furusato

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ふるさと納税管理（Furusato Nozei Management）

Furusato Nozei Management

ふるさと納税の寄附金受領証明書を読み取り、寄附データを管理し、控除額を計算するスキル。

This skill reads furusato nozei donation receipts, manages donation data, and calculates deduction amounts.

設定の読み込み（最初に実行）

Load Settings (Run First)

```
shinkoku.config.yaml
```
を Read ツールで読み込む
ファイルが存在しない場合は
```
/setup
```
スキルの実行を案内して終了する
設定値を把握する:
- ```
db_path
```
  : CLI スクリプトの
```
--db-path
```
  引数に使用（CWD基準で絶対パスに変換）
- ```
tax_year
```
  : 対象年度
- ```
furusato_receipts_dir
```
  : 受領証明書の格納ディレクトリ（任意）

Read the
```
shinkoku.config.yaml
```
file using the Read tool
If the file does not exist, guide the user to run the
```
/setup
```
skill and exit
Understand the configuration values:
- ```
db_path
```
  : Used for the
```
--db-path
```
  argument of the CLI script (convert to absolute path based on CWD)
- ```
tax_year
```
  : Target fiscal year
- ```
furusato_receipts_dir
```
  : Storage directory for donation receipts (optional)

進捗情報の読み込み

Load Progress Information

設定の読み込み後、引継書ファイルを読み込んで前ステップの結果を把握する。

```
.shinkoku/progress/progress-summary.md
```
を Read ツールで読み込む（存在する場合）
以下の引継書を Read ツールで読み込む（存在する場合）:
- ```
.shinkoku/progress/01-setup.md
```
読み込んだ情報を以降のステップで活用する（ユーザーへの再質問を避ける）
ファイルが存在しない場合はスキップし、ユーザーに必要情報を直接確認する

After loading settings, read handover files to understand the results of previous steps.

Read
```
.shinkoku/progress/progress-summary.md
```
using the Read tool (if it exists)
Read the following handover files using the Read tool (if they exist):
- ```
.shinkoku/progress/01-setup.md
```
Utilize the read information in subsequent steps (avoid re-asking users)
If the files do not exist, skip this step and directly confirm necessary information with the user

ステップ1: 受領証明書の画像読み取り

Step 1: Read Receipt Images

1-1. ファイルの確認

1-1. File Verification

import_data.py furusato-receipt --file-path PATH

でファイルの存在を確認する。

Verify the existence of the file using

import_data.py furusato-receipt --file-path PATH

1-2. 画像の読み取り

1-2. Image Reading

重要: 画像の読み取りは対応する reading- スキルに委任する。*

Important: Delegate image reading to the corresponding reading- skill.*

単一の受領証明書の場合

For a Single Receipt

画像ファイルの読み取りには

/reading-receipt

スキルを使用する。スキルの指示に従い、デュアル検証（2つの独立した読み取り結果の照合）を行って結果を取得する。

結果照合: 両方の読み取り結果から

amount

date

municipality_name

を比較する

一致の場合: そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告

不一致の場合: ユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:

差異のあるフィールドを明示する
A を採用 / B を採用 / 手動入力の3択を AskUserQuestion で提示する

読み取り結果の

---FURUSATO_RECEIPT_DATA---

ブロックから以下の情報を取得する:

自治体名: 寄附先の市区町村名
都道府県名: 寄附先の都道府県
寄附金額: 円単位の整数
寄附日: YYYY-MM-DD 形式
受領証明書番号: 記載があれば

Use the

/reading-receipt

skill to read the image file. Follow the skill's instructions to perform dual verification (compare results from two independent readings) and obtain the results.

Result Comparison: Compare

amount

date

, and

municipality_name

from both reading results

If Matched: Adopt the result directly. Report "Results matched in two independent readings"

If Not Matched: Present the original image path and both results to the user, and ask them to select the correct one:

Clearly indicate fields with discrepancies
Provide three options via AskUserQuestion: Adopt A / Adopt B / Manual Input

Extract the following information from the

---FURUSATO_RECEIPT_DATA---

block of the reading results:

Municipality Name: Name of the city/town/village where the donation was made
Prefecture Name: Prefecture of the donation recipient
Donation Amount: Integer in yen
Donation Date: Format YYYY-MM-DD
Receipt Number: If available

複数の受領証明書を一括処理する場合

For Batch Processing of Multiple Receipts

Glob ツールで受領証明書画像の一覧を取得する（例:
```
furusato_receipts/*.jpg
```
,
```
furusato_receipts/*.png
```
）

shinkoku import furusato-receipt --file-path PATH

で各ファイルの存在を確認する

画像ファイルの読み取りには
```
/reading-receipt
```
スキルを使用する。スキルの指示に従い、デュアル検証（2つの独立した読み取り結果の照合）を行って結果を取得する。
結果照合: ファイル単位で両方の読み取り結果の
```
amount
```
,
```
date
```
,
```
municipality_name
```
を比較する
一致の場合: そのまま採用。「2つの独立した読み取りで結果が一致しました」と報告

不一致の場合: 不一致のファイルについてユーザーに元画像パスと両方の結果を提示し、正しい方を選択してもらう:
- 差異のあるフィールドを明示する
- A を採用 / B を採用 / 手動入力の3択を AskUserQuestion で提示する
各証明書の結果をまとめてユーザーに提示する

Use the Glob tool to retrieve a list of receipt images (e.g.,
```
furusato_receipts/*.jpg
```
,
```
furusato_receipts/*.png
```
)

Verify the existence of each file using

shinkoku import furusato-receipt --file-path PATH

Use the
```
/reading-receipt
```
skill to read each image file. Follow the skill's instructions to perform dual verification (compare results from two independent readings) and obtain the results.
Result Comparison: Compare
```
amount
```
,
```
date
```
, and
```
municipality_name
```
from both reading results for each file
If Matched: Adopt the result directly. Report "Results matched in two independent readings"

If Not Matched: For the mismatched file, present the original image path and both results to the user, and ask them to select the correct one:
- Clearly indicate fields with discrepancies
- Provide three options via AskUserQuestion: Adopt A / Adopt B / Manual Input
Compile the results of all receipts and present them to the user

1-3. ユーザーに確認

1-3. Confirm with User

抽出した情報を一覧表示し、正しいか確認する。修正があればユーザーの入力を反映する。

Display the extracted information as a list and confirm its accuracy. Reflect any corrections provided by the user.

ステップ2: 寄附データの登録

Step 2: Register Donation Data

確認が完了したら

furusato.py add

で登録する。

bash

shinkoku furusato add --db-path DB --input FILE

入力 JSON ファイルのフォーマット:

json

{
  "fiscal_year": 2025,
  "municipality_name": "自治体名",
  "amount": 30000,
  "date": "2025-06-15",
  "municipality_prefecture": "都道府県",
  "receipt_number": "受領証明書番号",
  "one_stop_applied": false
}

Once confirmed, register the data using

furusato.py add

bash

shinkoku furusato add --db-path DB --input FILE

Format of the input JSON file:

json

{
  "fiscal_year": 2025,
  "municipality_name": "Municipality Name",
  "amount": 30000,
  "date": "2025-06-15",
  "municipality_prefecture": "Prefecture",
  "receipt_number": "Receipt Number",
  "one_stop_applied": false
}

ワンストップ特例の確認

Confirm One-Stop Special Application

登録時に「ワンストップ特例を申請しましたか？」と確認する。

重要な注意: 副業で確定申告する場合、ワンストップ特例は無効化される。確定申告時に全額を寄附金控除として申告する必要がある。

During registration, confirm with the user: "Did you apply for the one-stop special treatment?"

Important Note: If you file a final tax return for side income, the one-stop special treatment will be invalidated. You need to declare the full amount as a donation deduction when filing your final tax return.

ステップ3: 複数の証明書を繰り返し処理

Step 3: Process Multiple Receipts Repeatedly

「他に受領証明書はありますか？」と確認し、あればステップ1~2を繰り返す。

Ask the user: "Do you have other donation receipts?" If yes, repeat Steps 1-2.

ステップ4: 集計と控除上限チェック

Step 4: Aggregation and Deduction Limit Check

すべての寄附データを登録したら

furusato.py summary

で集計する。

bash

shinkoku furusato summary --db-path DB --fiscal-year YEAR [--estimated-limit N]

表示する情報:

寄附先自治体数と合計金額
所得控除額（合計 - 2,000円）
ワンストップ特例申請数
控除上限の推定（所得情報がある場合）

After registering all donation data, aggregate the data using

furusato.py summary

bash

shinkoku furusato summary --db-path DB --fiscal-year YEAR [--estimated-limit N]

Information to display:

Number of recipient municipalities and total donation amount
Income deduction amount (total - 2,000 yen)
Number of one-stop special applications
Estimated deduction limit (if income information is available)

控除上限の推定

Estimate Deduction Limit

所得情報が把握できている場合は

tax_calc.py furusato-limit

で上限を推定する。

bash

shinkoku tax furusato-limit --input FILE

上限超過の場合は警告を表示: 「寄附合計額が推定上限を超えています。超過分は自己負担となります。」

If income information is available, estimate the limit using

tax_calc.py furusato-limit

bash

shinkoku tax furusato-limit --input FILE

If the limit is exceeded, display a warning: "Total donations exceed the estimated limit. The excess amount will be your out-of-pocket expense."

ステップ5: 確定申告との関係

Step 5: Relationship with Final Tax Return

以下を説明する:

副業で確定申告する場合、ワンストップ特例は使えない
確定申告で寄附金控除（所得控除）として申告する
所得税からの控除 = (寄附合計 - 2,000) x 所得税率
住民税からの控除は別途計算される（特例分含む）

Explain the following:

If you file a final tax return for side income, you cannot use the one-stop special treatment
Declare the donation as a donation deduction (income deduction) in your final tax return
Deduction from income tax = (total donations - 2,000) × income tax rate
Deduction from resident tax is calculated separately (including special treatment amounts)

リファレンスファイル参照ガイド

Reference File Reference Guide

質問カテゴリ	参照ファイル
ふるさと納税の税制ルール・計算式	`references/furusato-tax-rules.md`
上限額・返礼品・タイミング・相談全般	`references/furusato-consultation-guide.md`

Question Category	Reference File
Furusato nozei tax rules and calculation formulas	`references/furusato-tax-rules.md`
Limit amount, return gifts, timing, general consultation	`references/furusato-consultation-guide.md`

次のステップの案内

Next Step Guidance

```
income-tax
```
スキルで所得税の計算に進む（寄附金控除が自動反映される）
他の控除（医療費控除等）がある場合は先にそちらを処理する

Proceed to calculate income tax using the
```
income-tax
```
skill (donation deductions will be automatically reflected)
If you have other deductions (e.g., medical expense deduction), process those first

引継書の出力

Output Handover Files

サマリー提示後、以下のファイルを Write ツールで出力する。これにより、セッションの中断や Compact が発生しても次のステップで結果を引き継げる。

After presenting the summary, output the following files using the Write tool. This allows subsequent skills to inherit the results even if the session is interrupted or compacted.

ステップ別ファイルの出力

Output Step-Specific File

.shinkoku/progress/05-furusato.md

に以下の形式で出力する:

---
step: 5
skill: furusato
status: completed
completed_at: "{当日日付 YYYY-MM-DD}"
fiscal_year: {tax_year}
---

Output to

.shinkoku/progress/05-furusato.md

in the following format:

---
step: 5
skill: furusato
status: completed
completed_at: "{Current Date YYYY-MM-DD}"
fiscal_year: {tax_year}
---

ふるさと納税管理の結果

Furusato Nozei Management Results

登録済み寄附一覧

List of Registered Donations

自治体名	都道府県	金額	寄附日	ワンストップ
{自治体名}	{都道府県}	{金額}円	{日付}	{申請済み/未申請}

Municipality Name	Prefecture	Amount	Donation Date	One-Stop
{Municipality Name}	{Prefecture}	{Amount} yen	{Date}	{Applied/Not Applied}

集計

Aggregation

寄附先自治体数: {件数}
寄附合計額: {合計金額}円
控除額（合計 - 2,000円）: {控除額}円

Number of recipient municipalities: {Count}
Total donation amount: {Total Amount} yen
Deduction amount (total - 2,000 yen): {Deduction Amount} yen

控除上限との比較

Comparison with Deduction Limit

推定控除上限: {上限額}円（所得情報がある場合）
上限超過: {なし/あり（超過額: {金額}円）}

Estimated deduction limit: {Limit Amount} yen (if income information is available)
Limit exceeded: {No/Yes (Excess amount: {Amount} yen)}

次のステップ

Next Step

/income-tax で所得税の計算に進む


寄附がない場合（スキップ）は status を `skipped` とし、内容は「該当なし」と記載する。

Proceed to income tax calculation with /income-tax


If there are no donations (skipped), set status to `skipped` and write "Not applicable" in the content.

進捗サマリーの更新

Update Progress Summary

.shinkoku/progress/progress-summary.md

を更新する（存在しない場合は新規作成）:

YAML frontmatter: fiscal_year、last_updated（当日日付）、current_step: furusato
テーブル: 全ステップの状態を更新（furusato を completed または skipped に）
次のステップの案内を記載

Update

.shinkoku/progress/progress-summary.md

(create a new one if it does not exist):

YAML frontmatter: fiscal_year, last_updated (current date), current_step: furusato
Table: Update the status of all steps (set furusato to completed or skipped)
Guidance on next steps

出力後の案内

Guidance After Output

ファイルを出力したらユーザーに以下を伝える:

「引継書を
```
.shinkoku/progress/
```
に保存しました。セッションが中断しても次のスキルで結果を引き継げます。」
次のステップの案内

After outputting the files, inform the user:

"Handover files have been saved to
```
.shinkoku/progress/
```
. Even if the session is interrupted, subsequent skills can inherit the results."
Guidance on next steps