shinkoku
確定申告を自動化する AI コーディングエージェント向けプラグイン。個人事業主・会社員の所得税・消費税の確定申告を、帳簿の記帳から確定申告書等作成コーナーへの入力代行までエンドツーエンドで支援します。
Claude Code Plugin として動作するほか、SKILL.md オープン標準 に準拠した Agent Skills パッケージとして、Claude Code / Cursor / Windsurf / GitHub Copilot / Gemini CLI / Codex / Cline / Roo Code / Antigravity など 40 以上の AI コーディングエージェントで利用できます。
想定ユーザー
| 対象 | 対応レベル | 備考 |
|---|
| 個人事業主（青色申告・一般用） | Full | メインターゲット。帳簿 → 決算書 → 税額計算 → 作成コーナー入力 |
| 会社員 + 副業（事業所得） | Full | 源泉徴収票 + 事業所得の税額計算 → 作成コーナー入力 |
| 給与所得のみ（会社員） | Full | 還付申告・医療費控除等 → 作成コーナー入力 |
| 消費税課税事業者 | Full | 2割特例・簡易課税・本則課税すべて対応 |
| ふるさと納税利用者 | Full | 寄附金 CRUD + 控除計算 + 限度額推定 |
| 住宅ローン控除（初年度） | Full | 控除額計算（添付書類は別途必要） |
| 医療費控除 | Full | 明細集計＋控除額計算 |
| 仮想通貨トレーダー | Full | 雑所得（総合課税）として申告書に自動反映 |
非対応
以下のケースには対応していません。
| 対象 | 理由 |
|---|
| 株式投資家（分離課税） | 株式譲渡所得・配当の分離課税 |
| FX トレーダー | 先物取引に係る雑所得等 |
| 不動産所得 | 不動産所得用の決算書・申告 |
| 退職所得 | 退職所得控除の計算 |
| 譲渡所得（不動産売却） | 長期/短期税率、3,000万円特別控除 |
| 外国税額控除 | 外国税支払額の追跡・控除計算 |
| 農業所得・山林所得 | 専用所得区分 |
| 白色申告 | 青色申告のみ対応 |
| 非居住者 | 日本居住者専用 |
⚠️ 免責事項
確定申告は自己責任で行ってください。
- 本ツールが生成した申告書・計算結果は、提出前に必ずご自身で内容を確認してください
- 税法の解釈や申告内容に不安がある場合は、税理士等の専門家に相談することを強く推奨します
- 本ツールの利用によって生じたいかなる損害についても、開発者は責任を負いません
- 税制は毎年改正されます。本ツールは令和7年分（2025年課税年度）の税制に基づいています
インストール
前提条件
- Python 3.11 以上
- uv パッケージマネージャ
CLI のインストール
スキルが内部で shinkoku コマンドを呼び出します。通常は /setup スキルが自動でインストールしますが、手動で行う場合は以下を実行してください。
# インストール
uv tool install git+https://github.com/kazukinagata/shinkoku
# 更新
uv tool upgrade shinkoku
Cowork の場合は、チャットで Claude にインストールを依頼してください。
方法 1: Claude Code プラグイン（フル機能）
プラグイン機能を使い、OCR 画像読取を含む全機能を利用できます。
# マーケットプレイスを追加
/plugin marketplace add kazukinagata/shinkoku
# プラグインをインストール
/plugin install shinkoku@shinkoku
方法 2: スキルのみインストール（40+ エージェント対応）
skills CLI でスキルをインストールできます。
# スキルのインストール（インストール先エージェントを対話的に選択）
npx skills add kazukinagata/shinkoku
# 特定のエージェントにグローバルインストール
npx skills add kazukinagata/shinkoku -g -a claude-code -a cursor
# インストール可能なスキル一覧を確認
npx skills add kazukinagata/shinkoku --list
環境別の補足
| 環境 | 設定方法 |
|---|
| Claude Code | /plugin marketplace add kazukinagata/shinkoku → /plugin install shinkoku@shinkoku |
| Cowork | プラグイン > 個人用 > GitHub からマーケットプレイスを追加 > kazukinagata/shinkoku を入力してマーケットプレイスを追加し、その後表示される shinkoku プラグインをインストール |
| その他 | npx skills add kazukinagata/shinkoku でインストール（方法 2 を参照） |
ブラウザ自動化（e-Tax に必要）
/e-tax スキルでは、確定申告書等作成コーナーへの入力にブラウザ自動化が必要です。以下の3方式に対応しています。
| 方式 | 対象環境 | 備考 |
|---|
| Claude in Chrome（推奨） | Windows / macOS のネイティブ Chrome | Claude in Chrome 拡張機能が必要 |
| Antigravity Browser Sub-Agent | Windows / macOS / Linux | Antigravity IDE のブラウザ操作機能を利用 |
| Playwright CLI（β版） | WSL / Linux 等 | @playwright/cli のインストールが必要 |
Claude in Chrome の有効化（Claude Code）
Claude in Chrome を利用するには、Claude Code 起動時にフラグを付けるか、セッション内でコマンドを実行します。
# 起動時に有効化
claude --chrome
# セッション内で有効化
/chrome
Playwright CLI のインストール
Claude in Chrome, Antigravity を利用する場合このステップは不要です。
# パッケージインストール
npm install -g @playwright/cli@latest
# スキルインストール（エージェントがコマンドを認識するために必要）
playwright-cli install --skills
# Chromium インストール
npx playwright install chromium
WSL の場合、GUI 表示が必要です（headed モードで Chrome を操作するため）。Windows 11 では WSLg が標準搭載されており追加設定は不要です。Windows 10 では X Server（VcXsrv 等）が必要です。
使い方
作業ディレクトリの準備
shinkoku はプラグイン（またはスキル）としてインストールして使います。このリポジトリを clone する必要はありません。
お好きなディレクトリを作業フォルダとして使ってください。確定申告に関するデータはすべてこのフォルダ内に保存されます。
# 例: 確定申告用のフォルダを作成
mkdir ~/kakuteishinkoku && cd ~/kakuteishinkoku
# git で管理する場合（推奨）
git init
セットアップ
作業ディレクトリで /setup と入力すると、対話形式で初期設定が始まります。
/setup
セットアップでは以下が行われます:
- 設定ファイル（
shinkoku.config.yaml）の生成
.gitignore の自動設定（git リポジトリの場合）- データベース（
shinkoku.db）の初期化
個人データの保護
shinkoku は作業ディレクトリに以下のファイルを生成します。これらにはマイナンバー・住所・財務データ等の個人情報が含まれます。
| ファイル | 内容 |
|---|
shinkoku.config.yaml | マイナンバー・電話番号・住所等の個人情報 |
shinkoku.db / shinkoku.db-wal / shinkoku.db-shm | 帳簿・仕訳の財務データ |
.shinkoku/ | 進捗ファイル（納税者情報のサマリー） |
output/ | 生成レポート |
/setup を git リポジトリ内で実行すると、これらのファイルが .gitignore に自動追加されます。ユーザーが設定した書類ディレクトリ（請求書・レシート等）も同様に追加されます。
注意: .gitignore に登録されていても、git add -f で強制追加するとコミットされてしまいます。個人情報を含むファイルを絶対にリモートリポジトリにプッシュしないよう注意してください。
スキル一覧
メインワークフロー
| スキル | 説明 |
|---|
/setup | 初回セットアップ。設定ファイル（shinkoku.config.yaml）の生成とデータベースの初期化 |
/assess | 確定申告が必要かどうか、所得税・消費税の申告要否を判定 |
/gather | 必要書類のチェックリストと取得先を案内 |
/journal | CSV・レシート・請求書・源泉徴収票を取り込み、複式簿記の仕訳を登録 |
/settlement | 減価償却・決算整理仕訳の登録、残高試算表・損益計算書・貸借対照表の生成 |
/income-tax | 所得税額を計算（所得控除・税額控除・復興特別所得税） |
/consumption-tax | 消費税額を計算（2割特例・簡易課税・本則課税） |
/submit | 最終確認チェックリストと提出方法（e-Tax / 郵送 / 持参）の案内 |
/e-tax | 確定申告書等作成コーナーへの入力代行（Claude in Chrome / Playwright / Antigravity） |
補助スキル
| スキル | 説明 |
|---|
/tax-advisor | 控除・節税・税制についての質問に回答する税務アドバイザー |
/furusato | ふるさと納税の寄附金登録・一覧・削除・集計と控除限度額推定 |
/invoice-system | インボイス制度関連の参照情報 |
/capabilities | shinkoku の対応範囲・対応ペルソナ・既知の制限事項を表示 |
/incorporation | 法人成り（個人事業主から法人への移行）の税額比較・設立手続き相談 |
OCR 読取スキル
| スキル | 読取対象 |
|---|
/reading-receipt | レシート・領収書・ふるさと納税受領証明書 |
/reading-withholding | 源泉徴収票 |
/reading-invoice | 請求書 |
/reading-deduction-cert | 控除証明書（生命保険料・地震保険料等） |
/reading-payment-statement | 支払調書 |
対応エージェント
OCR 画像読取
レシート・源泉徴収票等の画像読取（/reading-* スキル）は、利用する LLM がマルチモーダル（画像認識）に対応している必要があります。これはエージェントプラットフォームではなく、接続先の LLM の能力に依存します。
- マルチモーダル LLM（Claude Opus 4.6, GPT-5.2, Gemini 3.1 等）: OCR 読取可能
- テキスト専用 LLM: 手動入力が必要
OCR デュアル検証（サブエージェント利用）
2つのサブエージェントが独立に画像を読み取り、結果をクロスチェックする機能です。サブエージェントの並列実行に対応したプラットフォームで利用できます。非対応のプラットフォームでは、単一読取 + ユーザー確認にフォールバックします。
| エージェント | デュアル検証 |
|---|
| Claude Code | ✓ |
| Cowork | ✓ |
| Cursor 2.5+ | ✓ |
| GitHub Copilot | ✓ |
| Cline | ✓ |
| Antigravity | ✓ |
| Windsurf | — |
| Gemini CLI | △ |
| Roo Code | △ |
- △: サブエージェント機能はあるが並列実行が制限的
開発者向け情報
テスト
make test # 全テスト実行
uv run pytest tests/unit/ -v # ユニットテスト
uv run pytest tests/scripts/ -v # CLI テスト
uv run pytest tests/integration/ -v # 統合テスト
Lint / 型チェック
make lint # Ruff lint + format + mypy
uv run ruff format --check src/ tests/ # フォーマットチェック
uv run mypy src/shinkoku/ --ignore-missing-imports # 型チェック
プロジェクト構成
shinkoku/
├── .claude-plugin/
│ └── plugin.json # Claude Code プラグインマニフェスト
├── .github/
│ └── workflows/
│ └── test.yml # CI パイプライン
├── skills/ # Agent Skills（SKILL.md オープン標準）
│ ├── setup/SKILL.md # 初回セットアップ
│ ├── assess/SKILL.md # 申告要否判定
│ ├── gather/SKILL.md # 書類収集
│ ├── journal/SKILL.md # 仕訳入力・帳簿管理
│ ├── settlement/SKILL.md # 決算整理・決算書作成
│ ├── income-tax/SKILL.md # 所得税計算
│ ├── consumption-tax/SKILL.md # 消費税計算
│ ├── submit/SKILL.md # 提出準備
│ ├── tax-advisor/SKILL.md # 税務アドバイザー
│ ├── furusato/SKILL.md # ふるさと納税
│ ├── e-tax/SKILL.md # e-Tax 電子申告（Claude in Chrome）
│ ├── capabilities/SKILL.md # 機能確認
│ ├── incorporation/SKILL.md # 法人成り相談
│ ├── reading-receipt/SKILL.md # OCR: レシート
│ ├── reading-withholding/SKILL.md # OCR: 源泉徴収票
│ ├── reading-invoice/SKILL.md # OCR: 請求書
│ ├── reading-deduction-cert/SKILL.md # OCR: 控除証明書
│ └── reading-payment-statement/SKILL.md # OCR: 支払調書
├── src/shinkoku/
│ ├── cli/ # CLI エントリーポイント（shinkoku コマンド）
│ │ ├── __init__.py # main() + サブコマンド登録
│ │ ├── ledger.py # 帳簿管理 CLI
│ │ ├── tax_calc.py # 税額計算 CLI
│ │ ├── import_data.py # データ取込 CLI
│ │ ├── pdf.py # PDF ユーティリティ CLI
│ │ ├── furusato.py # ふるさと納税 CLI
│ │ └── profile.py # プロファイル CLI
│ ├── tools/ # ビジネスロジック（純粋関数）
│ │ ├── ledger.py # 帳簿管理
│ │ ├── tax_calc.py # 税額計算
│ │ ├── import_data.py # データ取り込み
│ │ ├── pdf.py # PDF ユーティリティ
│ │ ├── furusato.py # ふるさと納税
│ │ └── profile.py # プロファイル取得
│ ├── models.py # Pydantic モデル定義
│ ├── db.py # SQLite DB 管理
│ ├── master_accounts.py # 勘定科目マスタ
│ ├── tax_constants.py # 税制定数
│ ├── config.py # 設定ファイル読み込み
│ ├── hashing.py # ハッシュユーティリティ
│ └── duplicate_detection.py # 重複検出ロジック
├── tests/
│ ├── unit/ # ユニットテスト
│ ├── scripts/ # CLI テスト
│ ├── integration/ # 統合テスト
│ ├── fixtures/ # テストフィクスチャ
│ └── helpers/ # テストヘルパー
├── shinkoku.config.example.yaml # 設定ファイルテンプレート
├── pyproject.toml
├── Makefile
└── uv.lock
技術スタック
- Python 3.11+
- SQLite（WAL モード）
- Pydantic（モデル定義・バリデーション）
- pdfplumber（PDF 読取）
- Playwright（ブラウザ自動化フォールバック — Python
playwright + npm @playwright/cli）
- PyYAML（設定ファイル読み込み）
- Ruff（lint / format）
- mypy（型チェック）
- pytest（テスト）
ライセンス
MIT License -- 詳細は LICENSE を参照してください。
コントリビュート
Issue や Pull Request を歓迎します。日本語での報告・提案で構いません。
- バグ報告: Issue を作成してください。再現手順があると助かります
- 機能提案: Issue で議論した上で PR を作成してください
- PR:
main ブランチに対して作成してください。CI（lint + テスト）が通ることを確認してください
