中小規模のSaaSを運営する開発チームで、請求書作成APIの内部実装が複雑になっている場面を考えます。公開関数の引数や戻り値は、管理画面、社内バッチ、取引先向け連携から利用されています。担当者は保守性を改善したいものの、呼び出し元を壊せば複数部署の業務に影響します。ここでの成果物は、新しい機能ではありません。既存の公開API契約を維持したまま、責務の分割や重複処理の整理を終えたコードと、その互換性を説明できる検証記録です。

AIを使わない場合、担当者はGit、IDEの検索機能、API仕様書、既存テスト、過去のプルリクエストなどを行き来します。公開関数の定義を探し、呼び出し元を列挙し、関連する型や例外処理を読み、テストがどこまで契約を固定しているか確認します。その後、変更対象を絞って実装し、失敗したテストの原因が意図した内部変更なのか、互換性の破壊なのかを判定します。レビューで未調査の呼び出し元が見つかれば、調査へ戻ることになります。

この作業でClaude Codeに任せるのは、契約を変更してよいかという判断ではありません。リポジトリ内の関連箇所の探索、既存テストと実装の対応付け、変更計画の下書き、承認された範囲の編集、検証結果の整理を補助してもらいます。公開APIの定義、許容できる挙動差、テストの十分性、最終承認は引き続き人が担います。以下では、架空の請求書APIを例に、この境界を崩さず進める方法を示します。

公開APIを保つリファクタリングが難しい理由は、コードを書く作業よりも、変更してはいけない境界が複数の場所に分散している点にあります。関数シグネチャはソースコード、エラー形式はテスト、利用例はドキュメント、暗黙の前提は呼び出し元にしか残っていないかもしれません。担当者は検索結果を読みながら、公開契約、内部実装、テスト用コード、無関係な同名処理を分類する必要があります。

AIを使わない工程とClaude Codeで補助する工程を、入力、成果物、品質条件を変えずに対応付けると次のようになります。Claude Codeが探索結果をまとめても、検索漏れがないことや契約の解釈が妥当であることまで自動的に保証されるわけではありません。担当者は根拠となるファイルを開き、計画が実際のコードと一致するか確認します。

| 工程 | AIを使わない場合 | Claude Codeで補助する場合 |
| --- | --- | --- |
| 呼び出し元調査 | 検索結果を一件ずつ読み、関連箇所を分類する | 定義、再エクスポート、呼び出し元、テストの候補を根拠付きで整理させる |
| 契約の固定 | 仕様書とテストを見比べて変更禁止点をメモする | 引数、戻り値、例外、副作用の候補を契約一覧として下書きさせる |
| 変更計画 | 担当者が修正順序と影響範囲を組み立てる | 対象ファイル、非目標、検証手順を含む計画案を作らせる |
| 実装 | 小さく修正しながらテストを繰り返す | 承認済みの範囲だけ編集させ、差分と検証結果を報告させる |
| 回帰確認 | 失敗ログと差分を手作業で突き合わせる | 失敗内容を変更箇所と対応付けて整理させる |

減らせる可能性があるのは、探索結果の転記、関連ファイルの分類、計画書の初稿作成、検証結果の要約といった繰り返しです。対して、どの挙動が顧客との契約に含まれるか、既存の不具合まで互換性として残すのか、追加テストが十分かという判断は省略できません。AIへの入力準備や回答確認も工程に含めなければ、見かけ上の短縮だけを評価することになります。

互換性が条件になる作業では、調査と編集を同じ指示で始めるより、計画を承認するゲートを設けるほうが管理しやすくなります。Claude CodeのPlan modeは、ファイルを読み取って計画を提案し、利用者が承認するまで編集しない作業形態として公式資料で説明されています。セッション中はShift+TabでPlan modeへ切り替えられ、ステータスバーで状態を確認できると案内されています（出典: Claude Code Docs）。これは新機能として紹介するものではなく、影響範囲の大きい変更を人が事前確認するための既存ワークフローとして利用します。

計画には、単なる修正ファイル一覧だけでなく、公開契約の仮説、根拠となる定義やテスト、変更対象、非目標、実装順序、検証方法、未解決事項を含めます。たとえば「公開関数の名前と型は変更しない」だけでは不十分です。例外の種類、エラーメッセージを契約に含めるか、処理順序や副作用を維持するか、非同期処理のタイミング差を許容するかまで、既存資料から確認する必要があります。資料にない判断はClaude Codeに決めさせず、計画上の質問として残します。

承認時には、対象外の範囲も明記します。今回は公開APIの追加、データベーススキーマの変更、依存関係の更新、性能改善、デプロイを非目標とする、といった形です。非目標がない計画は、善意の整理が別の変更へ広がりやすくなります。承認は「計画が詳しいから」ではなく、各変更が契約または保守上の目的に結び付き、対応する検証方法があることを条件にします。

Plan modeは契約を発見する魔法ではありません。見落とした外部利用者や、テストに現れない運用依存は計画へ自動的に現れない可能性があります。したがって、計画の承認前にAPI仕様の所有者や運用担当者へ確認する経路も決めておきます。この人によるゲートが、探索支援と変更権限を分離する中心になります。

Claude Codeを起動する前に、対象リポジトリ、既存のテスト方法、公開APIを示す資料、変更要求をそろえます。前提知識として、Gitの差分確認、対象言語の型と例外処理、テストフレームワーク、APIの後方互換性、モジュールの公開範囲を理解している必要があります。今回の手順は、コードを読まずに実行できる自動変換ではありません。回答の根拠をソースコードまでたどり、提案された分割がシステム設計に合うか判断できる開発者を対象にしています。

準備する入力は四つに分けると扱いやすくなります。一つ目は、公開関数、エンドポイント、型定義、再エクスポート箇所などの契約候補です。二つ目は、正常系、入力境界、エラー、副作用を確認する既存テストです。三つ目は、今回解消したい保守上の問題です。「読みづらい」ではなく、「検証、税計算、永続化が一つの関数に混在し、個別テストが難しい」のように観察できる状態で記述します。四つ目は、変更してはいけない範囲と、人の承認が必要な操作です。

テストが少ない場合は、いきなり内部実装を入れ替えません。先に現在の挙動を特徴付けるテストを追加する計画を立て、そのテスト自体を人がレビューします。Claude Codeは既存テストを調べ、プロジェクトで使われているスタイル、フレームワーク、アサーションの傾向に合わせたテストや、境界値・エラー条件の候補を提案できると公式資料で案内されています（出典: Claude Code Docs）。ただし、生成されたテストが誤った現状を固定していないかは担当者が判断します。

開始時点の状態も記録します。既存テストの成否、作業前からある警告、対象APIの代表的な入出力、未追跡の変更などです。後から失敗が出たとき、今回の差分によるものか既存問題なのかを区別する材料になります。認証情報や顧客データを入力へ含める必要がある場合は、そのまま渡さず、組織の規程に沿った匿名化や利用可否の確認を先に行います。

操作は、調査、契約整理、計画承認、実装、検証の五段階に分けます。Claude Codeを対象リポジトリで利用し、Plan modeであることをステータスバーから確認した後、最初は読み取りと計画だけを依頼します。公式資料でも、Plan modeは編集前に変更案を確認したい場面に向くと説明されています（出典: Claude Code Docs）。指示内の角括弧は、自分のリポジトリに合わせて置き換えてください。

コピーして使う調査・計画用のお願い文です。これは活用例であり、公式に定められた書式ではありません。

対象は［公開API名またはモジュール名］の内部リファクタリングです。
まだファイルを編集せず、読み取りと計画作成だけを行ってください。

目的:
- ［解消したい責務の混在や重複］を整理する
- 公開APIの互換性を維持する

調査してください:
1. 公開定義、再エクスポート、型定義
2. リポジトリ内の直接・間接の呼び出し元
3. 正常系、境界値、エラー、副作用を扱う既存テスト
4. 仕様書、利用例、変更履歴にある契約の根拠

計画には、根拠となるファイル、契約として維持する項目、
変更対象、明示的な非目標、実装の小さな段階、
各段階の検証方法、未解決の質問を含めてください。
根拠が見つからない事項は推測せず、未確認と記載してください。

返ってきた計画では、列挙されたファイルが実在するか、呼び出し元の分類が妥当か、変更段階ごとに検証できるかを確認します。APIの契約候補に疑義があれば、その場で編集を許可せず、追加調査を依頼します。計画を修正して合意できた場合だけ、通常の編集が可能な状態へ移り、承認済みの一段階を指定します。

コピーして使う実装用のお願い文です。実際のテストコマンドはClaude Codeに創作させず、リポジトリの設定や文書から特定させます。

承認した計画のうち、［段階名］だけを実装してください。
公開名、引数、戻り値、公開型、エラー契約、観測可能な副作用は変更しません。
計画にない依存関係更新、API追加、設定変更、コミット、プッシュ、
デプロイは行わないでください。

実装後は、リポジトリで定義済みの方法に従って
対象テストと関連する広いテストを実行してください。
変更ファイル、契約を維持した根拠、実行した検証、
成功・失敗・未実行の区別、残るリスクを報告して停止してください。

一度に全段階を実装させず、差分をレビューしてから次へ進みます。途中で契約の解釈が変わった場合は、実装を継続せずPlan modeへ戻し、計画と非目標を更新します。これにより、最初の仮説が誤っていたときの手戻り範囲を限定できます。

実装後の確認は、テストが緑色かどうかだけでは終わりません。テストが契約の一部しか覆っていなければ、公開型の変更や再エクスポート漏れが残る可能性があります。担当者はGit差分を読み、公開APIに関係する変更と内部だけの変更を分類します。公開関数の名前、引数の必須・任意、戻り値の構造、公開される型、例外、ログ以外の副作用、処理順序に依存する挙動を、開始前に作った契約一覧と照合します。

承認基準はリポジトリごとに具体化します。少なくとも、公開面の差分がないこと、既存テストが同じ条件で通ること、追加テストが意図した境界を固定していること、失敗や未実行が明記されていること、変更が承認済みの対象内に収まっていることを確認します。API仕様を自動生成しているプロジェクトなら、生成物の差分も既存の正式な手順で調べます。差分が生じた場合、見た目が小さくても人が理由を説明できるまで承認しません。

Claude Codeからの最終報告は、検証の証拠を探す索引として使います。「互換性を維持しました」という要約そのものを証拠にはしません。報告されたコマンドが実際に実行されたか、終了状態はどうだったか、スキップされたテストがないか、対象外の失敗を無視していないかを確認します。未実行の検証は、成功ではなく未実行として扱います。

レビューでは、内部設計の品質も別に見ます。抽出した関数が元の責務を別の場所へ移しただけではないか、命名がドメイン用語と一致するか、新しい抽象化が一つの利用箇所しかないのに過剰ではないかを確認します。また、エラー処理やトランザクション境界が分割によって変化していないかも重要です。疑問があれば、Claude Codeへ差分の説明や追加テスト案を求められますが、採用判断は設計責任者が行います。

Claude Code導入の効果は、「実装に何分かかったか」だけでは判断できません。調査資料の準備、AIへの指示、計画の修正、差分レビュー、テスト、手戻りまで同じ範囲に含めます。比較するなら、同程度の公開範囲、呼び出し元数、テスト状態を持つ作業を選びます。片方だけ十分な仕様書がある案件や、片方だけテストが壊れている案件を並べても、AIの有無による差とは切り分けられません。

記録項目は、呼び出し元を探す時間、契約一覧を作る時間、計画をレビューする時間、実装時間、検証時間、修正回数、追加調査へ戻った回数に分けます。時間だけでなく、レビューで新たに発見された未調査箇所、計画外の変更数、テストで捕捉された契約差分も記録すると、速さと安全性を分けて評価できます。数値目標を先に作る必要はありません。数件の実績を同じ記録様式で集め、どの工程で転記や再探索が減ったかを確認します。

効果が出やすいのは、公開面と内部面がある程度分離され、既存テストや仕様の根拠をリポジトリから追える作業です。反対に、契約が口頭でしか共有されていない場合や、外部の呼び出し元を把握できない場合は、Claude Codeの探索だけで安全性を補えません。その場合、最初の成果はリファクタリングではなく、契約一覧や特徴付けテストを整備することになります。

最初の試行では、公開関数を一つだけ選び、外部依存やデータ移行を伴わない内部処理に範囲を限定します。Plan modeで調査と計画を作らせたところで一度停止し、人が作った従来の調査メモと比較してください。呼び出し元、契約候補、未解決事項のどこに漏れや余分な記述があるかを確認できれば、実装を任せる前に自社で使える指示と承認基準を調整できます。その小さな比較が、安全性を保った導入可否を判断する最初の一歩になります。

- Common workflows - Claude Code Docs