AIに「作らせる」だけでは足りない時代

AIコーディングツール（Claude Code、Codex、Cursor など）を使う際、多くの開発者が次のプロンプトで止まってしまっている。

1
2
3

「作って」
「修正して」
「いい感じにして」

これで機能は動く。しかし、後から「なぜそうなったのか」が一切わからない。

Claude Code Studio（@ClaudeCode_love）が紹介した、Anthropic 社員が使っているとされるプロンプトは、その問題に真正面から切り込んでいる（公式声明ではなく、あくまで伝聞である点に注意）。

Anthropic 社員が使うプロンプト

元ツイート（2026-05-19）では「自分がいちばん使っているプロンプト」として次の指示が紹介されている。

1
2
3

仕様書通りに実装して。
その途中で、仕様書に書かれてなかった判断・変更・妥協点・意思決定を、
全部 implementation-notes に残して

英語で書くなら次のようになる。

1
2
3

Implement according to the specification.
Along the way, record every judgment, change, trade-off, and decision
not covered by the spec into implementation-notes.

一見地味に見えるが、これは AI コーディングの本質を突いたプロンプトだ。本記事では、このプロンプトを 「計画レビュー」と対比する形で深掘り し、なぜ AI コーディング時代に implementation-notes パターンが支配的になるのかを考察する。

計画レビュー vs 実装後ノート — 2つのアプローチの本質的な違い

AI に作業させる際の品質担保には、大きく2つの系統がある。

A. 計画ドキュメント → レビュー → 実装

仕様 → 実装計画書（PRD、ADR、設計ドキュメント） → 人間がレビューして合意 → 実装。代表例は GitHub の RFC プロセスや、Claude Code の Plan Mode。

「これから起こすつもりのこと」を事前に文書化する。

B. 仕様 → 実装 → implementation-notes

仕様 → 実装しながら、仕様に書かれていなかった判断を都度ログに残す。今回の Anthropic 社員プロンプトの形。

「実際に起きたこと」を事後に文書化する。

この2つは表面上似ているが、解いている問題がまったく違う。

それぞれが防いでいるリスク

観点A: 計画レビューB: implementation-notes
主に防ぐリスク方向性の間違い・手戻りサイレントな逸脱・微小判断の蓄積
介入タイミング事前合意事後監査
記録される情報「こう実装するつもり」「実際にこう実装した／こう判断した」
ドキュメントの正直さ乖離（drift）しやすい高い（現実の記録）
失敗のコスト計画の作り直し仕様と実装のズレが放置される

計画レビューが防ぐのは「そもそも違う方向に進む」リスク。implementation-notes が防ぐのは「正しい方向に進んだつもりが、無数の小さな判断で違うものができている」リスク。

両者は対立するアプローチではなく、まったく違うレイヤーの監査メカニズム だと整理するのが正しい。後述するとおり、実務的には直列に組み合わせるべきものだ。

AI コーディング時代の非対称性

ここからが本題だ。なぜ Anthropic のエンジニアが「いちばん使っている」のが implementation-notes なのか — それは AI コーディング特有の リスク構造の非対称性 に起因する。

AI は無音で大量の micro-decision を下す

AI に実装を任せると、仕様に書かれていなかった選択が無数に生まれる。

  • 変数の命名規則
  • エラーハンドリングの粒度（throw する／catch して continue する）
  • ライブラリ選定（標準ライブラリ vs サードパーティ）
  • エッジケースの扱い（null は空文字に変換するのか、エラーにするのか）
  • 並行性の扱い（同期 vs 非同期、ロックの粒度）
  • ログ出力の有無と詳細度

これらは仕様には書かれない、しかし コードの挙動を決定的に左右する判断 だ。AI はこれらをすべて無音で下し、diff にだけ反映する。

人間レビュアは「なぜ」を再現できない

diff に現れるのは「何が変わったか」だけだ。「なぜそう変えたか」は AI の頭の中（実際にはコンテキスト）にしかない。人間レビュアが diff を見ても、AI の判断の正当性を再現的に検証することはできない。

これは人間のエンジニアがコードを書いた場合との決定的な違いだ。人間のエンジニアの場合：

  • 隣の席で議論した（口頭で「なぜ」が共有されている）
  • Slack で相談した（履歴に残っている）
  • ペアプロした（同時に判断を見ている）

AI コーディングでは、これら全部が 存在しない。判断は AI と仕様の間の一回限りの相互作用で発生し、終了後に消える。

計画レビューだけでは drift を捕捉できない

「事前に計画をレビューしたから安心」というアプローチは AI コーディングだと機能しない。なぜなら、

  • 計画書は実装中のすべての micro-decision を網羅できない
  • AI は計画書に従ったつもりでも、実装中に独自判断で逸脱する
  • 計画と実装の gap は 誰も監査していない

計画レビュー → 実装 → そのままマージ、というフローでは「計画書通りに実装されたか」を検証する仕組みが存在しない。ドキュメントが乖離しても誰も気づかない。

AI 実装は速いので、計画の沈没コストが低い

人間がコードを書く時代の計画レビューには「実装コスト » 計画コスト」という前提があった。だから事前に計画を固めることに大きな価値があった。

AI コーディングだと「実装コストも計画コストも、どちらもほぼゼロ」になる。計画を捨てて作り直すのが現実的選択肢になる。すると計画レビューの相対的価値は下がる。

逆に、実装の中身を事後監査する implementation-notes の相対的価値が上がる。

計画レビューが依然として強い場面

ただし、計画レビューが不要になるわけではない。次のケースでは依然として強い。

  • スコープや方針に複数のステークホルダー間で対立がある — 合意形成自体が目的。実装前に決めないと話が前に進まない
  • 実装コスト » 計画コスト が成立する領域 — インフラ変更、スキーマ移行、外部 API 契約のように「やり直しが効かない」もの
  • 外部依存を巻き込む — 他チーム、ベンダー、CI/CD パイプラインなど、変更の波及が大きいもの
  • 計画自体が成果物になる — ADR（Architecture Decision Record）、RFC、設計ドキュメント

これらは AI が高速で書き直せる範囲を超えている。計画レビューは「合意形成のプロトコル」として残る。

統合パターン — 計画 → 実装 → implementation-notes が直列で最強

前節で見たとおり両者は別レイヤーなので、直列に組み合わせるのが実務的な落とし所だ。

1
2
3
4
5
6
7
8
9

仕様
  ↓
計画（必要に応じて事前レビュー）   ← 方向性の事前合意
  ↓
実装
  ↓
implementation-notes              ← 計画からの逸脱を事後可視化
  ↓
人間レビュー（計画 + ノート + diff）

この構造のポイント：

  1. 計画は「方向性の事前合意」のため — 大筋を間違えないため
  2. ノートは「実装中の判断の事後可視化」のため — 大筋に従ったつもりの微小逸脱を捕捉するため
  3. ノートは「計画との差分」を明示する — これにより、計画ドキュメント自体の drift も検出される

Claude Code の Plan Mode + 通常モード + CLAUDE.md への記録、というフローは、まさにこの統合パターンを自然に実現している。

意思決定ログがあると何が変わるか

implementation-notes を残すことで、実務上次のような変化が起きる。

あとから修正しやすくなる。 「なぜこの実装になったのか」がわかれば、変更のリスクも見積もれる。理由のわからないコードを変えるのは怖い。理由が書いてあるコードは変えやすい。

次の AI に引き継ぎやすくなる。 Claude Code を使って実装を継続する際、前のセッションで何を決めたかを新しいセッション開始時に渡せる（コンテキスト引き継ぎ）。会話が切れても設計方針がブレにくくなる。

仕様と実装のズレに気づける。 AI が「仕様にはこう書いてあったが、実際にはこうしました」と書いてくれると、設計上の問題が表面化する。仕様書を更新するきっかけにもなる。

人間がレビューしやすくなる。 コードレビューは「このコードが正しいか」だけでなく「この判断が正しいか」を確認する行為でもある。判断が記録されていればレビューの質が上がる。

残し方：どこに implementation-notes を書くか

ここまでで「実装中の判断を記録する」という方針は決まったとして、どこに書くか は実は単純ではない。残し方を間違えると、せっかくの意思決定ログが活用されない。

代表的な選択肢を比較する。

残し方機能単位の物理隔離計画との対比AI の固定パス読み完了時スナップショット
CLAUDE.md に追記❌ 機能混在❌⚠️ プロジェクト共有ファイルが肥大化❌ 上書き運用
単一 docs/implementation-notes.md❌ 機能混在❌✅❌ 上書き
コミットメッセージに埋め込む⚠️ PR 単位❌❌ git log は固定パスから読みづらい✅
変更単位ディレクトリに置く（OpenSpec 流）✅ 変更単位✅ 同ディレクトリで proposal/design と並置✅✅ archive で固定

CLAUDE.md 追記や単一ファイル運用には致命的な弱点がある。機能の物理隔離がなく、複数機能を並行開発するとノートが混在する。さらに「計画」と「ノート」が別ファイルに散らばるので、計画からの逸脱を物理的に対比できない。

これを構造的に解くのが OpenSpec 流の 変更単位ディレクトリ だ。

OpenSpec 流：変更単位ディレクトリに第5のアーティファクトとして置く

OpenSpec は変更ごとに proposal.md（Why）/ design.md（How）/ tasks.md（Do）/ specs/（What）の 4 アーティファクトを生成する仕様駆動開発フレームワークだ。

implementation-notes.md は、ここに 第5のアーティファクトとして自然に組み込める。

1
2
3
4
5

docs/changes/2026-05-20-jwt-auth/
├── proposal.md           # Why: なぜ JWT 認証を入れるか
├── design.md             # How: アルゴリズム選定、フロー設計
├── tasks.md              # Do: 実装チェックリスト
└── implementation-notes.md  # ← 実装中の判断・逸脱をここに残す

この配置のメリット:

  • 計画と実装ノートが同じディレクトリで対比できる — design.md で「HS256 を採用」と書き、implementation-notes.md に「予定通り HS256」「ただし鍵長は仕様外で 256bit を選択」と残せる
  • archive 時にスナップショットとして固定される — docs/changes/archive/2026-05-20-jwt-auth/ に移送されると、その時点の判断がそのまま残る
  • AI に「該当 change ディレクトリだけ読ませる」運用と整合 — 並行開発中の他機能のノートが混入しない
  • PR レビュー時に「計画 → 実装 → ノート」が1ディレクトリで完結する — レビュアは proposal → design → tasks → notes の順に読めば全文脈が得られる

既存 docs/ 運用でも構造だけ真似られる

OpenSpec を導入していなくても、すでに mkdocs + docs/ 運用しているプロジェクトなら、ディレクトリ構造だけ真似る だけで同じ効果が得られる。具体的なリポジトリ規約の書き方は OpenSpec 記事の「docs-structure.md + GitHub Issue で初期化する」を参照のこと。

implementation-notes.md のテンプレート

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Implementation Notes — JWT 認証

## 仕様外の判断

### 鍵長: 256bit を採用
- 仕様には記載なし
- 理由: セキュリティとパフォーマンスのバランス。128bit は将来の量子耐性で懸念

### リフレッシュトークンの有効期限: 7日
- 仕様には「適切な期間」とだけ記載
- 理由: UX 上のセッション切れ頻度とセキュリティのバランス

## 計画からの逸脱

### design.md では Redis ベースのトークン無効化リストを採用予定だったが、PostgreSQL に変更
- 理由: 現プロジェクトには Redis インフラがなく、追加コストが見合わない
- トレードオフ: 無効化チェックの遅延が +5ms 程度（許容範囲）
- 将来 Redis を導入する場合は再検討

## 妥協点

### エラーハンドリングの粒度
- 仕様で詳細指定がなかったため、4xx / 5xx の区別のみ実装
- 詳細なエラーコード体系は次フェーズの課題として `tasks.md` 末尾に追記

## 将来要再検討

- HS256 → RS256 への移行（マルチサービス化の際）
- トークンローテーション戦略

「仕様外の判断」「計画からの逸脱」「妥協点」「将来要再検討」の 4 セクションに分けると、レビュアが読みやすく、AI も追記時の判断がしやすい。

プロンプトテンプレートとして使う

このプロンプトは汎用テンプレートとして整理できる。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

## タスク
[ここに何を実装するかを書く]

## 仕様書 / 要件
[ここに仕様や要件を書く]

## 指示
上記の仕様に従って実装してください。
実装中に発生した以下の内容をすべて `implementation-notes` セクションとして
出力の末尾に追記してください：

- 仕様に記載のなかった判断
- 複数の選択肢から選んだ場合の理由
- 妥協した点とその背景
- 将来的に変更が必要になりそうな箇所
- 計画 / 想定からの逸脱（あれば、なぜ逸脱したか）

最後の項目「計画からの逸脱」は、計画レビューと組み合わせる際にとくに重要だ。計画と実装の gap を明示的に可視化する役割を果たす。

まとめ — AI コーディング時代の監査レイヤー

implementation-notes は計画ドキュメントの 代替 ではない。計画レビューでは原理的にカバーできない「サイレント逸脱問題」を解く、別レイヤーの監査メカニズムだ。

  • 計画レビュー = 方向性の事前合意 （事前監査）
  • implementation-notes = 判断の事後可視化 （事後監査）
  • 両者を 直列に組み合わせる ことで、AI コーディングの品質を担保する
  • 残し方は OpenSpec 流の変更単位ディレクトリ に第 5 のアーティファクトとして置くのが構造的に最も強い

Anthropic 社員が「いちばん使っている」と紹介された implementation-notes プロンプトが示唆するのは、AI コーディング時代における リスク構造の非対称性 だ。方向性の間違いよりも、サイレントな micro-decision の累積のほうが、実務的にはるかに支配的なリスクになる。

「実装して」だけではなく、「なぜそうしたかも残して」までが AI コーディングの完了条件になる。

元ツイート: Claude Code Studio (@ClaudeCode_love) — 2026-05-19