tax-filing

税務申告スキル

連邦および州の所得税申告書を作成します。原資料を読み、税額を計算し、公式 PDF フォームに記入します。

年を問わず使用可能 — 必ず該当年の税率区分、控除、税額控除を調べてください。前年の数値は再利用しないでください。

フォルダー構成

作業ディレクトリ内のサブフォルダーにすべての作業を整理します。

working_dir/
  source/              ← user's source documents (W-2, 1099s, prior return, CSVs)
  work/                ← ALL intermediate files (extracted data, field maps, computations)
    tax_data.txt       ← extracted figures from source docs
    computations.txt   ← all tax math (federal, state, capital gains)
    f1040_fields.json  ← field discovery dumps
    f8949_fields.json
    f1040sd_fields.json
    ca540_fields.json
    expected_*.json    ← verification expected values
  forms/               ← blank downloaded PDF forms
    f1040_blank.pdf
    f8949_blank.pdf
    f1040sd_blank.pdf
    ca540_blank.pdf
  output/              ← final filled PDFs + fill script
    fill_YEAR.py       ← the fill script
    f1040_filled.pdf
    f8949_filled.pdf
    f1040sd_filled.pdf
    ca540_filled.pdf

最初にこれらのフォルダーを作成してください。作業ディレクトリを整理し、ファイルをむき出しのまま置かないでください。

コンテキスト予算のルール

これらのルールは、コンテキストの肥大化による圧縮を防ぎます。

1. Read ツールで PDF を絶対に読まないでください。 各ページは約 250KB の base64 画像になります（9 ページの申告書なら 1.8 MB）。代わりにテキストを抽出してください：

   python3 -c "
   import pdfplumber
   with pdfplumber.open('source/document.pdf') as pdf:
       for p in pdf.pages: print(p.extract_text())
   "
   

2. 同じ文書を二度読まないでください。 最初に読み取ったときに、抽出した数値を work/tax_data.txt に保存してください。
3. 各フォームのフィールド検出は一度だけ実行し、JSON を一括で work/ に出力してください。--search を繰り返し使わないでください。
4. 計算した値はすべて work/computations.txt に保存し、圧縮後も保持できるようにしてください。

ワークフロー

ステップ 1：原資料を収集する

ユーザーに所持している書類を確認してください。source/ からファイルを読み込みます（必要に応じてそこへ移動してください）。PDF には pdfplumber、CSV には Read ツールを使用してください。

抽出した数値はすべて、各文書につき 1 セクションにまとめ、関連するすべての数値を記載して、直ちに work/tax_data.txt に保存してください。

ステップ 2：申告内容を確認する — 必須

次に進む前に、以下の質問を必ずすべてユーザーに行い、回答を待ってください。 記憶や原資料から回答を知っていると思っても、この手順を省略しないでください。税務申告書は法的文書です。

• 申告資格（Single、MFJ、MFS、HOH、QSS）
• 扶養家族（人数、氏名）
• 居住州
• 標準控除と項目別控除のどちらを選ぶか
• デジタル資産／暗号資産の取引（はい／いいえ）— 株式取引はデジタル資産ではありません
• 医療保険の加入状況（CA の場合）
• 概算納税の有無
• その他の税額控除または調整

ユーザーの回答を得るまで、ステップ 3 に進まないでください。 「昨年と同じ」という回答も確認として扱います。

ステップ 3：該当年の数値を調べる

IRS.gov および FTB.ca.gov で次の情報を調査してください。

• 連邦税率区分、標準控除、QDCG の 0%／15%／20% の基準額
• 州税率区分、標準控除、個人控除の税額控除

work/computations.txt に保存してください。

ステップ 4：連邦申告書を計算する

1. 総所得：W-2 賃金（1a）＋利子（2b）＋配当（3b）＋キャピタルゲイン／ロス（7）
2. 調整額 → AGI（11 行目）
3. 控除 → 課税所得（15 行目）
4. 税額：適格配当／キャピタルゲインがある場合は QDCG ワークシートを使用
5. 税額控除、その他の税金 → 合計税額（24 行目）
6. 納付額（源泉徴収、概算納税）→ 還付／納付
7. 還付の場合：口座振込情報（ルーティング番号、口座番号、口座種別）を確認

各行の値をすべて work/computations.txt に保存してください。

ステップ 5：キャピタルゲインを計算する（該当する場合）

1. Form 8949：個別の取引（Part I は短期、Part II は長期）
2. Schedule D：合計、3,000 ドルの損失限度、繰越額の計算
3. 純損益 → 1040 の 7 行目

丸め規則：Form 8949 と Schedule D では、1099-B／1099-DA の原資料と一致する正確なセント単位を使用してください。整数ドルへの丸めは Form 1040 のみで行います（7 行目 = Schedule D の 16 行目を丸めた値）。8949 または Schedule D の金額は丸めないでください。

ステップ 6：州申告書を計算する（CA Form 540）

1. 連邦 AGI → CA の調整 → CA の課税所得
2. 税率区分に基づく税額 − 控除の税額控除 → 合計税額
3. 源泉徴収 → 還付／納付

ステップ 7：未記入の PDF フォームをダウンロードする

forms/ ディレクトリに保存してください。

IRS：前年のフォームには /irs-prior/ を使用してください（/irs-pdf/ は常に現行年のフォームです）。

https://www.irs.gov/pub/irs-prior/f1040--YEAR.pdf
https://www.irs.gov/pub/irs-prior/f8949--YEAR.pdf
https://www.irs.gov/pub/irs-prior/f1040sd--YEAR.pdf

CA：州のフォームには ftb.ca.gov/forms/YEAR/ を使用してください。

各ダウンロードのヘッダーが %PDF- であることを確認してください（HTML のエラーページではないこと）。

ステップ 8：フィールド名を検出してフォームに記入する

検出 — フォームごとに1回だけ、--compact を使用

python scripts/discover_fields.py forms/f1040_blank.pdf --compact > work/f1040_fields.json
python scripts/discover_fields.py forms/f8949_blank.pdf --compact > work/f8949_fields.json
python scripts/discover_fields.py forms/f1040sd_blank.pdf --compact > work/f1040sd_fields.json
python scripts/discover_fields.py forms/ca540_blank.pdf --compact > work/ca540_fields.json

--compact は最小限の {field_name: description} マッピングを出力します。各フィールド名にはツールチップ／読み上げ用の説明が対応しているため、手作業で確認せずに行番号をフィールド名に直接対応づけられます。ラジオボタンには選択肢の値も含まれます（例：{"/2": "Single", "/1": "MFJ"}）。

--search を繰り返し使用したり、生のメタデータを出力してコンテキストを無駄にする --json を使用したりしないでください。

重大な失敗：検出で人が読める説明が0件の場合は、そこで停止してください。フィールド名を推測してはいけません。

入力スクリプト

scripts/fill_forms.py を使用して output/fill_YEAR.py を作成します。

• add_suffix(d) — テキストフィールドのキーに [0] を追加します。IRS のフォームで必須です。
• fill_irs_pdf(in, out, fields, checkboxes, radio_values) — IRS のフォームに使用します。radio_values は申告区分、はい／いいえ、当座／普通預金に使用します。
• fill_pdf(in, out, fields, checkboxes) — CA のフォームに使用します。/Parent の階層と /AP/N キーで照合します。

入力済み PDF は output/ に出力します。

ステップ9：検証

python scripts/verify_filled.py output/f1040_filled.pdf work/expected_f1040.json

失敗項目を修正し、入力スクリプトを再実行します。

ステップ10：結果の提示

概要表、検証チェックリスト、資本損失の繰越額（該当する場合）を提示してから、次の項目を提示します。

• 申告書への署名 — 署名のない申告書は受理されません
• 納付方法（納付額がある場合） — IRS Direct Pay、FTB Web Pay、期限は4月15日
• 直接振込 — 還付の場合は利用を推奨します。口座情報が未提供の場合は確認してください
• 申告方法 — 電子申告（Free File、CalFile）または郵送先住所

ステップ11：MFJ と Single の比較（夫婦合算申告の場合）

MFJ の申告書を作成した後、それぞれの配偶者が別々に Single で申告した場合の納付額を計算します。これにより、申告区分の選択による税額への影響を夫婦が把握できます。

各配偶者について、仮の Single 申告書を計算します。

1. 所得：その配偶者の W-2、1099-INT、1099-DIV、1099-B／1099-DA のみを使用します
2. 基礎控除：Single の金額（通常、MFJ の半額）
3. QBI 控除：その配偶者の 199A 配当のみを基に計算します
4. 税額：Single の税率区分と、Single の0％／15％／20％の基準額を用いた QDCG ワークシートを使用します
5. 税額控除：その配偶者が外国税を納めた場合に限り、外国税額控除を適用します
6. 追加メディケア税：MFJ の25万ドルではなく、Single の20万ドルの基準額を使用します
7. 源泉徴収額：その配偶者の W-2 の Box 2 のみを使用します

次の比較表を並べて提示します。

	MFJ（実際）	2人ともSingle	差額
合計税額
合計源泉徴収額
合計納付額

重要なポイントも記載します。特に、追加メディケア税の基準額の違い（MFJ は25万ドル、Single は配偶者ごとに20万ドル）を取り上げてください。これは、MFJ と Single の差額に最も大きく影響する要因であることがよくあります。

特に注意すべき点

コンテキスト

• PDF に Read ツールを使用してはいけません。pdfplumber を使用します
• 同じ書類を2回読んではいけません。work/tax_data.txt に保存します
• フィールド検出はフォームごとに1回だけ、--compact を使用します。--json はコンテキストを無駄にするため使用せず、--search も繰り返し使用しません

フィールド検出

• フィールド名は年によって変わるため、毎回必ず新たに検出します
• XFA テンプレートは /AcroForm → /XFA 配列にあります。XREF を総当たりでスキャンして探してはいけません
• XFA に xml.etree を使用してはいけません。正規表現を使用します（IRS の XML では名前空間が壊れているためです）

PDF への入力

• AcroForm から XFA を削除し、NeedAppearances=True を設定して、auto_regenerate=False を使用します
• チェックボックス：/V と /AS の両方を /1 または /Off に設定します
• IRS のフィールドには [0] のサフィックスが必要です。add_suffix() を使用します
• IRS のチェックボックスは /T で直接照合します。ラジオグループは radio_values を介して /AP/N キーで照合します

端数処理

• Form 8949 と Schedule D：1099-B／1099-DA の原本書類と一致するよう、セント単位まで正確に記載します（例：「11.36」「-240.00」）。端数処理をしてはいけません。
• Form 1040：IRS の指示に従い、すべての金額を最も近い整数ドルに丸めます。7行目（キャピタルゲイン）は Schedule D の16行目を最も近い整数ドルに丸めた金額です。
• CA 540：最も近い整数ドルに丸めます。

フォーム固有

• 1040：最初の数項目（f1_01～f1_03）は氏名欄ではなく、会計年度の見出しです。SSN は 9 桁で、ハイフンは付けません。デジタル資産は暗号資産のみで、株式は含みません。
• 8949：ボックス A/B/C のチェックボックスは 3 択のラジオボタンです。合計欄はフィールド番号の大きい位置（例：f1_115～f1_119）にあり、最後のデータ行の後ではありません。スケジュール D の 1b/8b 行（8949 からの転記）を使用し、1a/8a 行は使用しません。
• Schedule D：一部のフィールドには _RO（読み取り専用）という接尾辞が付いています。これらはスキップしてください。
• CA 540：フィールド名は 540-PPNN（ページ＋連番で、行番号ではありません）です。チェックボックスの末尾は " CB"、ラジオボタンには名前付きの AP キーを使用します。
• ダウンロード：前年度の IRS は irs.gov/pub/irs-prior/、当年度は irs.gov/pub/irs-pdf/ です。