Boris Tane氏の Claude Code 3フェーズワークフロー：リサーチ→プラン→実装を徹底解説
Shuです。普段はAIツール、特にClaude Codeで遊んでいます。
Claude Codeを使い始めてから、「プロンプトをどう書けば本当に効果的なのか」をずっと試行錯誤していました。そんなときに、Boris Tane氏のブログ記事 "How I Use Claude Code" を読んで非常に参考になったので、日本語でまとめつつ自分の考えを加えて紹介します。
Boris氏はCloudflareでエンジニアとして働きながら個人プロダクトも開発している方で、Claude Codeを実務で使い込んでいる経験から生まれたワークフローを公開されています。
ワークフローの全体像
Boris氏のClaude Code活用法の核心となる原則はシンプルです。
「コードを書かせる前に、必ず書面によるプランをレビュー・承認する」
この一言に全てが詰まっています。Claude Codeに対してすぐに実装を依頼するのではなく、リサーチとプランニングを先行させることで、手戻りを最小化するアプローチです。
以下の3つのフェーズで構成されています：
- フェーズ1: リサーチ - コードベースを深く理解させ、ファイルに記録する
- フェーズ2: プランニング - 詳細な実装計画をMarkdownに書かせ、アノテーションで精錬する
- フェーズ3: 実装 - 承認済みのプランを一気に実装させる
それぞれのフェーズについて詳しく紹介します。
フェーズ1: リサーチ
何をするか
新しい機能実装やバグ修正を始める前に、Claude Codeにコードベースを深く読み込ませ、その結果を research.md というファイルに書き出させます。
なぜ重要か
Boris氏が最も高コストな失敗として挙げているのが、「実装が既存のシステムを壊す」という事態です。コンテキストを把握しないままコードを書かせると、既存の設計と噛み合わない実装になってしまいます。
リサーチフェーズで重要なのは、表面的な読み取りをさせないこと。プロンプトに "deeply"（深く）や "in great detail"（詳細に）といった言葉を意識的に含めることで、Claude Codeが大雑把に走り抜けてしまうのを防ぎます。
プロンプト例
Before writing any code, deeply research the codebase and understand
how authentication currently works in great detail.
Document your findings in research.md, including:
- Current architecture
- Key files and their responsibilities
- Potential impact areas for the change
なぜファイルに記録させるか
これが非常に重要なポイントで、research.md のようなファイルに書き出させることで、セッションのコンテキストが圧縮されても情報が永続化されます。Claude Codeは長いセッションになると古いコンテキストを圧縮してしまいますが、ファイルに書かれた内容は残り続けます。
フェーズ2: プランニング
plan.mdを作らせる
リサーチが終わったら、次は plan.md に詳細な実装計画を書かせます。このプランには以下が含まれます：
- アプローチの説明
- 重要なコードスニペット
- 変更が必要なファイルのパス
- トレードオフの検討
アノテーションサイクル（最重要）
プランができたら、いきなり実装を依頼してはいけません。インラインでメモ（アノテーション）を書き込み、Claudeにプランを更新させるというサイクルを1〜6回繰り返します。
plan.md を直接編集して、自分のコメントを斜体で書き込みます：
## Step 3: データベースマイグレーション
生のSQLファイルを作成して...
*use drizzle:generate for migrations, not raw SQL*
## Step 5: APIエンドポイントの更新
このエンドポイントはPUTメソッドで...
*no — this should be a PATCH, not a PUT*
## Step 8: キャッシュレイヤーの追加
Redis接続を新たに...
*remove this section entirely*
そしてClaudeには：
Update the plan based on my annotations.
Don't implement yet.
と依頼します。「Don't implement yet」（まだ実装しないで） という一言を必ず添えるのがポイントです。
なぜこのアノテーションサイクルが効果的か
このやり方の優れている点は、技術的選択の主導権を常に人間が持ち続けられる点です。
Claude Codeは大抵の場合それなりの実装プランを提示しますが、「このプロジェクトではdrizzleを使う」「RESTの設計上PATCHが正しい」といったプロジェクト固有の知識や判断は、Claudeには持てません。アノテーションを通じて短いコメントで軌道修正できるため、長いプロンプトを書く必要がありません。
Todoリストを追加させる
プランが固まったら最後に、実装手順をTodoリスト形式で追加させます：
Add a todo list at the end of plan.md with all implementation steps
as checkboxes.
これにより実装フェーズでの進捗管理が楽になります。
フェーズ3: 実装
一気に実装させる
プランの承認が済んだら、Boris氏は以下のようなプロンプトで実装を依頼します：
implement it all.
mark each task as completed in the plan document as you go.
do not stop until all tasks and phases are completed.
continuously run typecheck.
このプロンプトのポイントは4つです：
-
implement it all- 部分実装ではなく全て実装させる -
mark it as completed in the plan document- plan.mdのTodoをチェックさせ進捗を可視化 -
do not stop until all tasks are completed- 途中で「確認しましょうか？」と止まらせない -
continuously run typecheck- 型エラーを随時検出させる
実装は「機械的な作業」になるべき
フェーズ2でしっかりプランを精錬しているため、フェーズ3は創造的な判断を必要としない機械的な作業になります。Boris氏が「実装は機械的な作業になるべき」と言っているのは、これが理想の状態だということです。
修正は短く
実装中に細かい修正が必要になった場合、長い説明は不要です。
- 「wider」（もっと広く）
- 「still cropped」（まだ切れている）
といった一言で十分です。プランで文脈を共有しているためです。
問題が大きければrevertして再スコープ
実装が迷走し始めたら、迷わず git revert してフェーズ2からやり直します。コンテキスト汚染を抱えたまま進めるより、きれいな状態からプランを見直す方が結果的に早いです。
1セッションで完結させる
Boris氏はリサーチから実装まで1つのセッションで完結させることを好んでいます。
セッションを分割すると、新しいセッションではコンテキストが失われます。research.md や plan.md はファイルとして残りますが、Claude Codeが実装中に積み上げた暗黙的なコンテキスト（「さっきこのファイルで変更したばかり」など）は失われます。
長い1セッションで完結させることで、コンテキストの連続性を保つわけです。
まとめ
Boris Tane氏のClaude Code活用ワークフローをまとめます。
コアの原則: コードを書かせる前に、必ず書面によるプランをレビュー・承認する
3フェーズワークフロー:
-
リサーチ (
research.md)- "deeply"、"in great detail" を使って深く読み込ませる
- ファイルに記録させてコンテキスト圧縮対策
-
プランニング (
plan.md)- 詳細な実装計画を作成させる
- アノテーションサイクルで人間が軌道修正（1〜6回）
- 「Don't implement yet」を必ず添える
- Todoリストを追加させて進捗管理
-
実装
- "implement it all...do not stop...continuously run typecheck"
- 実装は機械的な作業になるべき
- 問題が大きければgit revertして再プラン
個人的に特に参考になったのはアノテーションサイクルです。プロンプトで全てを伝えようとするのではなく、生成されたプランに直接書き込んでいくアプローチは、会話的で効率的だと感じました。
ぜひ自分の開発ワークフローに取り入れてみてください。
Xフォローしてくれると嬉しいです
Xでも情報発信しているので、フォローしていただけると励みになります！
参考文献
Discussion