mindxassociates/practice-books-kit

Practice Books Kit — セラピー開業医向け簿記＋給与計算

目的

開業医に完全で再現可能なお金のシステムを提供します。以下の2つのパートで構成されます。

• Part A — 月次簿記。 エージェントにその月の銀行・カード明細を渡します。エージェントはすべての取引を固定勘定科目表に分類し、損益計算書（P&L）の1カ月分の列を埋め、月次決算が合致することを確認してから報告します。
• Part B — Practice Booksアプリ。 エージェントが構築・デプロイする、管理者専用の小規模なWebアプリです。業務委託先（1099）および従業員（W-2）の月次給与計算（支給実行、明細、年次サマリー）と、Part Aの損益計算書を可視化する読み取り専用の財務ダッシュボードを提供します。

この2つのパートは相互に補完し合います。アプリの業務委託費は損益計算書と照合でき、ダッシュボードにより事業主はワークブックを開かなくても常に最新の数値を確認できます。

エージェントへの引き継ぎ方（このキットを受け取る同僚向け）

AIエージェントにこのフォルダ全体を渡し、以下の手順を実行します。

1. 以下のセットアップインタビューに答える — エージェントは何よりも先に、これらの質問を一度だけ行う必要があります。
2. references/categories.md の勘定科目表を確認する — カテゴリ名と順序は、実際に該当しないカテゴリがない限り変更しないでください。エージェントは最初の記入前に確認する必要があります。
3. 1カ月分の明細を渡し、エージェントに最初の記入をさせます。その調整結果と判断を要する項目リストを確認し、必要に応じて一度だけ修正します。エージェントはその修正を恒久的なルールとして記録し、以降の月に適用します。

セットアップインタビュー（一度だけ収集し、書き留めて、毎月再利用する）

エージェントは、最初の記入またはアプリ構築の前に、以下の情報を必ず収集し、決して推測してはいけません。

• 事業所： 正式名称、事業主名、事業を行う州、法人形態。
• 口座（識別には下4桁で十分）：
  • 主事業用当座預金（保険会社からの収入が入金される口座）。
  • 給与サブ口座（業務委託先への支払いに使用する場合）。
  • 税金/積立サブ口座（ある場合。そこへの振替は内部取引）。
  • 事業用クレジットカード。
  • 事業主の個人/資産管理口座（振替の受取先。事業主引き出しを認識するために必要）。
• 明細： 事業主が毎月どのように明細を提供するか（CSVエクスポート推奨、銀行がそれしか提供しない場合はPDF）、および月を特定する日付列（取引日。事業主が別途指示しない限り、処理日ではない）。
• 支払い慣行： デフォルトは 前月分の労働に対して当月1日に支払う。実際の慣行を確認または記録します。
• 従業員と支払条件（Part B用）：すべての業務委託先/従業員、その種別（1099またはW-2）、正確な支払条件（回収額のパーセンテージ、セッション固定料金、時給、または月給）、民間保険/スライディングスケールの分割がある場合、定額控除（例：EHRシステム利用料）。支払率を決して推測しないでください。 レートが不明な場合は、未設定のままフラグを立てます。
• 明細外収入： 銀行フィードに現れない収入を事業所がどのように受け取るかを明示的に尋ねます（例：Zelle/Venmo/現金/小切手による指導料や家賃）。これらの支払いは毎月、メールや支払いアラートから取り込む必要があります。そうしないと、損益計算書が収入を過小表示することになります。

Part A — 月次明細から損益計算書へのワークフロー

参照ファイル：references/categories.md（勘定科目表＋分類ガイド）および references/pl-sheet-spec.md（ワークブックのレイアウト、数式、記入手順）。これらに正確に従ってください。

1. その月のすべての明細を収集します。 主事業用当座預金、給与サブ口座、すべての事業用カード、および明細外収入の取り込み（手順2）。明細が不足している場合はその旨を伝え、提供された明細でサポートできる範囲のみを記入します — レポートでそのギャップを明記します（例：「給与サブ口座の明細が未入手のため、業務委託費は保留中」）。黙って埋めてはいけません。
2. フィード外収入を取り込みます。 事業主のメール/支払いアラートをその月分検索し（Zelle/Venmoの「入金通知」など）、確認された事業収入を発生元とともに元帳に追加します。同じ検索で見つかった個人収入は除外し、リスト化します。
3. すべての取引を解析します。 各明細から1つの元帳にまとめます：日付、元口座、説明、金額（入金は正、出金は負）。
4. 内部資金移動を除外します — これらは収入でも費用でもありません：
   • 事業所自身の口座間の振替（当座預金 ↔ 給与サブ口座 ↔ 税金サブ口座）。
   • 事業主の個人/資産管理口座への振り出し — これらは事業主引き出しであり、費用ではありません。
   • クレジットカードの支払い（自動引き落としまたは手動） — カードの購入が費用であり、支払いは単なる口座間の資金移動です。
5. 残りの取引をすべて分類します。 references/categories.md を使用します。給与口座からの業務委託先へのACH支払いは業務委託費に分類します。どのルールにも当てはまらない取引は、判断を要する項目リストに追加します — 黙って削除せず、事業主の承認なしに新しいカテゴリを作成しないでください。
6. カテゴリ別に集計します。 その月の列の値にします（費用は負の値）。
7. 月の列を書き込みます。 references/pl-sheet-spec.md に従います：カテゴリセルのみ、その後合計数式を記述し、書き込み結果（セル数）を確認してから信頼します。
8. 読み戻しと端数調整の確認を行います。 ワークブックに書き込まれた列を再読み取りし、独立して計算された元帳と照合します：
   • 分類された収入の合計 = 明細の入金合計から除外項目（内部振込、事業主ルールに従うカード返金）を差し引いたもの。
   • 分類された費用の合計 = 明細の出金合計から除外項目を差し引いたもの。
   • 元帳のすべての取引が、分類済み、理由付きで除外済み、または未分類としてリストアップされていること。 端数調整が合わない場合は、報告前に修正します — 調整が取れていない月を報告してはいけません。
9. 月次報告を行います。 事業主に報告します：収入、費用、純利益；年度累計；行った判断（金額付き）と事業主の裁定を恒久ルールとして記録したもの；未分類のもの；不足している明細。報告は事実に基づき完全であること — 事業主はこれを基に監査を行います。

Part A の厳格なルール

• 実績のみ。 明細からの実際の取引金額を使用します。月を「完全に見せる」ために見積もり、平均、年換算、または数値をでっち上げてはいけません。不完全な月は不完全として報告します。
• 手入力されたセルを決して上書きしないでください。 事業主がすでにセルに値を入力しており、それがあなたの値と異なる場合、事業主の値を保持し、レポートでその矛盾をフラグし、オープンに調整します — 既存の入力は通常、あなたが持っていない情報源からのものです。
• 費用はシート上では負の数値とします。合計数式はこれを前提としています。
• 払い戻しは該当費用から相殺し、収入として計上しないでください。 誰かが事業所が立替えた特定の費用を事業所に返済した場合（典型的なケース：業務委託先がグループEHRサブスクリプションの自分の利用料を返済する）、その返済を受け取った月の該当費用カテゴリから差し引きます。収入として総額表示すると、収入と費用の両方を過大表示します。
• 個人取引は除外し、報告書にリストします。 「念のため」カテゴリ分類してはいけません。
• 事業主の裁定を一貫して適用します。 事業主が一度分類を修正したら、そのルールを書き留め（メモリ/この事業所用のメモに）、毎月以降、再度尋ねることなく適用します。

Part B — Practice Booksアプリ

参照ファイル：references/app-spec.md — データモデル、給与ルール、実行ライフサイクル、財務データリーダー契約、チャートリスト、デプロイゲート。この仕様に従って構築します。

作業の流れ：

1. セットアップインタビューデータを確認します（特に従業員と支払条件）。推測したレートに基づいて財務関連の構築を一切行わないでください。
2. まずローカルで構築します。 サーバーとクライアントのコード、およびスプレッドシート層をスタブ化し、クライアントが送信する正確な引数形状ですべてのサーバー関数を呼び出すローカルテストハーネスを作成します。最低限、以下のカバレッジを確保します：支払ベース計算（パーセント / 固定 / 民間分割）、実行ライフサイクルガード（実行は承認前に支払済みを通過できない）、支払済み → 支払履歴への書き込み、1099 $600フラグ、W-2 FICA賃金基準額上限、および会計形式文字列に対する財務データパーサー。
3. ゲート付きでデプロイします。 コードをプッシュし、デプロイされたプロジェクトの内容を読み戻し、バージョンを作成する前に、テスト済みのローカルファイルとバイト単位で一致することを確認します — コンテンツが古いデプロイは、誰かがアプリを開くまで正常なデプロイと見分けがつきません。既存のデプロイメントを新しいバージョンにバンプします。新しいデプロイメントURLを作成しないでください（新しいURLごとに誰かがリンクを更新する必要があり、古いURLは古いコードを提供し続けます）。バンプ後、デプロイメントを再リストして、バージョンが実際に移動したことを確認します（デプロイメントリストはバンプから数秒遅れることがあります）。
4. 事業主の認可は一度限りの手動ステップです。 事業主が一度プロジェクトを開き、スコープ（スプレッドシート＋メール送信）を承認します。これまでは、アプリURLはアクセスエラーを表示します — これは期待される動作であり、バグではありません。
5. 初回実行時のチェックリスト： ロックを解除し、データワークブックが自動生成されたことを確認し、人物を同期/追加し、各人の支払ベースとレートを設定し、最初の（前月分の）給与実行をドラフトでドライランとして作成し、承認前に明細行を確認します。

アプリの境界（事前に事業主に明示すること）

• アプリは計算と記録のみを行います。税金の電子申告（1099/W-2/941）は行わず、送金や支払いも行わず、政府機関への提出も一切行いません。事業主は通常通り銀行から従業員に支払いを行い、アプリはそれが行われたことを記録します。
• W-2源泉徴収額は見積もりです（編集可能な税率表タブからの年換算パーセント方式）。事業主の公認会計士（CPA）が確認するためのものであり、申告準備完了として提示してはいけません。
• アプリのワークブックに完全なSSN/EINや銀行口座番号は保存しません。 「税務フォーム提出済み」/「ACH登録済み」フラグのみを保存し、完全な識別子は事業所の既存の安全なシステムに保持します。
• アプリは管理者専用です。事業主のサインインゲート（例：サーバー側で名簿と照合するPIN）があり、すべてのサーバー関数は呼び出し元の認可を再確認します。プロバイダー（提供者）がアプリを見ることはありません。プロバイダー自身の支払いビュー（ある場合）は、別の読み取り専用画面です。
• 財務ダッシュボードは読み取り専用です — アプリは損益ワークブックに書き込みを一切行いません。月次記入（Part A）が損益計算書に数値を入力する唯一の方法であり続けます。

エージェントの運用ルール

• 即興よりも参照ファイルに従います。参照とライブの指示が矛盾する場合、事業主の現在の指示が優先され、変更内容は書き留められます。
• 自己主張ではなく、成果物から検証します：書き込み後にシートを読み戻し、デプロイ後にデプロイされたコードを読み戻し、コード変更後にテストハーネスを実行します。
• ステップが失敗した場合、何が失敗したか、実際の状態はどうか、次に何が起こるかを報告します。開始したという理由だけで、記入、デプロイ、または支払い実行が完了したと報告してはいけません。