0. はじめに
Claude Codeを使い始めた多くの開発者が陥るパターンがあります。プロンプトを打ち込み、エラーを修正し、また打ち込む。これを繰り返しているうちに、Claudeが誤った仮定の上に15分かけてコードを積み上げ、最終的に全部巻き戻す羽目になる、というものです。
この失敗の根本原因は「計画なき実装」にあります。AIコーディングツールの本質的な問題は構文エラーでも論理バグでもなく、孤立しては動くが周囲のシステムを壊す実装です。既存のキャッシュレイヤーを無視する関数、ORMの規約を考慮しないマイグレーション、すでに存在するロジックを重複するAPIエンドポイント。これらはすべて、事前調査なしに実装へ突進することで生まれます。
ここで紹介するのは、Boris Tane氏が9ヶ月間Claude Codeを使い続けて確立したワークフローです。Boris Tane氏はCloudflare エンジニアリングリード（前 Baselime 創業者）で、2026年2月10日に "How I Use Claude Code"（https://boristane.com/blog/how-i-use-claude-code/ ）というブログ記事を公開しました。このワークフローの核心は一言でいえば「書面による計画を確認・承認するまでコードを書かせない」です。
この方法論を日本語で解説し、すぐに実践できる具体的なプロンプト例とともに紹介する。対象は、Claude Codeをある程度使っているが「もっとうまく使いたい」「大きなタスクで迷走してしまう」と感じている開発者だ。
1. ワークフローの全体像
核心原則
書面による計画を確認・承認するまでコードを書かせない
この一文がすべてです。計画と実行を分離することで、無駄な作業を防ぎ、アーキテクチャ上の決定を自分の手元に置けます。
4ステップのフロー
Research → Plan → Annotation Cycle（1〜6回） → Implementation
テキストで表すと次のようになります。
Claudeがコードベースを調査する
↓
research.md に調査結果を記録する
↓ 開発者がレビューする
Claudeが plan.md を作成する
↓ 開発者がエディタでインラインノートを追加する
Claudeがノートを反映して plan.md を更新する
↓（満足するまで繰り返す）
Todoリストを plan.md に追加する
↓
"implement it all" で実装を一気に開始する
↓
完成
なぜこれが機能するのか
このワークフローは、AIコーディングにおける3つの主要な失敗パターンを各フェーズで防ぎます。
| フェーズ | 防ぐ失敗パターン |
|---|---|
| Research | 無知な変更（既存システムを理解せずに実装する） |
| Planning + Annotation | 誤った変更（早期の誤った仮定の上に構築する） |
| Implementation | 無秩序な実装（途中で方向転換を繰り返す） |
2. Phase 1 — Research
Deep Read Directiveとは
タスクは「深読み指示」から始まります。Deep Read Directiveとは、Claudeに表面的な読み込みではなく「深く理解すること」を明示的に指示するプロンプトパターンです。
通常、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
（日本語訳: このフォルダを深く読み込み、どのように動作するか、何をするものか、その特性をすべて深く理解してください。完了したら、学んだことと発見を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
（日本語訳: 通知システムを詳細に調査し、その複雑な仕組みを理解して、通知がどのように機能するかについてすべてを記載した詳細なresearch.mdドキュメントを書いてください。）
バグを探す場合。
go through the task scheduling flow, understand it deeply and look for potential bugs. there definitely are bugs in the system as it sometimes runs tasks that should have been cancelled. keep researching the flow until you find all the bugs, don't stop until all the bugs are found. when you're done, write a detailed report of your findings in research.md
（日本語訳: タスクスケジューリングのフローを調べ、深く理解して潜在的なバグを探してください。キャンセルされるべきタスクが実行されることがあるため、システムには確実にバグがあります。すべてのバグを見つけるまで調査を続け、見つけ終わったらresearch.mdに詳細なレポートを書いてください。）
キーワードの重要性
これらのプロンプトに共通する重要な単語があります。
| キーワード | 効果 |
|---|---|
"deeply" |
深い分析を要求する |
"in great details" |
詳細な調査を促す |
"intricacies" |
複雑な仕組みまで調べさせる |
"keep researching... until" |
止まらずに調査を継続させる |
Boris Tane氏は元記事でこう述べています。「これらの言葉は飾りではない。これらがなければ、Claudeはスキミングする」。
なぜ research.md に書かせるのか
口頭での報告（チャットメッセージ）ではなく、書面の成果物として記録する理由は明確だ。
- レビュー面として機能する。開発者が内容を確認し、Claudeが本当にシステムを理解しているかを検証できる。
- 誤解をこの段階で修正できる。調査が間違っていれば計画が間違い、実装も間違う。Garbage in, garbage out。誤りを最も早い段階で捕捉できるのがここだ。
- コンテキスト圧縮を乗り越えられる。セッション中にコンテキストが圧縮されても、ファイルとして残る
research.mdはいつでも参照できる。
3. Phase 2 — Planning
組み込みのPlan Modeではなく独自の plan.md を使う理由
Claude Codeには組み込みのPlan Mode（Shift+Tab）がありますが、Boris Tane氏はこれを使いません。代わりに、エディタで編集可能な独自の .md ファイルを使います。理由は明確です。
- エディタで直接編集できる。次のAnnotation Cycleの核心となる操作です。
- プロジェクトの実成果物として残る。セッションを超えて参照できます。
- コンテキスト圧縮を乗り越えられる。research.mdと同様、ファイルシステム上に存在します。
計画リクエストのプロンプト例
新機能を計画する場合。
I want to build a new feature <name and description> that extends the system to perform <business outcome>. write a detailed plan.md document outlining how to implement this. include code snippets
（日本語訳: ＜名前と説明＞という新機能を作りたいです。これはシステムを拡張して＜ビジネス上の成果＞を実現します。これを実装する方法を概説した詳細なplan.mdドキュメントを書いてください。コードスニペットも含めてください。）
既存機能の変更を計画する場合。
the list endpoint should support cursor-based pagination instead of offset. write a detailed plan.md for how to achieve this. read source files before suggesting changes, base the plan on the actual codebase
（日本語訳: listエンドポイントはオフセットの代わりにカーソルベースのページネーションをサポートする必要があります。これを実現する方法についての詳細なplan.mdを書いてください。変更を提案する前にソースファイルを読み、実際のコードベースに基づいて計画してください。）
後者のプロンプトで「read source files before suggesting changes」と明示している点に注目してください。これにより、Claudeがコードベースを読まずに一般的な実装パターンを提案することを防ぎます。
参照実装を活用するテクニック
オープンソースで良い実装を見つけた場合、そのコードを参照として共有することで劇的に良い結果が得られます。
this is how they do sortable IDs, write a plan.md explaining how we can adopt a similar approach.
（日本語訳: これが彼らのソータブルIDの実装方法です。同様のアプローチを採用する方法を説明するplan.mdを書いてください。）
ゼロから設計させるより、具体的な参照実装を渡す方が、Claudeは実際のコードの形・データ構造・エッジケースの扱い方を正確に把握した上で計画を立てられます。
4. Annotation Cycle — ワークフローの核心
概要
Boris Tane氏のワークフローで最も特徴的な部分です。plan.md にインラインノートを直接書き込み、Claudeに更新させることを1〜6回繰り返します。
このサイクルがワークフロー全体の価値の大半を担っています。ドメイン知識、製品優先順位、エンジニアリング上のトレードオフを計画に注入する唯一の場所だからです。
実際の手順
- Claudeが
plan.mdを作成する - エディタで
plan.mdを開き、問題のある箇所にインラインノートを直接追加する - 次のプロンプトをClaudeに送る
I added a few notes to the document, address all the notes and update the document accordingly. don't implement yet
（日本語訳: ドキュメントにいくつかノートを追加しました。すべてのノートに対応してドキュメントを更新してください。まだ実装しないでください。）
- 満足するまでステップ2〜3を繰り返す
- 詳細なTodoリストを要求する
add a detailed todo list to the plan, with all the phases and individual tasks necessary to complete the plan - don't implement yet
（日本語訳: 計画に詳細なTodoリストを追加してください。計画を完了するために必要なすべてのフェーズと個々のタスクを含めてください。まだ実装しないでください。）
インラインノートの具体例5パターン
| パターン | 実例 | 目的 |
|---|---|---|
| ドメイン知識の注入 | "use drizzle:generate for migrations, not raw SQL" |
Claudeが知らない制約を伝える |
| 誤った仮定の修正 | "no — this should be a PATCH, not a PUT" |
HTTPメソッドの誤りを直す |
| アプローチの却下 | "remove this section entirely, we don't need caching here" |
不要な実装を削る |
| 短い指摘 | "not optional" |
パラメータの必須性を2語で修正 |
| セクション全体のリダイレクト | "this is wrong, the visibility field needs to be on the list itself, not on individual items. when a list is public, all items are public. restructure the schema section accordingly" |
設計の根本的な修正 |
ノートの長さは2語から段落まで状況によって異なります。重要なのは、問題のある箇所に直接書き込むことです。
"don't implement yet" ガードの重要性
このフレーズを明示しなければ、Claudeは「計画が十分になった」と判断した瞬間に実装を開始します。計画が完成したかどうかを判断するのはClaude自身ではなく、開発者です。このガードを常に使うことで、判断権を手元に置き続けられます。
なぜAnnotation Cycleが有効なのか
Markdownファイルが共有可変状態として機能するからです。
チャットメッセージで「第3セクションの設計が間違っています」と説明する代わりに、問題のある第3セクションに直接ノートを書き込みます。これにより次の効果が生まれます。
- 精度が上がる。正確な箇所を指摘できるため、Claudeの理解がずれない。
- 効率が上がる。段落で説明する代わりに、問題箇所に2語で書けばよい。
- ドメイン知識を蓄積できる。「このプロジェクトではdrizzle:generateを使う」という知識が計画に残る。
元記事でBoris Tane氏はこう述べています。「3ラウンドの "added notes, update the plan" で、汎用的な実装計画を既存システムに完璧にフィットする計画へと変えられる」。
Todoリストで進捗を可視化する
Annotation Cycleの最後に詳細なTodoリストを計画に追加させます。このリストが実装フェーズ全体の進捗トラッカーになります。Claudeはタスクを完了するごとにリストを更新していくため、数時間にわたるセッションでも「今どこにいるか」を一目で把握できます。
5. Phase 3 — Implementation
標準実装プロンプト
計画が承認されたら、実装フェーズに入ります。Boris Tane氏はほぼすべての実装セッションで次のプロンプトをそのまま再利用します。
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.
（日本語訳: すべてを実装してください。タスクまたはフェーズが完了したら、計画ドキュメントに完了としてマークしてください。すべてのタスクとフェーズが完了するまで止まらないでください。不要なコメントやJSDocを追加しないでください。anyや不明な型を使用しないでください。新しい問題を導入していないことを確認するために継続的に型チェックを実行してください。）
各フレーズの意図
| フレーズ | 意図 |
|---|---|
"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で終わっています。Boris Tane氏の言葉を借りれば「実装をボーリング（退屈）にしたい。創造的な作業は計画フェーズで完了している」。
実装中のフィードバックは短く
計画段階でのノートが段落レベルなら、実装中の修正は1文で十分です。Claudeはセッション全体の文脈を持っているため、短い指摘でも意図を理解できます。
"wider"
"still cropped"
"there's a 2px gap"
"You didn't implement the `deduplicateByTitle` function."
"You built the settings page in the main app when it should be in the admin app, move it."
フロントエンドの場合は、スクリーンショットを添付することで視覚的な問題を素早く伝えられます。
また、既存コードを参照することで暗黙の要件をすべて伝えられます。
this table should look exactly like the users table, same header, same pagination, same row density.
間違った方向に進んだらリバート
段階的な修正より、リバートしてスコープを絞る方が速い結果につながります。
I reverted everything. Now all I want is to make the list view more minimal — nothing else.
悪いアプローチをパッチで修正しようとするより、gitで変更を捨ててスコープを明確に絞って再実行する方が、常によい結果を生みます。
6. Single Long Session戦略
Research・Plan・Implementを1セッションで完結させる
Boris Tane氏はResearch、Planning、Implementationを1つのセッションで完結させます。セッションの分割は情報損失を招くからです。
典型的なセッションの流れはこうです。
- フォルダの深読みから開始する
- 計画のAnnotation Cycleを3ラウンド行う
- 完全な実装を実行する
- これをすべて単一の継続的な会話で行う
「コンテキスト50%超で性能劣化する」は経験上感じない
よく言われる「コンテキストウィンドウが50%を超えると性能が落ちる」という通説を、Boris Tane氏は自身の経験上確認していません。むしろ逆で、「implement it all」と言う時点で、Claudeはセッション全体を通じて理解を積み上げています。
- 調査中にファイルを読んでいる
- Annotation Cycleでメンタルモデルを精緻化している
- ドメイン知識の修正を吸収している
調査から計画、計画への注釈を経て積み上げた理解が、コードベースに即した実装を可能にする。
コンテキスト圧縮を乗り越える plan.md
コンテキストウィンドウが満杯になると自動圧縮が実行されますが、plan.md と research.md はファイルシステム上に存在する永続的な成果物です。圧縮が発生しても完全な状態で残ります。
セッションの任意の時点で "refer to plan.md" と指示すれば、文脈を即座に取り戻せます。
7. ハンズオン例: カーソルベースのページネーションを追加する
具体的なタスクで一連の流れを確認します。「既存のAPIエンドポイントに、オフセットベースではなくカーソルベースのページネーションを追加する」というシナリオです。
Step 1: Research
まずClaudeに現在の実装を深く調査させます。
study the list endpoints in /src/api/routes/lists.ts in great details. understand how pagination currently works, the data models involved, and any ORM-specific conventions used. write a detailed research.md with everything you find.
Claudeが research.md を作成したら、自分で内容を確認します。「現在はoffsetとlimitを使っている」「ORMはDrizzleを使っている」「既存のレスポンス型はListItemだ」といった事実が正確に記載されているかを確認します。誤解があれば、この時点で修正を指示します。
Step 2: Plan
調査結果を確認してから計画を作成させます。
the /api/lists endpoint should support cursor-based pagination instead of offset pagination. write a detailed plan.md explaining how to implement this. read the source files before suggesting changes, base the plan on the actual codebase. include code snippets.
重要なのは "read the source files before suggesting changes" の指示です。これにより、一般的なカーソルページネーションのパターンではなく、このコードベースの実際の構造に基づいた計画が生まれます。
Step 3: Annotation Cycle
plan.md をエディタで開いて、インラインノートを追加します。
## Approach
We'll use a cursor based on `createdAt` timestamp + `id` for uniqueness.
[NOTE: use `id` as the primary cursor field, `createdAt` as secondary sort key. The cursor should be base64 encoded as a single string.]
## Schema Changes
Add `cursor` field to ListItem response...
[NOTE: the cursor should be optional - first page has no cursor]
## Migration
We'll use a raw SQL migration to add the index...
[NOTE: use drizzle:generate for the migration, not raw SQL. Check research.md for the convention we use.]
ノートを追加したらClaudeに更新させます。
I added a few notes to the document, address all the notes and update the document accordingly. don't implement yet
更新された plan.md を確認し、まだ修正が必要なら再度ノートを追加して繰り返します。計画が正確だと判断したら、Todoリストを追加させます。
add a detailed todo list to the plan, with all the phases and individual tasks necessary to complete the plan - don't implement yet
Step 4: 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.
実装中は、必要に応じて短い修正指示を出すだけです。計画が正確であれば、実装はほぼ機械的に進みます。
8. まとめ
ワークフローの一文要約
元記事の締めくくりをそのまま引用します。
Read deeply, write a plan, annotate the plan until it's right, then let Claude execute the whole thing without stopping, checking types along the way.
（深く読み、計画を書き、正しくなるまで計画に注釈をつけ、その後Claudeに途中で止まらずすべてを実行させ、その間中型チェックを続ける。）
魔法のプロンプトもなく、精巧なシステム指示もなく、巧妙なハックもありません。思考と実装を分離する、規律あるパイプラインがあるだけです。
始め方
いきなりすべてを導入しなくても、段階的に試せます。
- まず1つ。次のタスクをPlan Modeの代わりに
research.mdから始めてみます。 - 次に1つ。
"don't implement yet"を意識的に使い始めます。 - そして1つ。
plan.mdにインラインノートを書き込むAnnotation Cycleを1回だけ試します。
各フェーズの役割の整理
| フェーズ | 役割 | 成果物 |
|---|---|---|
| Research | コードベースを深く理解する | research.md |
| Planning | 実装計画を立てる | plan.md |
| Annotation Cycle | ドメイン知識と判断を計画に注入する | 更新された plan.md + Todoリスト |
| Implementation | 承認済み計画を機械的に実行する | コード |
このワークフローを実践することで、「計画なきAIコーディング」の混乱から抜け出し、AIを道具として制御下に置けます。
参考
- Boris Tane, "How I Use Claude Code" https://boristane.com/blog/how-i-use-claude-code/ (2026-02-10)
- Claude Code 公式ドキュメント