Anthropic Claude Codeの実践ワークフロー：Markdownを軸とした開発サイクル

Anthropicが提供する開発支援ツール「Claude Code」は、単なるコード補完を超え、プロジェクトの初期設計から実装までを構造化する新しい開発体験を提供する。その公式ドキュメントで推奨される、調査→計画→修正の繰り返しをMarkdownファイルを軸に行うワークフローは、特にプロジェクトの見通しを立てる段階で威力を発揮する。一方で、小さなスクリプト作成など即時的なコーディング支援のみを求める開発者には、過剰な仕組みに感じられる可能性もある。

Claude Codeとは：プロジェクト全体を俯瞰する開発パートナー

Claude Codeは、AnthropicのAIモデルClaudeを開発作業に特化させたツールだ。公式ドキュメントによれば、ローカル環境やWeb上で動作し、プロジェクト全体のコードベースを分析し、計画立案、コード編集、さらにはTODOリストの生成までを支援する。従来のAIコーディングアシスタントが主にエディタ内でのコード補完や生成に焦点を当てていたのに対し、Claude Codeの特徴は、開発の「上流工程」を含むより広範なライフサイクルをサポートする点にある。プロジェクトの構造を理解し、開発方針を文書化し、タスクを分解する――こうした作業をAIと対話しながら進められるのが最大の利点と言える。

公式推奨のコアワークフロー：調査・計画・修正の繰り返し

Claude Codeの効果的な使い方の核心は、公式ドキュメントで示されている特定のサイクルにある。これは、単発のコード生成を繰り返すのではなく、プロジェクトに対する理解を段階的に深め、計画を洗練させていくプロセスだ。

ステップ1: 調査と初期ドキュメント作成

まず、Claude Codeにプロジェクトのコードベース全体を読み込ませ、分析（調査）を依頼する。この段階では、プロジェクトが何をしているのか、どのような技術スタックを使っているのかをClaudeに理解させる。次に、この調査結果を基に、プロジェクトの概要を記した最初のMarkdownファイル（例えばPROJECT_OVERVIEW.md）を作成させる。これがプロジェクトに関する共通認識の土台となる。

ステップ2: 計画の立案とMarkdown化

調査結果を踏まえ、次に行うべき開発タスクや機能追加について計画を立てさせる。この計画もまた、IMPLEMENTATION_PLAN.mdのようなMarkdownファイルとして出力する。計画には、実装すべき機能、変更が必要なファイル、考慮すべき依存関係などが含まれる。ここで重要なのは、計画を単なる箇条書きではなく、構造化された文書として残すことだ。

ステップ3: 計画のレビューとドキュメント修正の繰り返し

作成された計画ファイルを開発者自身が読み、不足点や誤り、優先順位の変更などを発見する。そして、そのフィードバックをClaudeに伝え、計画のMarkdownファイルを修正させる。この「計画を読み、修正を指示し、更新された文書を読み込む」というサイクルを、計画に満足がいくまで繰り返す。この反復プロセスにより、AIの提案を単に受け入れるのではなく、開発者の意図と深くすり合わせた、現実的な計画が仕上がっていく。

ステップ4: TODOリストの作成と実装

最終的な計画が固まったら、Claude Codeにその計画を実行可能なタスクに分解させ、TODO.mdなどの形式でTODOリストを生成させる。このリストは、具体的なファイル名や関数名を含む、アクション指向の項目になる。その後、このTODOリストを参照しながら、個々のタスクについてClaude Codeにコードの実装や修正を依頼していく。計画段階で詳細まで詰めているため、実装フェーズではより正確でコンテキストに即したコード生成が期待できる。

具体的な活用例：機能追加プロジェクトでの実践

例えば、既存のWebアプリケーションに新たなユーザー設定ページを追加するプロジェクトを想定してみよう。まず、Claude Codeに現在のコードベース（フロントエンド、バックエンド、データベーススキーマ等）をすべて読み込ませる。「このプロジェクトに設定ページを追加するための調査をして、SETUP_ANALYSIS.mdを作成して」と指示する。次に、その分析を基に「設定ページ追加の実装計画をSETTINGS_PLAN.mdにまとめて」と依頼する。生成された計画を見ると、バックエンドAPIの追加が必要と書かれているが、実際には既存APIを拡張すれば済むことに気付く。そこで「計画の3節を、既存のUserAPIを拡張する方式に修正して」と指示し、文書を更新させる。このやり取りを数回繰り返し、フロントエンドコンポーネントの構成からDBマイグレーションの内容まで詳細が固まってから、TODOリストを生成し、実装に移る。このように、AIを単なるコーディングマシンではなく、設計の議論相手として活用できる。

従来ツールとの比較：なぜこのワークフローが有効なのか

GitHub Copilotなどのツールは、現在編集中のファイルや隣接するコードのコンテキストから優れた補完を提供するが、プロジェクト全体のアーキテクチャや長期的な計画について深く議論するのは不得手だ。Claude Codeのアプローチは、プロジェクトを「物語」としてAIに理解させ、その上で開発者と共同で「続きのあらすじ（計画）」を練り上げることに似ている。Markdownファイルという形で中間成果物が残るため、思考の過程が可視化され、チームメンバーとの共有も容易になる。また、計画を何度も修正するプロセスは、開発者自身の思考整理にも役立つ。自分が何を実現したいのか、そのためには何が必要なのかを、AIとの対話を通じて明確にしていくことができる。

まとめ：誰がこのワークフローを試すべきか

Claude Codeのこの調査→計画→修正のワークフローは、中規模以上の新規プロジェクトの立ち上げや、既存の複雑なコードベースへの機能追加を担当する開発者に特に有効だ。プロジェクトの全体像を把握し、構造化された計画を立てることに時間を割く価値がある場面で真価を発揮する。逆に、些細なバグ修正や単純なユーティリティ作成だけを行う場合には、通常のコーディングアシスタントで十分かもしれない。AIを開発の「戦略パートナー」として活用し、コードを書く前の「考える」段階を強化したい実践的な開発者にとって、Claude Codeは新しい選択肢を提供するツールと言える。