Claude Code と経理 freee会計API周りの調査下書きと人間確認（概念）

freee会計をはじめとするクラウド会計SaaSの導入が進む一方で、実務担当者を悩ませ続けているのが「既存システムや独自スプレッドシートとのAPI連携」です。iPaaS（MakeやZapierなど）では対応しきれない複雑な配賦ロジックや、社内独自の基幹データとの突き合わせ、そして何より「AIが勝手に仕訳を送信してしまわないか」という不安が、自動化の壁となっています。

この課題に対し、Anthropicが提供するコーディングエージェント「Claude Code」は、単なるコード生成を超えた「実務の調査・下書き・検証」のパートナーとして極めて強力な力を発揮します。本記事では、Claude CodeをCLI（コマンドラインインターフェース）から操作し、freee会計APIを用いたセキュアで確実な連携基盤を構築する手法を解説します。

1. 経理DXのボトルネックをClaude Codeで突破する

経理実務におけるAPI連携が「構想」だけで終わってしまう最大の理由は、APIドキュメントの理解と、例外処理の多さにあります。例えば、freee会計APIで取引（deals）を登録する際、勘定科目ID、税区分コード、部門ID、タグIDなど、事前に取得・照合すべき項目が膨大に存在します。

Claude Codeは、開発者のローカルリポジトリに直接アクセスし、既存のコード、設定ファイル、そして読み込ませたドキュメントを「文脈」として理解します。これにより、従来のチャット型AIでは難しかった「うちの会社の勘定科目定義に基づいた、エラーの出ない連携スクリプトの作成」が可能になります。

特に重要なのは、Claude Codeに「完璧な自動化」ではなく「人間が確認するための高度な下書き」を作らせることです。仕訳データを飛ばす前に、その内容を人間がレビューできる形式（Markdownやスプレッドシート）で出力する工程をClaude Codeに担当させることで、セキュリティと心理的安全性を担保します。

2. Claude Code × freee API連携のリポジトリ設計と設定

Claude Codeを効果的に動かすためには、リポジトリ構成を「AIが読み取りやすい形」に整える必要があります。具体的には、プロジェクトのルートに CLAUDE.md を配置し、Claude Codeが守るべきルールや参照すべき情報を定義します。

リポジトリの推奨構成

• /docs/api_spec/: freee APIの仕様（公式からダウンロードしたOpenAPI JSONやリファレンスのMarkdown）。
• /config/master/: 自社の勘定科目、部門、タグの一覧（JSON形式）。
• /scripts/: Claude Codeが生成する実行スクリプト（Python/Node.jsなど）。
• CLAUDE.md: プロジェクト全体の指示書。
• AGENTS.md: 特定のタスク（例：月次仕訳チェック）に特化したサブエージェントへの指示。

CLAUDE.md の記述例

Claude Codeはこのファイルを読み取って自身の挙動を制御します。ここに「freee会計のAPI仕様を遵守すること」「秘密鍵は .env から読み込み、コード内に直接書かないこと」「必ず dry-run モードを実装すること」といった制約を記述します。

# Project: freee-api-integration

Rules

Always use environment variables for CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN.

Reference docs/api_spec/freee_accounting_api.json for endpoint structures.

Implement a '--dry-run' flag in all scripts to output target data in JSON format before actual API calls.

All financial numbers must be handled as integers to avoid floating-point errors.

3. 実践：Claude CodeによるAPI連携スクリプトの生成フロー

環境が整ったら、CLIから Claude Codeを起動します。ここでのポイントは、指示を細分化し、段階的に「下書き」を構築させることです。

ステップ1：APIドキュメントの解析と型定義の作成

まず、docs/api_spec/ に配置したfreeeのOpenAPIファイルを読み取らせ、スクリプトで利用するための型定義や定数を作成させます。

「docsの下にあるfreeeのAPI仕様を確認して、取引（deals）の作成に必要なリクエストボディのTypeScript型定義ファイルを作って。また、主要な勘定科目IDをconfigから読み取って列挙型にして」

ステップ2：認証・認可（OAuth2.0）の実装

freee APIはアクセストークンの有効期限が短いため、リフレッシュトークンによる更新処理が必須です。Claude Codeにこのロジックを実装させます。Claude Codeはファイル編集能力（edit_file）とターミナル実行能力（run_terminal_command）を持っているため、実際に curl などで導通確認を行いながらコードをブラッシュアップできます。

ステップ3：エラーハンドリングの組み込み

Claude Codeの強みは、過去の実行ログ（エラーメッセージ）を読み取らせて修正案を出させることにあります。例えば、「リクエストした勘定科目コードが存在しない」というエラーが出た場合、Claude Codeはそのログを解析し、「APIを叩く前にローカルのマスターと照合するチェック関数」を自動的にスクリプトに追加してくれます。

4. 「人間確認」を前提とした安全な実行・承認フローの構築

会計データにおいて、AIによる「全自動」はリスクです。Claude Codeを活用して、以下のような「承認ステップ」をコード内に組み込みます。

Dry-run とプレビュー出力

スクリプトを実行すると、実際のAPI送信を行う代わりに、送信予定のデータをテーブル形式のMarkdownファイル（proposed_deals.md）として出力させます。Claude Codeに対し、「このMarkdownを読んで、重複や異常値がないかエージェントの視点でチェックして」と依頼することも可能です。

Claude Codeによる「人間への質問」

複雑な配賦ロジックで迷った際、Claude Codeは自ら判断を下さず、開発者に質問を投げます。

「この行の部門IDが特定できません。マスタに従って『共通部門』に割り当てますか？それともスキップしますか？」

このやり取りの結果をスクリプトの条件分岐として反映させることで、実務に即した精度の高いコードが完成します。

5. freee会計API活用における比較と選定基準

API連携の実装手段は、Claude Codeによる自作以外にも存在します。用途に合わせて適切なツールを選択してください。

6. まとめ：Claude Codeを「経理のIT右腕」にするための運用ルール

Claude Codeを使ったfreee API連携は、開発スピードを劇的に向上させますが、それを継続的に運用するためには、エンジニアではない経理担当者との役割分担が重要です。

• エンジニア（またはIT担当者）: Claude Codeを使い、リポジトリの CLAUDE.md を更新し、スクリプトの骨組みをメンテナンスする。
• 経理担当者: config/master/ 内のJSONファイルやCSVファイルを更新し、AIが参照する「正解データ」を常に最新に保つ。
• 共通フロー: 実行前に必ず proposed_deals.md などの中間生成物を確認し、双方が合意してから本番実行（またはプルリクエストの承認）を行う。

AIエージェントを「ただのコード生成ツール」としてではなく、「ドキュメントと実務の溝を埋める調査担当」として位置づけること。これこそが、Claude Code時代の新しいバックオフィスDXの姿です。まずは、現在手動で行っているCSV変換作業の「下書き」を、Claude Codeに依頼するところから始めてみてください。