Claude Codeの活用法: 計画と実行の分離

 (boristane.com)
86 ポイント 投稿者 GN⁺ 2026-02-23 | 4件のコメント | WhatsAppで共有
  • AIコーディングツールの使い方を根本的に再構成し、コードを書く前に必ず明示的な計画レビュー段階を経るワークフローを提示
  • 核心原則は**「計画が承認される前にはClaudeにコードを書かせない」**ことで、これにより構造的な統制と効率的なトークン利用を実現
  • 全体のプロセスはResearch → Plan → Annotation → Todo List → Implementation → Feedbackの循環構造で進行
  • 各段階で**Markdown文書（research.md, plan.md）**を中心に協業し、注釈と修正の過程を繰り返して完成度を高める
  • この方式はAIの実行力と人間の判断力を分離・結合し、複雑なシステムでも安定して一貫した結果を得ることに重点を置く

全体ワークフローの概要

  • 約9か月間Claude Codeを主な開発ツールとして使う中で、一般的な「プロンプト入力 → コード生成 → 修正の反復」という方式ではなく、計画と実行を分離した体系的な手順を構築
  • Claudeがコードを書く前に、必ず**作成者がレビュー・承認した計画文書（plan.md）**に基づいてのみ実行させる
  • このアプローチは不要な試行錯誤を減らし、アーキテクチャの決定権を維持し、トークン使用量に対する品質を最大化する

Phase 1: Research

  • すべての作業は深いコードベース分析から始まる
    • Claudeに特定フォルダや機能を「深く読み（detailed, intricacies）」分析するよう指示
    • 結果は必ず**research.mdファイル**に記録させる
  • この文書はClaudeの理解度を検証する**レビュー面（review surface）**として機能し、誤解があればこの段階で修正する
  • 誤ったリサーチは誤った計画と実装につながるため、最もコストの高い失敗要因を事前に遮断する
  • 例として、キャッシュ層の無視、ORMルールの未反映、重複ロジックの生成といった問題を防ぐ

Phase 2: Planning

  • リサーチをレビューした後、Claudeに**詳細な実装計画（plan.md）**を書かせる
    • 実際のコードスニペット、修正するファイルパス、トレードオフなどを含める
    • 組み込みのplanモードではなく、直接管理できるMarkdownファイルを使う
  • オープンソースの**参照実装（reference implementation）**を一緒に提供すると、Claudeの計画品質が大きく向上する
  • 計画文書そのものより重要なのは、その後の注釈（Annotation）サイクルである

Annotation Cycle

  • 作成者はplan.mdを開き、自分でインライン注釈を追加する
    • 誤った前提の修正、アプローチの却下、ドメイン知識の追加など
    • 例: 「これはPATCHであるべき」「キャッシュは不要」「visibilityフィールドはリスト単位に移動」など
  • その後Claudeに「注釈を反映して文書を更新するが、まだ実装はしないこと」と指示する
  • この注釈-更新サイクルを1〜6回繰り返し、don’t implement yetという指示で早期実行を防ぐ
  • Markdown文書は**共有可能な状態（state）**として機能し、対話型の指示よりも明確で構造的
  • 反復を通じて、一般的な計画が実際のシステムに完全に合った仕様へと進化する

Todo Listの作成

  • 実装前に、Claudeに**詳細な作業一覧（todo list）**を追加させる
    • 各段階の細かなタスクを含めて進捗を追跡
    • Claudeが完了項目に印を付けるため、長時間のセッションでも状態を把握しやすい

Phase 3: Implementation

  • すべての決定が確定した後、標準化されたプロンプトで実行を指示
    • 「すべてのタスクを完了するまで止まらないこと」「不要なコメント禁止」「any/unknown型禁止」「継続的に型チェックを実行すること」など
  • この命令は計画をそのまま実行する機械的な段階であり、創造的な判断はすでに終わっている状態
  • 計画なしですぐに実装すると誤った前提の上にコードを積み上げることになるため、don’t implement yetルールが重要な安全装置となる

Implementation中のフィードバック

  • 実行中は作成者が監督者の役割に切り替わる
    • フィードバックは短く明確に伝える: 「この関数が抜けている」「adminアプリに移動」など
    • フロントエンド修正時には「wider」「2px gap」のような短文指示やスクリーンショットを活用
  • 既存コードの参照を頻繁に使い、一貫したUI/UXを維持する
  • 誤った方向に進んだ場合はgit revertして範囲を縮小して再試行し、段階的な修正より効果的

主導権を握り続ける

  • Claudeに完全な自律権を与えず、最終決定は常に人間が下す
  • Claudeの提案の一部だけを選ぶ、または修正・削除し、技術選択を再定義する
    • 例: 「1つ目はPromise.allを使う」「4つ目と5つ目は無視」
    • 「ダウンロード機能を削除」「関数シグネチャは変更禁止」「特定ライブラリのメソッドを使う」など
  • Claudeは機械的な実行、人間は判断と優先順位の決定を担当する

Single Long Sessions

  • リサーチから実装までを1つの長いセッションで連続して実施
    • セッション中、Claudeは継続的に文脈を蓄積し、auto-compactionにより十分なコンテキストを維持
    • plan.mdはセッション全体を通して完全な形で保持され、いつでも参照可能

核心の要約

  • 「深く読み、計画を書き、注釈で磨いたあと、一気に実行せよ。」
  • 複雑なプロンプトやシステム指示がなくても、思考（Thinking）とタイピング（Typing）を分離した規律あるパイプラインで高品質を確保
  • Researchは無知な変更を防ぎ、Planは誤った変更を防ぎ、Annotationは人間の判断を注入する
  • 最終実行はすべての決定が確定した後に自動化された手順として行われ、効率的な協業構造を完成させる

関連記事

4件のコメント

 
naka98 2026-02-25

私も似たような問題をずっと経験しています。チャットベースだけでAIと協業すると、作業単位の分解（WBS）、進捗、意思決定の記録が曖昧になってしまうんですよね。
 
pcj9024 2026-02-23

計画ファイルをそのままリポジトリ内に入れておいて、その計画を実行することで生じた適用内容を保存するようにすると、コンテキストがかなり維持されるんですよね。
 
geekbini 2026-02-23

この内容はClaudeだけに限った話ではなく、汎用的にほかのCLIベースのAIサービスにも適用できそうですね。
 
GN⁺ 2026-02-23
Hacker News の意見

  • 本当の核心は「計画するかしないか」ではなく、モデルがコードとして固まる前に 前提を表に出させること
    LLM は文法よりも、アーキテクチャや制約条件のような 見えない前提 で失敗する。だから文書化された計画が、その前提をデバッグできる表面になってくれる

    • そういう意味で サブエージェント構成 は大いに役立つ。1つは計画、1つは実装、もう1つはレビューを担当させれば役割が明確になる。ブルーチーム/レッドチーム方式にもできる。結局のところ重要なのは、LLM がより明確な指示で正しく推論できるよう助けること
    • 全体の ユースケースの流れ を指針に含めると、モデルが的外れな行動をしにくくなる
    • ただし、こうして前提を表に出す行為自体がモデルの挙動を変えることもありうる。まるで printf() を1行入れたら Heisenbug が消えるようなもの
    • 文法エラーがほとんどないって？ 自分の経験は違う。小さな Rust プロジェクトで S3 バックエンドを追加しようとして、Claude が API 幻覚ループ に陥り、30分で $20 を燃やした。単純な文法の問題だったのに
    • ひょっとしてこの記事、ChatGPT で書いたんじゃない？

  • 「深く」「詳細に」といった言葉を使わないと Claude が表面的に読んでしまう、という話があるけれど、正直なぜそうなるのか 直感的に理解しにくい

    • それは attention メカニズム のため。LLM はインターネット全体を学習していて、「問題の詳細を見よ」といった表現が入った文章には、たいてい専門家レベルの回答が含まれている。だからそういう語が入ると、モデルはその種のデータにより重みを置くようになる。「MIT の教授のように振る舞え」といったプロンプトが効く理由も同じ
    • でもこういう説明は 迷信 のように思える。統計的に検証された根拠がなく、まるで太陽神に供物を捧げるレベルの 呪術的思考 に感じる。本当に効果があるなら最適化問題として証明できるはずなのに、誰もデータを公開しない
    • 今のソフトウェア開発は本当に 奇妙な時代。なぜ LLM がそう振る舞うのか誰にもわからない。私たちはただ、プロンプトが確率をうまく動かしてくれることを願うだけ。昔は決定論的だった分野なのに、今では AGENTS.md ファイルに、親が子どもに言うように太字で命令を書き込んでいる
    • こういう話を見てもなお真面目に受け取られているのが不思議。ほとんど 工学版の占星術 みたいだ
    • モデルの 潜在空間 (latent space) を地形のようなものだと考えると理解しやすい。プロンプトはボールを特定の地点に落とすことに近く、単語の選び方がそのボールがどの谷へ転がるかを決める。「深く」みたいな表現は、そのボールを望む領域に留まりやすくする。完璧な説明ではないかもしれないが、そう考えると実際にうまくいった

  • 私は3種類の文書タイプと2種類のスキルで構成された仕組みを使っている
    Specs はプロジェクトの静的な設計文書、Plans は LLM が生成した実行計画、Working memory ファイルは進行状況を追跡する。
    Gemini Pro の planner skill で新しい計画を作り、Codex の implementer skill で実行する。
    こうするとコンテキストが軽く集中しやすいため効率が高い。Codex/Gemini の $20 プランでも十分な速さで進められる

    • 私も似たようなアプローチを取っている。論文ベースで spec ファイルを作り、Claude とやり取りしながら計画を発展させる。IEEE スタイルのシステムエンジニアリング文書のように 要件–テスト–定義書 を管理している。Claude はガードレールを与えるとよく従う。Codex より Claude のほうが自分のスタイルに合っている
    • 良いアプローチだと思う。ただ、モノレポ が AI 時代により良い選択なのか気になる。うちの会社は Next.js アプリを複数のリポジトリに分けているが、1つにまとめたほうがいいのか悩んでいる

  • 計画文書に直接 コメントを残すアイデア が新鮮に感じられる。もしそのコメントを別途保存したり、あとで見直せるように管理する方法があるのか気になる

  • このアプローチにはいくつか気に入らない点がある
    第一に、一度にすべてのコードを生成する ビッグバン方式 は、理解しにくい巨大なコードの塊を作ってしまう。段階ごとに計画して実行するほうがよいと思う。
    第二に、フィードバックを与えても ナレッジベースを更新しない点 が惜しい。エラーの原因を記録して、次回は繰り返さないようにすべきだ。
    最後にテストへの言及がない。テスト駆動開発 (TDD) を少しでも含めるべき。AI 支援開発がこうした方法論とどう融合していくのか興味深い

    • 私も似た経験がある。PLAN.md を 段階ごとに分けて、各段階だけを実行するようプロンプトを慎重に書いている。テストも計画の一部に含めるが、まだ後半で追加することが多い

  • このワークフローは実は Anthropic が推奨する Claude Code の標準的なやり方。ただし欠点は、計画が完璧でなければ最初からやり直しになること
    だから私は デザイン → 計画 → 実行 を複数のバッチに分けて進めている。1,500行以下の計画単位に分けると、複雑さを管理しやすい。
    自分の 3万 LOC のアプリには 10万行の計画がある。一度に作るのは不可能だ

    • 私も同じ経験がある。だからもっと小さな計画単位に分けて、機能別ブランチ でコミットを管理している。AI のおかげで、むしろ開発習慣が良くなった
    • 正直、「根本的に違う」とされるワークフローが、ただ 基本の Plan モード を使っているだけなのは少し気まずい
    • 私も 段階的な実行 が正解だと思う。巨大プロジェクトを一度に完成させるのは、まだ 幻想 にすぎない
    • 完璧な計画でなくても構わない。AI が修正した部分だけ巻き戻して、前の段階からやり直せばいい。小さな単位の変更 で複雑さを減らすのが核心だ
    • 10万行の計画はほぼ100万語だ。読むだけで66時間かかる。現実的ではない

  • 私は plan.md の代わりに 実行可能なスキャフォールドと検証ループ を中心に作業している
    Kolibri Tickets という実際の決済システムを AI と一緒に構築した。核心は、モデルに素早くコードを書かせることではなく、検証ループを設計すること だ

    • 初期段階から動く骨組みを維持し
    • 一度に 薄い垂直スライス だけを追加し
    • テスト・型・状態マシンなど 検証可能な成果物 を強制し
    • リファクタリングを日常化する
      こうすると「速度の錯覚」ではなく、実際により速くデプロイできる。Plan 文書は共有状態を保つ1つの方法であり、検証可能なハーネス も別の方法だ
    • 私もコードが安くなった時代だからこそ 100% テストカバレッジ を目標にしている。Python で静的型付け、Playwright テスト、mutation testing まで導入中だ。今ではエージェントが1時間ループを回し、ほとんど手直し不要なコードを出してくる

  • 私は Claude Code を 講義準備用 に使っている
    Quarto で講義ノートを書き、Claude にそれを Slidev スライド に変換させる。その後、スライドに「これは2枚に分ける」「ここに画像を追加」などのコメントを書いてフィードバックする。
    こうした コメントベースのフィードバック は非常に強力だ。トークン距離や文脈維持に大きく役立つ

    • Quarto 自体でも PowerPoint、PDF、HTML などさまざまなフォーマットをサポートしているのに、なぜ Slidev を使うのか気になる。Claude に Quarto 文書を再生成させればよいのでは？
    • フィードバックは インラインコメント として残しているのか気になる。たとえば # この部分を X に変える のような形で？
    • その Claude skill をオープンソース公開 しているか知りたい

  • すでに Amazon の Kiro、Google の Antigravity、GitHub の Spec Kit、OpenSpec のようなツールが、こうした機能を提供している

  • AI 支援コーディングで最も高くつく失敗は文法エラーではなく、部分的には動くがシステム全体を壊す実装 だ
    だから私は初期段階で brief.md を追加し、問題定義、目標指標、機能中止の基準などを明記する。こうするとビジネス目標と技術実装がずれるコストを減らせる