その他の環境構築まとめはこちら
Claude Code 環境構築・運用Tipsまとめ
はじめに
Claude Code などのコーディングエージェントに実装を任せていると、既存の共通関数を使わずに似た関数を新たに作ったり、他の箇所とは違う方法でエラー処理をしたりすることがあります。
これらの原因の多くは、実装前の計画のあいまいさにあります。計画に未決定や要検討の項目が残っていると、エージェントは、実装中にそれらの箇所を自己判断して実装します。そのときの材料として使われるのは、実装のために読み込んでいる狭いコンテキストの範囲内の情報だけです。結果、その実装箇所では動作するが、コード全体では噛み合っていない、独創的な実装が発明されます。特に、最近のLLMは高性能になっている分、逆に、独創性が発揮されやすいです。
この現象が積み重なると、結局は、技術負債になります。
この技術負債を減らすためには、実装前に計画のフェーズを設けることと、その計画で広く、深く探索・計画させることが大切です。そのためには、さらに下記の２点に配慮する必要があります。
- 筋のいい計画の作成： 実装済みのコードと、公式文書や世間一般の事例を調べてから計画を作れば、独自の解法を編み出さずに、世の中の知見を活用した、計画の作成ができる。
- 未決定項目の払拭： 未決定/要検討の項目は、計画作成時にディスカッションして決める。また、事前調査で試験が必要であれば、試験を許可する。そうして、実装中の判断が入る余地をなくす。
この記事では、上記2つを具体的に実践するポイントと、最後に CLAUDE.md の例文を載せます。
全体の流れ
1. 関係するコードを読む
2. 世間一般のやり方を調べる
3. 試験して確かめる
4. 変更に伴う影響範囲を調べる
5. 計画書を書く
6. 要検討・未決定の項目を解消する
7. サブエージェントでレビューする
8. 承認を受けてから実装する
手順
1. 関係するコードを読む
経験ある人はわかりますが、コーディングエージェントは計画作成をする際、驚くほど実物のコードを読みません。プロジェクトのフォルダにある関連ドキュメントやgrepで”斜め読み”をして、実装のあたりをつけます。そして、実装時になって逐一コードを読み始めて計画と実装のずれを見つけると、その場の判断で実装方針を変更し、結果、独創的な実装が生まれます。
そのため、実装計画には、コードの該当部分を読んで確かめたことだけを書かせます。また、コードの読み方として、次の指示もしています。
-
二次資料の情報は、現物と照合する：タスク管理の記述・前回からの引き継ぎメモ・過去のメモは、それが書かれた時点の情報です。計画作成では記述が指すコードや git の状態と突き合わせて調べさせます。
-
リファクタリングする場合は、暗黙的な仕組みも書き出す：並列性・呼び出し回数・順序など。コードのその箇所だけでは分からない条件や仕組みも書き出させます。
-
計画は仮説で実コードが真だと念押しする：計画に書いた設計判断は、実装の段階でもコードと照らし合わせるようにします。計画を書いたあとにコードを読まなくなるのを防ぎます。
2. 世間一般のやり方を調べる
世間一般の実装は、その問題に対して、簡潔・的確であることの方が多いです。そのため、計画作成に、まず、主流のツールやライブラリがその問題をどう解いているか、公式ドキュメントやレポジトリで調べさせます。
AIエージェントは、WebsearchやWebfetchを避ける傾向があるので、これも、明確に指示しないと調査しません。手順に記載して、車輪の再発明をさせないようにします。
3. 試験して確かめる
ライブラリやAPI、コマンドの振る舞い（応答の内容や、所用時間など）は、ドキュメントやコードを読むだけでは分からないことがあります。しかし、この部分を放置していると、AIエージェントは推測で計画を書くか、未決定事項として実装時の宿題に回します。これらは、結果、実装中にその場で考えて技術負債になります。
そのため、試験をしてよいという許可を、明示的に開発ルールに入れています。
4. 変更に伴う影響範囲を調べる
事前に、実装による影響を受けるファイル・呼び出し元・設定キー・フォールバックを調べ、具体的にfile:line 付きで記載させます。これにより、計画検討の網羅性を上げます。また、ファイルとラインまで書かせることで、AIエージェントが実際にコードを読んだことの証明にもなります。あわせて、これから書こうとしている処理と同じものが、既にないかも調査させます。
5. 計画書を書く
計画書必須の項目は、チェックリスト2にあります。また、「別セッションの Claude が、受け取って実行できるレベルの詳しさ」で書くよう指示しています。そうすることで、計画のあいまいさや省略をなくすようにします。
冗長性の削除や保守性の配慮もルールとして指示しています。具体的には、コード変更はチョークポイント（複数の処理の根本・集約した箇所）で実行するよう検討させています。結果として、１つの変更に対して、分岐先のコード複数個所で直すことがないようにします。
また、「やらないこと」も指定します。依頼していない機能の追加や、ついでのリファクタリング、過剰な汎用化はしないようにしています。
6. 要検討・未決定の項目を解消する
AIエージェントが書く計画書は、うっかりしていると、結構、未決定の記載が混入します（正直といえば正直）。これらも、実装中にAIエージェントがその場で判断して埋めてしまいます。そのため、「要検討」「TBD」の内容は、計画提示までに全部解消させます。方法は2通りあります。
- ドキュメント調査や世の中一般のやり方で答えが決まることは、自分で決めさせて根拠を添える
- ユーザーの価値観・運用・リスクの取り方で答えが変わることだけは、選択肢と推奨を添えて質問させる
7. サブエージェントでレビューする
作成した計画書は、レビューエージェントを立てて、レビュー → 修正 させています。エージェントに指示するレビュー観点は、チェックリスト4のとおりです。
8. 承認を受けてから実装する
実装はユーザーの承認取得後に実行します。さらに、実装中に方式や割り切りが変わったら、その時点で承認を取り直させ、独自判断が混入しないようにします。
チェックリスト
1. 根拠にしてよいもの
- 実際のコードを読んで確かめた
- 実際に動かした結果で確かめた
- 記憶・エージェントの報告・引き継ぎメモ・タスク管理の記述は、現物と照らし合わせてから使った
2. 計画書に必須の項目
-
対象ファイル（
file:line） - 変更内容
- 変更を置く場所と、その理由
- やらないこと（範囲外）
- 確かめ方（実行するコマンドと、期待する結果）
3. 影響範囲の洗い出し
- 呼び出し元・設定キー・フォールバック・テスト・ドキュメントまで含めた
- 同じ処理・同じ判断が、すでにどこかにないかを探した
- 定数を変えるときは、名前だけでなく古い値でも grep した
4. セルフレビューの観点
- 前提は正しいか
- 抜けは無いか
- リスクを書いたか
- 完了条件は、確かめられる形になっているか
- 頼まれていない作業が混じっていないか
- もっと簡潔にできないか
5. 差し戻しへの対応
- 差し戻しの反映が2回を超えたら、追記をやめて全体を書き直した
CLAUDE.md に貼る例文
## 計画の作り方
計画は、実装中にその場の判断が要らない状態まで詰めてから提示する。
### 手順
1. 関係するコードを実際に読む。読んで確かめたことだけを書き、推測は書かない
2. 独自の仕組みを足す前に、主流のツールがその問題をどう解いているかを公式ドキュメントで調べる
3. 読むだけで分からない挙動は、一時ディレクトリで動かして確かめる
4. 影響を受けるファイル・呼び出し元・設定キー・フォールバックを file:line 付きで一覧にする。同じ処理・判断がすでにないかも探す。一覧が埋まるまで計画を書き始めない
5. 計画を書く。この会話を知らない別の Claude が、そのまま実行できる詳しさにする
6. 「要検討」「TBD」を提示前に消す。規約や標準で決まることは自分で決めて根拠を添え、人の価値観で答えが変わることだけを選択肢と推奨を添えて質問する
7. 提示前に、前提・抜け・リスク・完了条件・範囲外の作業・簡潔さの観点で自分でレビューする
8. 承認を得てから実装する。実装中に方式が変わったら、その時点で承認を取り直す
### 計画書に必須の項目
- 対象ファイル（file:line）
- 変更内容
- 変更を置く場所と、その理由
- やらないこと（範囲外）
- 確かめ方（コマンドと期待結果）
### コードの読み方
- タスクの記述・引き継ぎメモ・記憶・エージェントの報告は、着手前に現物と照らし合わせる。食い違いは列挙し、実態を正とする
- 既存の構造を作り直すときは、暗黙に持っていた性質（並列性・呼び出し回数・順序）を先に書き出す。書いていない性質は「未確認」と扱う
- 計画は仮説であり、正本は実コード。実装時にもコードと照らし合わせる
- 「影響は無い」「〜だけ」と書く前に、反証を1回試す。検索の0件は、検索が見た範囲を確かめてから「無い」と読む
### 置き場所と範囲
- 判断（分類・条件分岐・検証）は、必要な情報が全部揃う1か所に置く。同じ判断を複数の箇所に置かない
- 不変条件は、症状の出た箇所でなく共通の経路（入口・出口・境界・共有関数）で守る
- 同じものを2か所に手で書いて同期させない。正本を1つにして、残りは生成・導出する
- 頼まれていない機能・ついでのリファクタリング・必要になる前の汎用化はしない。必要だと考えたら提案として出す
### 守ること
- 定数を変えるときは、名前だけでなく古い値でも grep する
- 差し戻しの反映が2回を超えたら、追記をやめて全体を書き直す
- 確かめるための読み取りと、一時ディレクトリでの試験は、許可を待たずに行ってよい
まとめ
- 技術負債が発生する元は、AIエージェントが実装中に行う、その場の判断にある
実装中の判断を防ぐために、
- 筋のいい計画を作る仕組みを入れる（コードを読む・一般的なやり方を調べる・試験・影響範囲をだす）
- 計画には未決定項目を残さない（決められることは決め、聞くべきことは聞く）
AIエージェントの実装を見ていると、予定を変えてとんでもない実装をやるとつぶやき始めた。。そういうことがないように、事前の計画をしっかり実行しましょう！！