私のClaude Codeの使い方
原文: How I Use Claude Code by Boris Tane (Cloudflare Engineering Lead) — 2026年2月10日
この記事のポイント
**書かれた計画をレビューして承認するまで、Claudeにコードを書かせない。**これがこのワークフローのすべてだ。
- リサーチを書面に残す — Claudeにコードベースを読ませた結果をresearch.mdに書き出させる。チャット上の口頭まとめではなく、レビュー可能な成果物にする。リサーチが間違っていれば、そこから先はすべて間違う。
- 計画をMarkdownファイルで管理する — Claude Code組み込みのプランモードではなく、自分の.mdファイルを使う。エディタで編集でき、インラインでメモを追加でき、プロジェクト内の成果物として残る。
- 注釈サイクルが最も価値を生む — 計画ドキュメントに直接メモを書き込み、Claudeに更新させるサイクルを1〜6回繰り返す。前提の修正、アプローチの却下、ドメイン知識の提供をここで行う。「まだ実装しないでください」のガードが不可欠。
- 実装は退屈であるべき — 注釈サイクルで創造的な作業は終わっている。「すべて実装してください」と言う時点で、すべての決定は下されている。実装は機械的な作業になる。
- 主導権は渡さない — Claudeの提案から取捨選択し、スコープを積極的に削り、既存インターフェースを保護する。判断を下すのは常に人間だ。
- Markdownが共有状態になる — チャットの会話ではなく、永続的なドキュメントが人間とAIの間のインターフェースとして機能する。自分のペースで考え、問題の正確な場所を指し示し、コンテキストを失わず再開できる。
私はClaude Codeを主要な開発ツールとして約9ヶ月間使ってきたが、最終的にたどり着いたワークフローは、大半の人がAIコーディングツールでやっていることとは根本的に異なる。ほとんどの開発者はプロンプトを打ち込み、たまにプランモードを使い、エラーを直して、繰り返す。もっとネットに浸かっている人たちは、ralphループやMCP、gas town（覚えてる？）などを組み合わせている。どちらの場合も結果はぐちゃぐちゃで、些細でないものには完全に破綻する。
これから説明するワークフローには1つの核心原則がある：書かれた計画をレビューして承認するまで、Claudeにコードを書かせない。この計画と実行の分離こそが、私がやっている中で最も重要なことだ。無駄な作業を防ぎ、アーキテクチャの決定を自分のコントロール下に置き、いきなりコードに飛びつくよりもはるかに少ないトークン使用量で格段に良い結果を生み出す。
1〜6回繰り返す
リサーチ → 計画 → 注釈 → Todoリスト → 実装 → フィードバック＆反復
フェーズ1：リサーチ
意味のあるタスクはすべて、深い読み込みの指示から始まる。何かをする前に、コードベースの関連部分を徹底的に理解するようClaudeに依頼する。そして必ず、発見した内容を永続的なMarkdownファイルに書き出させる。チャット上での口頭のまとめは絶対にダメだ。
このフォルダを深く読み込み、どう機能しているか、何をしているか、すべての特殊な仕様を深く理解してください。終わったら、学んだことと発見した内容の詳細なレポートをresearch.mdに書いてください
通知システムを徹底的に調査し、その複雑な仕組みを理解して、通知がどう動作するかについて知るべきことすべてを網羅した詳細なresearch.mdドキュメントを書いてください
タスクスケジューリングのフローを一通り追い、深く理解し、潜在的なバグを探してください。キャンセルされるべきタスクが実行されることがあるので、確実にバグがあります。すべてのバグが見つかるまでフローの調査を続け、見つけ終えるまで止まらないでください。終わったら、発見内容の詳細なレポートをresearch.mdに書いてください
言葉遣いに注目してほしい：「深く」「徹底的に」「複雑な仕組み」「一通り追って」。これは飾りではない。これらの言葉がないと、Claudeは表面的にしか読まない。ファイルを読み、関数がシグネチャレベルで何をしているか見て、次に進んでしまう。表面的な読み込みでは不十分だということを明示する必要がある。
成果物としてのresearch.mdは極めて重要だ。Claudeに宿題をさせるためではない。これは私のレビュー対象だ。読んで、Claudeが本当にシステムを理解しているか確認し、計画が始まる前に誤解を正すことができる。リサーチが間違っていれば計画も間違い、実装も間違う。ゴミを入れればゴミが出てくる。
これがAI支援コーディングにおける最もコストの高い失敗パターンであり、それは構文エラーやロジックのバグではない。単体では動くが周囲のシステムを壊す実装だ。既存のキャッシュレイヤーを無視する関数。ORMの規約を考慮しないマイグレーション。すでに別の場所にあるロジックを重複させるAPIエンドポイント。リサーチフェーズはこれらすべてを防ぐ。
フェーズ2：計画
リサーチをレビューしたら、別のMarkdownファイルに詳細な実装計画を依頼する。
<名前と説明>という新機能を構築したい。<ビジネス上の成果>を実現するためにシステムを拡張するものだ。これをどう実装するかを概説した詳細なplan.mdドキュメントを書いてください。コードスニペットも含めてください
リストのエンドポイントはオフセットではなくカーソルベースのページネーションをサポートすべきだ。これを実現するための詳細なplan.mdを書いてください。変更を提案する前にソースファイルを読み、実際のコードベースに基づいて計画を立ててください
生成される計画には常に、アプローチの詳細な説明、実際の変更を示すコードスニペット、変更されるファイルパス、考慮事項とトレードオフが含まれる。
私はClaude Code組み込みのプランモードではなく、自分の.mdプランファイルを使っている。組み込みのプランモードはダメだ。自分のMarkdownファイルなら完全にコントロールできる。エディタで編集でき、インラインでメモを追加でき、プロジェクト内の実際の成果物として永続化する。
よく使うテクニック：OSSのリポジトリで良い実装を見つけたような、十分にスコープが絞られた機能の場合、そのコードをリファレンスとして計画依頼と一緒に共有する。ソート可能なIDを追加したい場合、それをうまくやっているプロジェクトのID生成コードを貼り付けて「彼らはこうやってソート可能なIDを実装している。同様のアプローチをどう採用できるかを説明するplan.mdを書いてください」と言う。Claudeはゼロから設計するよりも、具体的な参照実装があるときに劇的に良い結果を出す。
だが、計画ドキュメント自体が面白い部分ではない。面白いのは次に起こることだ。
注釈サイクル
これが私のワークフローで最も特徴的な部分であり、私が最も価値を加える部分だ。
Claudeがplan.mdを書く → 私がエディタでレビュー → インラインでメモを追加
→ Claudeをドキュメントに戻す → Claudeが計画を更新
→ 満足？ → No: メモ追加に戻る / Yes: Todoリストを依頼
Claudeが計画を書いた後、エディタで開いてドキュメントに直接インラインでメモを追加する。これらのメモは、前提の修正、アプローチの却下、制約条件の追加、またはClaudeが持っていないドメイン知識の提供を行う。
メモの長さは大きく異なる。パラメータにClaudeが「オプション」と記載した横に「オプションじゃない」と2単語だけのこともあれば、ビジネス上の制約を説明したり期待するデータの形状を示すコードスニペットを貼り付ける1段落のこともある。
実際に追加するメモの例：
- 「マイグレーションには生SQLではなくdrizzle:generateを使う」— Claudeが知らないドメイン知識
- 「ダメ — これはPUTではなくPATCHにすべき」— 間違った前提の修正
- 「このセクションは丸ごと削除、ここにキャッシュは不要」— 提案されたアプローチの却下
- 「キューのコンシューマーがすでにリトライを処理しているので、このリトライロジックは冗長。削除して単に失敗させる」— なぜ変更すべきかの説明
- 「これは間違い。visibilityフィールドは個々のアイテムではなくリスト自体に置くべき。リストがパブリックなら全アイテムがパブリック。スキーマのセクションをそれに合わせて再構成すること」— 計画のセクション全体の方向転換
そしてClaudeをドキュメントに戻す：
ドキュメントにいくつかメモを追加した。すべてのメモに対応してドキュメントを更新してください。まだ実装しないでください
このサイクルは1〜6回繰り返す。明示的な「まだ実装しないでください」というガードは不可欠だ。これがないと、Claudeは計画が十分だと思った瞬間にコードに飛びつく。私がOKと言うまで十分ではない。
なぜこれがうまく機能するのか
Markdownファイルが私とClaudeの間の共有可変状態として機能する。自分のペースで考え、問題のある場所を正確に注釈し、コンテキストを失わずに再開できる。チャットメッセージですべてを説明しようとしているのではない。ドキュメント内の問題のある正確な場所を指し示し、そこに修正を書いているのだ。
これはチャットメッセージで実装を導こうとすることとは根本的に異なる。計画は、全体的にレビューできる構造化された完全な仕様だ。チャットの会話は、決定を再構成するためにスクロールして遡る必要があるものだ。計画が常に勝つ。
3回の「メモを追加した、計画を更新して」サイクルで、汎用的な実装計画を既存のシステムに完璧にフィットするものに変えることができる。Claudeはコードの理解、ソリューションの提案、実装の作成に優れている。しかし、私のプロダクトの優先順位、ユーザーのペインポイント、私が許容するエンジニアリング上のトレードオフは知らない。注釈サイクルは、その判断を注入する方法だ。
Todoリスト
実装が始まる前に、必ず細かいタスクの分解を依頼する：
計画に詳細なTodoリストを追加してください。計画を完遂するために必要なすべてのフェーズと個別タスクを含めてください — まだ実装しないでください
これにより、実装中の進捗トラッカーとして機能するチェックリストが作成される。Claudeは進めながら完了したアイテムにマークを付けるので、いつでも計画を一目見るだけで現在の進捗が正確にわかる。数時間に及ぶセッションで特に価値がある。
フェーズ3：実装
計画が整ったら、実装の指示を出す。これをセッション間で再利用する標準的なプロンプトとして洗練させてきた：
すべて実装してください。タスクやフェーズが完了したら、計画ドキュメントで完了マークを付けてください。すべてのタスクとフェーズが完了するまで止まらないでください。不要なコメントやJSDocは追加しないでください。anyやunknown型は使わないでください。型チェックを継続的に実行して、新しい問題を導入していないことを確認してください。
この1つのプロンプトが重要なことをすべてエンコードしている：
- 「すべて実装してください」：計画のすべてを実行し、つまみ食いしない
- 「計画ドキュメントで完了マークを付けてください」：計画が進捗の信頼できるソースである
- 「すべてのタスクとフェーズが完了するまで止まらないでください」：途中で確認のために一時停止しない
- 「不要なコメントやJSDocは追加しないでください」：コードをクリーンに保つ
- 「anyやunknown型は使わないでください」：厳格な型付けを維持する
- 「型チェックを継続的に実行してください」：問題を最後ではなく早期に検出する
実質的にすべての実装セッションでこのまったく同じ文言（わずかなバリエーション付き）を使っている。「すべて実装してください」と言う時点で、すべての決定は下され検証されている。実装は創造的ではなく機械的なものになる。これは意図的だ。実装を退屈なものにしたい。創造的な作業は注釈サイクルで行われた。計画が正しければ、実行は単純明快であるべきだ。
計画フェーズがない場合に典型的に起こることは、Claudeが早い段階で合理的だが間違った前提を立て、その上に15分かけて構築し、そして私が変更の連鎖を巻き戻さなければならなくなることだ。「まだ実装しないでください」のガードはこれを完全に排除する。
実装中のフィードバック
Claudeが計画を実行し始めると、私の役割はアーキテクトから監督者に変わる。プロンプトは劇的に短くなる。
Claudeが実装 → 私がレビュー/テスト
→ 正しい？ → No: 簡潔な修正指示 → Claudeが実装に戻る
→ Yes: まだタスクある？ → Yes: Claudeが実装に戻る / No: 完了
計画のメモが1段落かもしれないのに対し、実装の修正は多くの場合1文だ：
- 「deduplicateByTitle関数を実装していない。」
- 「設定ページをメインアプリに作ったが、管理アプリにあるべきだ。移動して。」
Claudeは計画と進行中のセッションの完全なコンテキストを持っているので、簡潔な修正で十分だ。
フロントエンドの作業が最も反復的な部分だ。ブラウザでテストして素早く修正を投げる：
- 「もっと広く」
- 「まだ切れてる」
- 「2pxの隙間がある」
視覚的な問題については、スクリーンショットを添付することもある。テーブルのズレのスクリーンショットは、言葉で説明するよりも問題を早く伝える。
既存のコードへの参照も頻繁に使う：
「このテーブルはユーザーテーブルとまったく同じ見た目にして。同じヘッダー、同じページネーション、同じ行の密度で。」
これはデザインをゼロから記述するよりもはるかに正確だ。成熟したコードベースのほとんどの機能は既存パターンのバリエーションだ。新しい設定ページは既存の設定ページのように見えるべきだ。参照を示すことで、暗黙の要件をすべて明示せずに伝えられる。Claudeは通常、修正する前に参照ファイルを読む。
方向が間違った場合、パッチを当てようとはしない。gitの変更を破棄してリバートし、スコープを絞り直す：
「全部リバートした。今やりたいのはリストビューをもっとミニマルにすることだけ — それ以外は何もしない。」
リバート後にスコープを狭めると、悪いアプローチを段階的に直そうとするよりもほぼ必ず良い結果が得られる。
主導権を握り続ける
実行をClaudeに委任していても、何を構築するかの完全な自律性は決して与えない。能動的な舵取りの大部分はplan.mdドキュメントの中で行う。
これが重要な理由は、Claudeが技術的には正しいがプロジェクトには不適切なソリューションを提案することがあるからだ。アプローチが過剰に設計されていたり、システムの他の部分が依存するパブリックAPIのシグネチャを変更したり、より簡単な選択肢で十分なのに複雑な方を選んだりする。私にはClaudeにはない、より広いシステム、プロダクトの方向性、エンジニアリング文化についてのコンテキストがある。
Claudeが変更を提案 → 私が各項目を評価
→ そのまま承認 / アプローチを修正 / スキップ・削除 / 技術的選択をオーバーライド
→ 洗練された実装スコープ
提案からの取捨選択： Claudeが複数の問題を特定した場合、1つずつ検討する：「最初のやつはPromise.allを使うだけでいい、過度に複雑にしないで。3番目は可読性のために別の関数に抽出して。4番目と5番目は無視して、複雑にする価値がない。」今何が重要かの知識に基づいて、項目レベルの判断を下している。
スコープのトリミング： 計画にあると嬉しいものが含まれている場合、積極的に削る。「ダウンロード機能は計画から削除して、今は実装したくない。」これがスコープクリープを防ぐ。
既存インターフェースの保護： 変更すべきでないものがわかっている場合、厳格な制約を設ける：「この3つの関数のシグネチャは変更してはならない。ライブラリではなく呼び出し側が適応すべき。」
技術的選択のオーバーライド： Claudeが知り得ない特定の好みがある場合がある：「あのモデルではなくこのモデルを使って」「カスタムで書くのではなく、このライブラリのビルトインメソッドを使って」。素早く、直接的なオーバーライド。
Claudeが機械的な実行を担当し、私が判断を下す。計画が大きな決定を事前にキャプチャし、実装中に浮上する小さな決定は選択的なガイダンスで対処する。
1つの長いセッション
リサーチ、計画、実装を別々のセッションに分けるのではなく、1つの長いセッションで実行する。1つのセッションがフォルダの深い読み込みから始まり、計画の注釈を3ラウンド経て、完全な実装を実行するまで、すべて1つの継続的な会話の中で行われることもある。
みんなが言っているようなコンテキストウィンドウの50%以降のパフォーマンス低下は経験していない。実際、「すべて実装してください」と言う時点で、Claudeはセッション全体を通じて理解を構築してきている：リサーチ中のファイル読み込み、注釈サイクル中のメンタルモデルの洗練、私のドメイン知識による修正の吸収。
コンテキストウィンドウがいっぱいになると、Claudeの自動圧縮が続行に十分なコンテキストを維持する。そして計画ドキュメントという永続的な成果物は、圧縮を完全な忠実度で生き残る。いつでもClaudeをそこに向けることができる。
ワークフローを一言で
深く読み、計画を書き、計画が正しくなるまで注釈を付け、そしてClaudeに途中で型チェックをしながら止まらず全体を実行させる。
それだけだ。魔法のプロンプトもなく、精巧なシステム指示もなく、巧妙なハックもない。思考とタイピングを分離する規律あるパイプラインだけだ。リサーチがClaudeの無知な変更を防ぐ。計画が間違った変更を防ぐ。注釈サイクルが私の判断を注入する。そして実装コマンドが、すべての決定が下された後に中断なしで実行させる。
このワークフローを試してみてほしい。注釈付きの計画ドキュメントなしで、どうやってコーディングエージェントで何かをリリースできていたのか不思議に思うだろう。