AIコーディングで手戻りを減らしたいなら、実装依頼にこの一文を足すのが効きます。
仕様書通りに実装して。
途中で仕様書に書かれていなかった判断・変更・妥協点を、全部 implementation-notes に残して。大事なのは、AIに「作らせる」だけで終わらせないことです。
AIがどこで仕様の行間を読んだのか。
どこで小さな判断をしたのか。
それをあとから見える形に残します。
仕様書は100%を網羅できない
仕様書に全部を書くのは難しいです。
- ボタンの文言
- エラー時の表示
- 空データの扱い
- 既存コードとの合わせ方
- どのファイルに責務を置くか
- テストをどこまで書くか
こういう細部は、実装中に決まることが多いです。
人間が実装するときも同じです。
ただ、人間ならレビュー時に「ここはこう判断しました」と説明できます。
AIにもそれをさせる。
それが implementation-notes の役割です。
implementation-notes に残すべきこと
残すのは、きれいな作業日報ではありません。
あとからズレを見つけるためのメモです。
たとえば、こういう内容です。
## implementation-notes
- 仕様書に空状態の文言がなかったため、「まだデータがありません」を仮文言にした。
- 既存の Button コンポーネントに disabled スタイルがあったため、新規CSSは追加しなかった。
- APIエラーの種類が未定義だったため、現時点では全エラーを同じ表示にしている。
- 一覧の並び順が未指定だったため、既存ページと同じ `created_at desc` にした。
- テスト対象は保存成功と空状態に絞った。権限エラーは仕様未確定のため未追加。このくらいで十分です。
完璧な説明より、「どこが仕様外だったか」が見えることのほうが大事です。
レビューで見る場所が変わる
このメモがあると、レビューの見方が変わります。
コード全体を最初から読む前に、まず implementation-notes を見ます。
- 仕様にない判断は妥当か
- 仮置きの文言はそのままでよいか
- 妥協点を次のタスクにするべきか
- テストしなかった部分は危険ではないか
ここを見れば、仕様と実装のズレを早く見つけられます。
AIが勝手にズレたというより、AIが埋めた行間を人間が確認できる状態になります。
Claude CodeでもCodexでもCursorでも使える
この考え方は、Claude Codeだけの話ではありません。
CodexでもCursorでも同じです。
AIに長い実装を任せるほど、途中の判断は増えます。
だから依頼文に、最初からログの置き場を指定します。
仕様書に沿って実装してください。
仕様書にない判断、変更、妥協点、未確認事項は implementation-notes に箇条書きで残してください。
実装完了後、変更点より先に implementation-notes を提示してください。「先に提示してください」まで入れるのがポイントです。
最後に短く出してもらうだけだと、見落としやすいからです。
ファイルに残すなら場所を決める
毎回チャットだけに残すと、次のAIに引き継ぎにくくなります。
プロジェクトで使うなら、置き場所も決めておくと安定します。
implementation-notes は docs/implementation-notes.md に追記してください。
追記するときは、日付、対象機能、判断、理由、未確認事項を短く残してください。小さい案件なら、PR本文や作業完了メモでも十分です。
大きい案件なら、専用ファイルに残すほうがあとで探しやすいです。
そのまま使える短いプロンプト
最短ならこれでいいです。
仕様書通りに実装して。
仕様書に書かれていなかった判断・変更・妥協点・未確認事項は、全部 implementation-notes に残して。レビュー前提なら、少し足します。
仕様書通りに実装して。
仕様書にない判断・変更・妥協点・未確認事項は implementation-notes に残して。
最後に、implementation-notes、変更ファイル、未実施事項、確認したテストを短く出して。チームで使うなら、もっと明確にします。
仕様書通りに実装して。
仕様書にない判断・変更・妥協点・未確認事項は docs/implementation-notes.md に追記して。
各メモは「判断」「理由」「影響」「次に確認すること」の4項目で書いて。
公開、削除、破壊的操作は実行前に確認して。CLAUDE.md や AGENTS.md に入れるなら
毎回使うなら、プロジェクト指示に入れるのもありです。
## 実装メモ
- 仕様書にない判断、変更、妥協点、未確認事項は implementation-notes に残す。
- メモは短く、あとからレビューできる具体度で書く。
- 公開、削除、破壊的操作は実行前に確認する。AnthropicのClaude Codeドキュメントでも、CLAUDE.md はプロジェクトの共有指示として使える場所です。
Codexなら AGENTS.md に同じ考え方を入れられます。
「なぜそうしたか」まで残す
AIコーディングで怖いのは、コードが動かないことだけではありません。
動いているけれど、なぜそうなったかわからない。
これが後から一番つらいです。
だから、実装依頼に一文足す。
なぜそうしたかも残して。この一文で、AIの作業はただの生成から、引き継げる実装に近づきます。
関連記事
- CLAUDE.mdの書き方：効く文と効かない文の違い
- Claude Codeのプロジェクト設定、ちゃんとやってますか？.claude/フォルダの使い方
- Codexで長い実装を任せるときのファイル作業フロー
