はじめに
Plan Modeを使っているのに、手戻りがなかなか減らない。
「計画を立てて実装したはずなのに、エッジケースが漏れていた」「テストを後から書いたら、実装の形に合わせたテストになってしまった」「仕様が曖昧なまま進めたせいで、実装途中で方向を変えることになった」——Plan Modeの基本は身についているのに、こういった状況が続いているなら、問題は計画の「立て方」にある。
Plan Modeの基本操作（Shift+Tab×2での起動、Explore→Plan→Implementの3段階ワークフロー）についてはClaude Code Plan Modeを使いこなす——「探索→計画→実装」で手戻りをゼロにする技術で解説しています。本記事はその先の話だ。
計画の品質を左右するのは、初回の計画をどれだけ正確に修正できるか（計画の洗練度）、実装前に要件の曖昧さをどこまで除去できるか（仕様の明確度）、テスト計画を実装バイアスなしに立てられるか（検証の網羅度）——この3点だ。それぞれに対応するテクニックが本記事の主題になる。
アノテーションサイクル——計画を1〜6回反復して洗練させる
「計画を立てたら即実装」は間違い
多くのエンジニアはplan.mdが生成されたら即実装に移る。しかしClaude Codeを9ヶ月間使い続けたエンジニアのBoris Tane氏は、そのアプローチに限界があると語っている。
> 「Claudeは優れたコード理解と提案能力を持つが、プロダクト優先度を知らず、ユーザーの痛点を理解していない。アノテーションサイクルで開発者の判断を計画に注入することが不可欠だ」
Claudeが自動生成した計画は、コードベースの構造や一般的なベストプラクティスを踏まえた「汎用的な計画」だ。しかし「このシステムの命名規則に合わせたもの」「このチームの技術的制約を考慮したもの」にするには、開発者の判断を計画に注入する必要がある。
アノテーションサイクルのプロセス
1. Claudeが plan.md を作成
↓
- Ctrl+G でエディタを開いてインラインノートを直接追加
↓
- Claudeにプロンプトを送る：
「I added a few notes to the document, address all the notes
and update the document accordingly. don't implement yet」
（訳：文書にメモを追加しました。全てのメモに対応して文書を更新してください。まだ実装しないでください）
↓
- 満足するまで2〜3を繰り返す（通常1〜6ラウンド）
↓
- Todoリストを追加させてから実装開始
「add a detailed todo list with all phases and tasks.
don't implement yet.」
（訳：全フェーズとタスクを含む詳細なTodoリストを追加してください。まだ実装しないでください）
don't implement yet（まだ実装しないで）のガードフレーズは必須だ。これを入れないと、アノテーション中にClaudeが実装を開始してしまう。
インラインノートの実例と分類
ノートの種類は大きく3パターンで、長さは2語から段落まで何でもよい。
# ドメイン知識を注入（Claudeが持てない情報）
use drizzle:generate for migrations, not raw SQL
（訳：マイグレーションはdrizzle:generateを使ってください。生のSQLではなく）
# 誤った仮定を修正
no — this should be a PATCH, not a PUT
（訳：いいえ——これはPUTではなくPATCHにすべきです）
# 不要なアプローチを除去
remove this section entirely, we don't need caching here
（訳：このセクションを完全に削除してください。ここでキャッシュは不要です）
なぜMarkdownファイルがチャットより優れるか
チャット会話での計画修正は、過去の決定をスクロールして再構築しながらフィードバックを書く必要がある。plan.mdへのアノテーションは、完全な仕様を一度に確認でき、問題の正確な箇所に直接修正を記述できる。Markdownファイルが「開発者とClaude間の共有可変状態」として機能するため、コンテキストを失わずに反復できる。
1ラウンド目は汎用的な実装計画（「こういう機能を追加するには一般的にはこうする」）。3ラウンド目には、既存システムに完璧にフィットした計画（「このコードベースの命名規則・既存パターン・技術的制約を全て考慮した計画」）になる。この変化がアノテーションサイクルの本質的な価値だ。
仕様インタビュー＋セッション分離——Claudeにインタビュアーになってもらう
Plan Modeの前段階：仕様の曖昧さを除去する
Plan Modeで計画を立てる前に、「そもそも何を実装するか」が曖昧なまま進んでいないだろうか。仕様インタビューパターンはこの問題を解決する。エンジニアのThariq（@trq212）氏が実践・公開しているアプローチで、AskUserQuestionツールを活用して仕様を明確化するものだ。
プロセス
Session 1: 仕様策定
┌──────────────────────────────────────────┐
│ 1. 最小限の方向性だけ用意 │
│ ↓ │
│ 2. Claudeにインタビュアーになってもらう │
│ 「この機能について技術実装・UI/UX・ │
│ エッジケース・トレードオフの観点から │
│ AskUserQuestionで質問して仕様を │
│ 明確化して」 │
│ ↓ │
│ 3. 回答→質問のサイクルで仕様が明確化 │
│ ↓ │
│ 4. spec.md として文書化 │
└──────────────────────────────────────────┘
↓
Session 2: 計画・実装
┌──────────────────────────────────────────┐
│ spec.md を入力に、クリーンなコンテキストで│
│ Plan Mode → 実装 │
└──────────────────────────────────────────┘
セッションを分離する理由
仕様策定の試行錯誤がコンテキストに残ると、実装セッションに「仕様を決める時に浮かんだアイデア」「一度否定したアプローチ」が混入する。新しいセッションはクリーンなコンテキストでspec.mdという完成した入力から始められる。
Claudeが引き出す視点
自分一人で仕様を考えていると意外と出てこないが、Claudeのインタビューでよく出てくる観点がある。
「エラー状態はどう扱いますか？」——エラーハンドリングの仕様を事前に決める。「既存の[関連機能]との整合性はどう担保しますか？」——影響範囲を事前に特定する。「スケールした場合のパフォーマンス要件はありますか？」——アーキテクチャの選択に影響する前提を明確化する。
完璧な仕様書を最初から用意する必要はない。「ざっくりした方向性」があれば、Claudeのインタビューが残りを引き出してくれる。
検証フェーズでのPlan Mode活用——実装後の「独立したテスト計画」
見落とされがちなPlan Modeの使いどころ
多くのエンジニアは実装フェーズでのみPlan Modeを使う。しかし検証フェーズでも同様に有効だ。Anthropicが実践・推奨しているアプローチで（@bcherny、2026年2月）、実装後の品質担保に活用できる。
実装した直後のセッションでテスト計画を立てると、テストが「実装を知っているClaude」によって書かれる。その結果、実装の抜け道を許したテストができあがる——これはコンテキスト汚染の問題と同じメカニズムだ。
Plan Modeを使うことで、Claudeを「テスト計画を立てるだけ」に制限できる。
実装後のPlan Mode活用プロンプト
# 実装完了後、Plan Modeに入ってから：
「この実装の検証戦略を立案して。
以下の観点を網羅すること：
- 正常系・異常系・境界値テストケース
- エッジケースと例外パス
- 既存機能への影響（リグレッション）
- 統合テストが必要な箇所
テスト実行は始めないで。まず計画だけ」
Plan Modeで立てたテスト計画をアノテーション
実装を知っているからこそ、テスト計画への適切なアノテーションができる。
# 見落とされているエッジケースを追加
concurrent requestsのケースが抜けている。追加して
（訳：並行リクエストのケースが抜けています。追加してください）
# 既存テストとの重複を削除
このケースは existing_test.ts で既にカバー済み。削除して
# 優先度を明記
このテストは本番クリティカル。最初に実装して
3つのテクニックの組み合わせパターン
大規模機能開発のフルフロー
Session 1: 仕様インタビュー
「AskUserQuestionで仕様を明確化して → spec.md に保存」
↓
Session 2: 計画（Plan Mode）
「spec.md を元に plan.md を作成 → アノテーション1〜3回 → dont implement」
↓
Session 3: ダブルレビュー
「別セッションでスタッフエンジニアとして plan.md をレビュー」
↓
Session 4: 実装
「implement it all. mark tasks as completed. dont stop until done.」
（訳：全て実装してください。完了したタスクをマークしながら、完了するまで止まらないでください）
↓
Session 5: 検証計画（Plan Mode）
「実装の検証戦略を Plan Mode で立案 → アノテーション」
↓
Session 6: テスト実装
「テスト計画を実装して」
「6セッションは多すぎる」と感じるかもしれない。しかしセッションを細かく分けることで、各セッションのコンテキストが汚染されない。私の経験では、フルフローを通じた合計時間は「計画なしで実装→手戻りを修正」のサイクルより短かった。
小〜中規模タスクのシンプルフロー
まずここから始めてほしい。
Plan Mode: アノテーションサイクル1〜2ラウンド
↓
実装: 「implement it all」
↓
検証Plan Mode: テスト計画立案
アノテーションサイクル1ラウンドだけでも、計画の質は明確に変わる。5分の追加で手戻りを防げるなら十分に価値がある。
ビフォーアフター
Before（基本Plan Modeのみ）
Shift+Tab×2 → 計画生成 → 即実装。「計画通りに実装してもらったが、いざ動かしたらエッジケースが漏れていた」「テストを後付けで書いたが、実装の形に合わせたテストになってしまった」。手戻りとバグが続く。
After（3つのテクニック活用）
Session 1で仕様インタビューをこなして要件の曖昧さをゼロにする。Session 2でPlan Mode＋アノテーション3ラウンドで「既存システムに完璧にフィットした計画」に洗練させる。Session 3で1回の「implement it all」で完成。Session 4で検証Plan Modeにより実装バイアスのないテスト計画を立てる。手戻りが消え、テストが本物の品質保証として機能する。
まとめ：今日からできること
- 今すぐ（5分）: 現在進行中のタスクのplan.mdを
Ctrl+Gで開き、1つだけインラインノートを追加してアノテーションサイクルを体験する - 今日中: 次の新機能開発を「仕様インタビューSession → 計画Session」の2セッション分離で試す
- 今週: 直近の実装に対して「検証フェーズのPlan Mode」を試し、実装後に独立したテスト計画を立てる
- CLAUDE.mdに追加:
## 計画ルールとして「複雑なタスクはアノテーションを最低2回行ってから実装する」を記述する
Plan Modeは「計画を作るツール」から「計画を洗練させるサイクルの起点」に変わる。アノテーションサイクルを1回試すだけで、その感覚はすぐに分かる。
コメント