■ 1. 計画なき実装という失敗
- Claude Code初学者が陥るパターン:
- プロンプトを打ち、エラーを修正し、また打つという繰り返しに終始する
- Claudeが誤った仮定の上に15分かけてコードを積み上げ、最終的に全部巻き戻す羽目になる
- 失敗の根本原因:
- 構文エラーでも論理バグでもなく、孤立しては動くが周囲のシステムを壊す実装にある
- 事前調査なしに実装へ突進することで生まれる
- 周囲を壊す実装の具体例:
- 既存のキャッシュレイヤーを無視する関数
- ORMの規約を考慮しないマイグレーション
- すでに存在するロジックを重複するAPIエンドポイント
- 出典と著者:
- Cloudflareエンジニアリングリード（前Baselime創業者）のBoris Tane氏が9ヶ月間の使用で確立したワークフロー
- 2026年2月10日公開の "How I Use Claude Code" が原典
- 想定読者:
- Claude Codeをある程度使っているが、大きなタスクで迷走してしまうと感じている開発者
■ 2. ワークフローの全体像
- 核心原則:
- 書面による計画を確認・承認するまでコードを書かせない
- 計画と実行を分離することで、無駄な作業を防ぎ、アーキテクチャ上の決定を自分の手元に置ける
- 4ステップのフロー:
- Research → Plan → Annotation Cycle（1〜6回） → Implementation
- 具体的な流れ:
- Claudeがコードベースを調査し、research.mdに結果を記録する
- 開発者がレビューし、Claudeがplan.mdを作成する
- 開発者がエディタでインラインノートを追加し、Claudeがノートを反映してplan.mdを更新する
- 満足するまで繰り返した後、Todoリストをplan.mdに追加する
- "implement it all" で実装を一気に開始する
- 各フェーズが防ぐ失敗:
- Researchは無知な変更、すなわち既存システムを理解せずに実装することを防ぐ
- Planning + Annotationは誤った変更、すなわち早期の誤った仮定の上に構築することを防ぐ
- Implementationは無秩序な実装、すなわち途中で方向転換を繰り返すことを防ぐ
■ 3. Phase 1: Research
- Deep Read Directive:
- 表面的な読み込みではなく深く理解することを明示的に指示するプロンプトパターン
- 通常のClaudeはファイルを開き、関数のシグネチャレベルで理解してそのまま先へ進む
- それでは周辺システムとの依存関係や暗黙の規約を見落とす
- フォルダ全体を理解させるプロンプト:
- read this folder in depth, understand how it works deeply, what it does and all its specificities. when that's done, write a detailed report of your learnings and findings in research.md
- 特定システムを調査するプロンプト:
- study the notification system in great details, understand the intricacies of it and write a detailed research.md document with everything there is to know about how notifications work
- バグを探すプロンプト:
- go through the task scheduling flow, understand it deeply and look for potential bugs
- バグが確実に存在する根拠を伝え、すべて見つけるまで止まらずに調査を継続させ、research.mdに報告させる
- 効果を左右するキーワード:
- "deeply" は深い分析を要求する
- "in great details" は詳細な調査を促す
- "intricacies" は複雑な仕組みまで調べさせる
- "keep researching... until" は止まらずに調査を継続させる
- これらの言葉は飾りではなく、なければClaudeはスキミングする
- research.mdに書かせる理由:
- レビュー面として機能し、Claudeが本当にシステムを理解しているかを検証できる
- 調査が間違えば計画も実装も間違うため、誤りを最も早い段階で捕捉できる
- ファイルとして残るため、セッション中にコンテキストが圧縮されても参照できる
■ 4. Phase 2: Planning
- 組み込みPlan Modeを使わない理由:
- エディタで直接編集でき、次のAnnotation Cycleの核心となる操作が可能になる
- プロジェクトの実成果物として残り、セッションを超えて参照できる
- ファイルシステム上に存在するため、コンテキスト圧縮を乗り越えられる
- 新機能を計画するプロンプト:
- 機能名と説明、実現するビジネス上の成果を示し、詳細なplan.mdをコードスニペット込みで書かせる
- 既存機能の変更を計画するプロンプト:
- listエンドポイントをオフセットからカーソルベースのページネーションに変更する方法をplan.mdに書かせる
- "read source files before suggesting changes" を明示し、実際のコードベースに基づかせる
- これによりコードベースを読まずに一般的な実装パターンを提案することを防ぐ
- 参照実装を活用するテクニック:
- オープンソースで良い実装を見つけたら、そのコードを参照として共有すると劇的に良い結果が得られる
- ソータブルIDの実装例を示し、同様のアプローチを採用する方法をplan.mdに説明させる
- ゼロから設計させるより、実際のコードの形・データ構造・エッジケースの扱い方を正確に把握した計画が立つ
■ 5. Annotation Cycle
- ワークフロー全体の価値の大半を担う工程:
- plan.mdにインラインノートを直接書き込み、Claudeに更新させることを1〜6回繰り返す
- ドメイン知識、製品優先順位、エンジニアリング上のトレードオフを計画に注入する唯一の場所
- 手順:
- Claudeが作成したplan.mdをエディタで開き、問題のある箇所にインラインノートを直接追加する
- ノートをすべて反映してドキュメントを更新するよう指示し、まだ実装しないよう明示する
- 満足するまでこの往復を繰り返す
- 最後に、全フェーズと個々のタスクを含む詳細なTodoリストを計画に追加させる
- インラインノートの5パターン:
- ドメイン知識の注入は "use drizzle:generate for migrations, not raw SQL" のように未知の制約を伝える
- 誤った仮定の修正は "no — this should be a PATCH, not a PUT" のようにHTTPメソッドの誤りを直す
- アプローチの却下は "remove this section entirely, we don't need caching here" のように不要な実装を削る
- 短い指摘は "not optional" の2語でパラメータの必須性を修正する
- セクション全体のリダイレクトは、可視性フィールドの持ち先が誤っている旨とスキーマ節の再構成を指示する
- ノートの粒度:
- 長さは2語から段落まで状況によって異なる
- 重要なのは問題のある箇所に直接書き込むこと
- "don't implement yet" ガード:
- 明示しなければ、Claudeは計画が十分になったと判断した瞬間に実装を開始する
- 計画の完成を判断するのはClaude自身ではなく開発者である
- 常に使うことで判断権を手元に置き続けられる
- 有効である理由:
- Markdownファイルが共有可変状態として機能する
- 正確な箇所を指摘できるため精度が上がり、Claudeの理解がずれない
- 段落で説明する代わりに問題箇所に2語で書けばよく効率が上がる
- このプロジェクトではdrizzle:generateを使うといったドメイン知識が計画に蓄積される
- 3ラウンドの効果:
- 3ラウンドの "added notes, update the plan" で、汎用的な実装計画を既存システムに完璧にフィットする計画へ変えられる
- Todoリストによる進捗可視化:
- Annotation Cycleの最後に追加したリストが実装フェーズ全体の進捗トラッカーになる
- Claudeがタスク完了ごとにリストを更新するため、数時間のセッションでも現在地を一目で把握できる
■ 6. Phase 3: Implementation
- 標準実装プロンプト:
- ほぼすべての実装セッションで同一のプロンプトをそのまま再利用する
- implement it all. when you're done with a task or phase, mark it as completed in the plan document. do not stop until all tasks and phases are completed. do not add unnecessary comments or jsdocs, do not use any or unknown types. continuously run typecheck to make sure you're not introducing new issues.
- 各フレーズの意図:
- "implement it all" は計画のすべてを実行させる
- "mark it as completed in the plan document" は計画を進捗の唯一の信頼できる情報源とする
- "do not stop until all tasks and phases are completed" は途中で確認を求めさせず中断なく実行させる
- "do not add unnecessary comments or jsdocs" はコードをクリーンに保つ
- "do not use any or unknown types" はTypeScriptにおける厳密な型付けを維持する
- "continuously run typecheck" は問題を最後ではなく途中で検出する
- 実装はつまらないほど良い:
- 計画が正しければ実装は機械的な作業になる
- 創造的な判断はAnnotation Cycleで終わっており、実装はボーリング（退屈）であることが望ましい
- 実装中のフィードバックは短くする:
- 計画段階のノートが段落レベルなら、実装中の修正は1文で十分である
- Claudeはセッション全体の文脈を持つため、短い指摘でも意図を理解できる
- "wider"、"still cropped"、"there's a 2px gap" のような指摘で足りる
- 特定関数を未実装である旨や、設置先アプリを誤っている旨も1文で伝える
- 視覚的問題の伝達:
- フロントエンドではスクリーンショットを添付することで視覚的な問題を素早く伝えられる
- 既存コードの参照:
- このテーブルをusersテーブルと全く同じ見た目、同じヘッダー、同じページネーション、同じ行密度にすると指示する
- 既存コードを参照することで暗黙の要件をすべて伝えられる
- 間違った方向に進んだらリバート:
- 段階的な修正より、リバートしてスコープを絞る方が速い結果につながる
- すべてリバートした上で、リストビューをよりミニマルにすることだけを求めると宣言し直す
- 悪いアプローチをパッチで修正するより、gitで変更を捨てスコープを絞って再実行する方が常によい結果を生む
■ 7. Single Long Session戦略
- 1セッションで完結させる:
- Research、Planning、Implementationを1つのセッションで完結させる
- セッションの分割は情報損失を招く
- 典型的なセッションの流れ:
- フォルダの深読みから開始する
- 計画のAnnotation Cycleを3ラウンド行う
- 完全な実装を実行する
- これらをすべて単一の継続的な会話で行う
- コンテキスト50%超で性能劣化するという通説:
- 自身の経験上、この劣化は確認していない
- むしろ逆で、"implement it all" と言う時点でClaudeはセッション全体を通じて理解を積み上げている
- 調査中にファイルを読み、Annotation Cycleでメンタルモデルを精緻化し、ドメイン知識の修正を吸収している
- 積み上げた理解がコードベースに即した実装を可能にする
- コンテキスト圧縮への耐性:
- コンテキストウィンドウが満杯になると自動圧縮が実行される
- plan.mdとresearch.mdはファイルシステム上の永続的な成果物であり、圧縮が発生しても完全な状態で残る
- 任意の時点で "refer to plan.md" と指示すれば文脈を即座に取り戻せる
■ 8. ハンズオン例: カーソルページネーション
- シナリオ:
- 既存のAPIエンドポイントに、オフセットベースではなくカーソルベースのページネーションを追加する
- Step 1 Research:
- 対象ファイルのlistエンドポイントを詳細に調査させ、現在のページネーション、データモデル、ORM固有の規約を理解させる
- 発見内容を詳細なresearch.mdに書かせる
- 現在はoffsetとlimitを使う、ORMはDrizzleを使う、既存のレスポンス型はListItemである、といった事実が正確かを自分で確認する
- 誤解があればこの時点で修正を指示する
- Step 2 Plan:
- 調査結果を確認してから、カーソルベースへの移行方法を説明する詳細なplan.mdをコードスニペット込みで作成させる
- "read the source files before suggesting changes" の指示が重要である
- これにより一般的なカーソルページネーションのパターンではなく、このコードベースの実際の構造に基づく計画が生まれる
- Step 3 Annotation Cycle:
- カーソルの主フィールドをid、副ソートキーをcreatedAtとし、base64で単一文字列にエンコードすべきとノートする
- 最初のページにはカーソルがないため、カーソルはオプショナルであるべきとノートする
- マイグレーションはraw SQLではなくdrizzle:generateを使い、規約はresearch.mdを参照するようノートする
- ノート反映を指示して更新させ、必要なら再度ノートを追加して繰り返す
- 計画が正確だと判断したらTodoリストを追加させる
- Step 4 Implementation:
- 標準実装プロンプトで実装を開始する
- 実装中は必要に応じて短い修正指示を出すだけでよく、計画が正確であれば実装はほぼ機械的に進む
■ 9. まとめと導入手順
- ワークフローの一文要約:
- 深く読み、計画を書き、正しくなるまで計画に注釈をつける
- その後Claudeに途中で止まらずすべてを実行させ、その間中型チェックを続ける
- 特別な仕掛けは不要:
- 魔法のプロンプトも、精巧なシステム指示も、巧妙なハックもない
- 思考と実装を分離する、規律あるパイプラインがあるだけである
- 段階的な始め方:
- まず次のタスクをPlan Modeの代わりにresearch.mdから始める
- 次に "don't implement yet" を意識的に使い始める
- そしてplan.mdにインラインノートを書き込むAnnotation Cycleを1回だけ試す
- 各フェーズの役割と成果物:
- Researchはコードベースを深く理解し、research.mdを産出する
- Planningは実装計画を立て、plan.mdを産出する
- Annotation Cycleはドメイン知識と判断を計画に注入し、更新されたplan.mdとTodoリストを産出する
- Implementationは承認済み計画を機械的に実行し、コードを産出する
- 実践による効果:
- 計画なきAIコーディングの混乱から抜け出し、AIを道具として制御下に置ける