確定申告を自動化する Agent Skill "shinkoku" を OSS にした

確定申告、めんどくさくないですか？

年に1回しかやらないから毎年やり方を忘れる。レシートの山を前にしてうんざりする。帳簿をつけて、決算書を作って、税額を計算して、申告書を提出する――気が遠くなるほど長い道のりです。個人事業主やフリーランスの方なら、この苦しみに共感してもらえると思います。

「もう全部 AI にやらせたい」。そう思って作ったのが、確定申告を自動化する Agent Skill「shinkoku」です。この記事では、作った動機、できること、セットアップ方法、テストによる品質保証について紹介します。

https://github.com/kazukinagata/shinkoku

作った動機

私は毎年、確定申告の時期になると憂鬱な気持ちになっていました。

年に1回しかやらないから、去年の記憶なんて綺麗さっぱり消えているんですよね。「去年どうやったっけ？」が毎年の恒例行事で、結局ゼロから調べ直す羽目になります。

そして1年分のレシートと領収書の山。1枚ずつ確認して仕訳を切る作業は、地味なのに確実に心が折れます。

そこから帳簿付け、決算書、税額計算、申告書の提出と続くわけですが、このプロセスの長さがまた辛い。途中でミスに気づくと手戻りで余計に時間がかかります。

この苦行をもう繰り返したくない。そう思っていたところに、AI エージェントが汎用的なタスクでも丸投げできる品質になってきた。それなら確定申告も任せられるんじゃないか――そう思って作り始めました。

OSS にした動機

仕事柄、AI エージェントをいろいろ試しているためよく分かるのですが、エージェントはここ半年ほどで急激に賢くなり、コーディングだけじゃなく、確定申告のような「プログラミングとは関係ない面倒ごと」までこなせるようになっています。しかし、まだまだエンジニア以外の方にその認知は拡がっておらず、チャットと何が違うの？と思われる方も多いと思うのです。

そういった方々にこのスキルを試してもらって、AI エージェントってこんなことまで出来るのか、こうやって仕事を頼めばいいのか、などといったことを体感してもらいたいという狙いがあります。

shinkoku でできること

ざっくり言うと、書類の読み取り・整理から帳簿の記帳、e-Tax への入力代行まで、確定申告の全工程をエージェントと一緒に進められる Agent Skill です。個人事業主・会社員の所得税・消費税に対応しており、令和7年分（2025年課税年度）の税制に準拠しています。スラッシュコマンドで各ステップを明示的に呼び出すこともできますし、会話の流れからエージェントが適切なスキルを自動で選んでくれることもあります。

「確定申告したい」と伝えるだけでスキルが発動してあとは質問に答えていくだけ

たとえば、一番面倒な書類整理はほぼ自動化できます。レシート、領収書、請求書、源泉徴収票、医療費の領収書、ふるさと納税の受領証明書、控除証明書、支払調書――これらを画像・PDF・CSV・Excel のいずれかで作業ディレクトリに置くだけで、OCR 読取から仕訳入力まで自動で処理されます。OCR の結果は完璧ではないため、人間の目で確認することを推奨しますが、ゼロから手入力するのとは労力が段違いです。

また、セットアップ時には氏名・電話番号・住所・家族構成・担当税務署名といった基本情報の入力が必要です。一問一答で聞かれると地味に面倒ですが、shinkoku では「去年の確定申告書の PDF を見て」「ウェブで調べて」のように雑に頼むだけで済みます。エージェントが書類やウェブから情報を拾い、設定ファイルに反映してくれます。

さらに、最終ステップの e-Tax 入力もエージェントに任せられます。確定申告書等作成コーナーは画面数が多く手動での操作が大変ですが、shinkoku ではページ構造を事前に学習させているため、エージェントがスムーズに画面を遷移しながら計算結果を入力していきます。

AIがブラウザ操作して申告データ送信直前までを代行してくれる

メインワークフロー（9スキル）

スキル	説明
/setup	初回セットアップ。設定ファイル（shinkoku.config.yaml）の生成とデータベースの初期化
/assess	確定申告が必要かどうか、所得税・消費税の申告要否を判定
/gather	必要書類のチェックリストと取得先を案内
/journal	CSV・レシート・請求書・源泉徴収票を取り込み、複式簿記の仕訳を登録
/settlement	減価償却・決算整理仕訳の登録、残高試算表・損益計算書・貸借対照表の生成
/income-tax	所得税額を計算（所得控除・税額控除・復興特別所得税）
/consumption-tax	消費税額を計算（2割特例・簡易課税・本則課税）
/submit	最終確認チェックリストと提出方法（e-Tax / 郵送 / 持参）の案内
/e-tax	確定申告書等作成コーナーへの入力代行（Claude in Chrome / Playwright / Antigravity）

補助スキル（5スキル）

スキル	説明
/tax-advisor	控除・節税・税制についての質問に回答する税務アドバイザー
/furusato	ふるさと納税の寄附金登録・一覧・削除・集計と控除限度額推定
/invoice-system	インボイス制度関連の参照情報
/capabilities	shinkoku の対応範囲・対応ペルソナ・既知の制限事項を表示
/incorporation	法人成り（個人事業主から法人への移行）の税額比較・設立手続き相談

OCR 読取スキル（5スキル）

スキル	読取対象
/reading-receipt	レシート・領収書・ふるさと納税受領証明書
/reading-withholding	源泉徴収票
/reading-invoice	請求書
/reading-deduction-cert	控除証明書（生命保険料・地震保険料等）
/reading-payment-statement	支払調書

対象ユーザー

「自分の申告パターンは対応してるの？」と気になると思うので、まとめました。

対象	対応レベル	備考
個人事業主（青色申告・一般用）	Full	メインターゲット。帳簿 → 決算書 → 税額計算 → 作成コーナー入力
会社員 + 副業（事業所得）	Full	源泉徴収票 + 事業所得の税額計算 → 作成コーナー入力
給与所得のみ（会社員）	Full	還付申告・医療費控除等 → 作成コーナー入力
消費税課税事業者	Full	2割特例・簡易課税・本則課税すべて対応
ふるさと納税利用者	Full	寄附金 CRUD + 控除計算 + 限度額推定
住宅ローン控除（初年度）	Full	控除額計算（添付書類は別途必要）
医療費控除	Full	明細集計＋控除額計算
仮想通貨トレーダー	Full	雑所得（総合課税）として申告書に自動反映

非対応項目

正直に言うと、まだカバーしきれていない領域があります。

対象	理由
株式投資家（分離課税）	株式譲渡所得・配当の分離課税
FX トレーダー	先物取引に係る雑所得等
不動産所得	不動産所得用の決算書・申告
退職所得	退職所得控除の計算
譲渡所得（不動産売却）	長期/短期税率、3,000万円特別控除
外国税額控除	外国税支払額の追跡・控除計算
農業所得・山林所得	専用所得区分
白色申告	青色申告のみ対応
非居住者	日本居住者専用

分離課税や不動産所得など、専用の計算ロジックが必要なケースは手つかずです。ニーズの高いものから順に対応していきたいと思っています。

対応エージェント

shinkoku は Claude Code と Cowork をメインターゲットとして開発しています。

ただ、せっかく作ったものを特定のエージェントでしか使えないのはもったいないと思い、SKILL.md オープン標準に準拠しました。そのおかげで Cursor / Windsurf / GitHub Copilot / Gemini CLI / Codex / Cline / Roo Code / Antigravity など、40 以上のエージェントでも利用できます。

なお、OCR 読取スキル（レシートや源泉徴収票の読取など）を使うには、マルチモーダル LLM に対応したエージェントが必要です。一部のプラットフォームでは、OCR デュアル検証（2つのサブエージェントで独立に読み取り、結果をクロスチェックする方式）にも対応しています。

セットアップ

導入は簡単です。環境さえ揃っていれば数分で終わります。

前提条件

• Python 3.11 以上
• uv パッケージマネージャ

Claude Code の場合

Cowork の場合

プラグイン > 個人用 > GitHub からマーケットプレイスを追加 > kazukinagata/shinkoku を入力してマーケットプレイスを追加し、その後表示される shinkoku プラグインをインストールしてください。

その他のエージェント

README.md を読ませてセットアップさせるのがおすすめです。skills CLI でもインストールできます。

テストカバレッジ

正直、自分でも「AI に税額計算させて大丈夫なのか？」と不安でした。だからこそ、テストはかなり手厚く書いています。税法の条文に基づいたテストケースを多数用意し、計算ロジックの正しさを担保しています。

テスト構造

15 のテストスイート、合計 238 のテストケースで構成しています。内訳は unit テスト（10スイート / 140ケース）と scripts テスト（5スイート / 98ケース）です。

テストスイート	テストケース数	内容
test_config.py	43	設定ファイルのバリデーション
test_ledger.py	40	帳簿
test_import_data.py	23	データインポート
test_sanity_check.py	21	サニティチェック
test_consumption_tax_rounding.py	19	消費税の端数処理
test_tax_calc.py	19	税額計算
test_furusato.py	11	ふるさと納税
test_db.py	10	データベース操作
test_income_tax_rounding.py	9	所得税の端数処理
test_master_accounts.py	9	勘定科目マスタ
test_opening_balance.py	8	開始残高
test_blue_return_cap.py	7	青色申告控除の上限
test_duplicate_detection.py	7	重複仕訳の検出
test_hashing.py	7	ハッシュ計算
test_profile.py	5	プロファイル

税法条文に基づくテスト

「なんとなく合ってそう」では怖いので、テストケースは税法の条文を直接根拠にしています。

• 国税通則法 第118条: 課税所得金額は1,000円未満切捨
• 国税通則法 第119条: 納付税額は100円未満切捨
• 消費税法 第28条: 課税標準 = 課税資産の譲渡等の対価の額
• 消費税法 第45条: 消費税額の計算
• 復興財源確保法 第13条: 復興特別所得税 = 基準所得税額 x 2.1%

端数処理の境界値テスト

税額計算で地味にハマるのが端数処理です。切り捨てのタイミングを1つ間違えると税額がずれるので、境界値を重点的にテストしています。

• 課税所得の1,000円未満切捨（国税通則法118条）
• 納付税額の100円未満切捨（国税通則法119条）
• 復興特別所得税の1円未満切捨（復興財源確保法13条）
• 還付額は100円切捨なし（1円単位）

サニティチェック（10項目）

テストを通っても、実データで変な結果が出ることはあり得ます。そこで、明らかにおかしい計算結果を早期に弾くためのサニティチェックを10項目設けています。

1. BLUE_DEDUCTION_ON_LOSS - 赤字なのに青色申告控除が適用されている
2. BLUE_DEDUCTION_EXCEEDS_PROFIT - 控除が利益を超過
3. LARGE_BUSINESS_LOSS - 事業損失が1,000万円超
4. TAX_ON_ZERO_INCOME - 課税所得0なのに税額発生
5. NEGATIVE_TOTAL_INCOME - 合計所得が負
6. TAXABLE_INCOME_ROUNDING - 課税所得が1,000円単位でない
7. RECONSTRUCTION_TAX_MISMATCH - 復興特別所得税の計算不一致
8. CREDITS_EXCEED_TAX - 税額控除が算出税額超過
9. NO_WITHHOLDING_ON_SALARY - 給与ありなのに源泉徴収0
10. REFUND_EXCEEDS_WITHHELD - 還付額が源泉徴収+予定納税の合計超過

CI/CD パイプライン

GitHub Actions で以下を実行しています。

• Lint: Ruff（pre-commit）+ mypy 型チェック
• Test: Python 3.11 / 3.12 のマトリクステスト（unit + integration）
• Coverage: pytest-cov でカバレッジ測定

freee との比較検証

テストを書いても、やっぱり「自分の実データで本当に合ってるのか？」が一番気になるところです。テストケースはあくまで架空のデータなので、実際の申告とは条件が違います。

そこで、自分自身の実データを使って freee でも確定申告書を作成し、shinkoku の出力と突き合わせてみました。freee は広く使われている確定申告ソフトなので、比較対象として信頼できます。

結果、shinkoku の計算結果と freee の出力は一致しました。正直、ホッとしました。

これは自動テストではなく手動での検証なので、サンプル数は限られています。それでも、メジャーな確定申告サービスと同じ結果が出たのは、一定の安心材料にはなるはずです。

最後に

自分自身、shinkoku を使うようになって確定申告が劇的に楽になりました。毎年あれだけ憂鬱だった作業が、エージェントとの対話で淡々と片付いていく。この体験を自分だけのものにしておくのはもったいないと思い、OSS にしました。

今後は分離課税や不動産所得など、対応範囲を広げていきます。コントリビュートも歓迎していますので、興味のある方はぜひ GitHub リポジトリを覗いてみてください。

ひとつ補足すると、shinkoku のコードやドキュメントはあえてすべて日本語で書いています。非エンジニアの方でも Issue を立てたり、ドキュメントを直したりできるようにしたかったからです。AI エージェントがコードを書いてくれる時代になれば、エンジニアと非エンジニアの境界はどんどん溶けていくはずです。確定申告に詳しい方、税務の実務を知っている方――そういう方々がプロジェクトに参加してくれたら、shinkoku はもっと良くなります。

なお、shinkoku の出力は提出前にご自身で内容を確認してください。判断に迷う場合は税理士に相談することをおすすめします。

https://github.com/kazukinagata/shinkoku

エピローグ：作成コーナーに行き着くまで

最初は xtx ファイル（e-Tax の電子申告データ、中身は XML）を直接生成するアプローチを試しました。PDF の出力も検討しました。プログラムで申告データを作れれば、ブラウザを操作する必要がなくなるからです。

ただ、実際に手を動かしてみると、xtx を正しく組み立てる工数がかなり大きいです。しかも仮に生成できたとしても、その後の電子署名・送信・受信通知の確認といった手作業はなくなりません。PDF も同様で、印刷して郵送か持参する手間が残ります。結局、人間の負担はあまり減りません。

それなら確定申告書等作成コーナーの画面操作をエージェントに任せて、入力から送信まで一気通貫で完結させた方がいい。回り道をした末の結論でした。

――ここからは完全に個人的なぼやきです。

このプロジェクトを通じて痛感したのは、国が作るシステムの歪さです。e-Tax には xtx という電子申告フォーマットがあるのに、個人の確定申告は確定申告書等作成コーナーに誘導されます。作成コーナーでは xtx のアップロードができません。作成コーナー独自の保存形式（.data）は仕様が非公開です。つまり、プログラムから申告データを流し込む正規のルートが、個人には用意されていません。

そしてふと気づいたのですが、この使いづらさの上に士業のビジネスが成り立っている面があります。制度が複雑だから専門家に頼む。システムが分かりにくいから代行を依頼する。国が生み出す負の体験が、そのまま市場になっています。

もちろん、税理士の方々の専門知識には大きな価値があります。でも「システムが難しいから頼む」と「判断が難しいから頼む」は別の話です。前者はテクノロジーで解消できるはずですし、解消されるべきだと思っています。

参考資料

• shinkoku GitHub リポジトリ
• SKILL.md オープン標準
• Claude Code
• Cowork