🙆

大きめなタスクをAIにコーディングしてもらうときはフェーズに分けてドキュメント駆動で進めると良さげな件

に公開
AI
Claude
Claude Code
idea

はじめに

個人でClaudeCodeを使って開発しています。普段はサーバーサイドのエンジニアをしています。

コーディングエージェントで個人開発をする際は基本的にドキュメント駆動ベースで開発を進めているんですが、大きめのタスクを投げると、どうしても破綻してしまうケースがあって、どうしようかといろいろ試行錯誤していました。

いろいろ試した結果、フェーズ分割で進めるスタイルが今のところ良い感じで便利だなと思っているので、まとめてみました。

使っているツール

以下のツールを使っています。

  • ClaudeCode
  • メモリMCP - 登録済みのプロンプトを検索できるMCP

こんな人の参考になるかも

コーディングエージェントを使っていて、以下のような経験がある方は、参考になるかも。

  • 大きなタスクを投げると途中で崩壊しがち
  • コンテキスト圧迫のときのAIエージェントのコンテキスト引き継ぎがうまくいかない

フェーズ分割開発をする前の問題点

フェーズ分割を取り入れるまでは、ClaudeCodeに対して、以下のようなドキュメントを作ってもらいながら開発を進めていました。

よくあるドキュメント駆動開発だと思います。

goal.md - プロジェクトの目的
require.md - ユーザー要求（ざっくりやりたいことなど）
requirement.md - 機能要件
analyze.md - 既存コード分析（主に既存コードの調査）
research.md - 技術調査（主にオンラインでの調査）
design.md - 設計
tasks.md - タスク一覧

この進め方も悪くなかったんですが、タスクが大きくなるのに比例して全部が肥大化してしまい、以下のような問題にはまるケースがありました。

  • tasks.mdの内容が多くなりすぎて管理しづらい
  • 一つのドキュメントに詰め込みすぎて、それぞれの分析や調査が浅くなる
  • 長いタスクの途中でAIが混乱したり、想定と違う実装になったり、エラーにハマると解決できなくなる
  • コンテキストが溢れそうになって別のエージェントに切り替えるとき、引き継ぐ情報が多すぎる

これをどうにかして解決できないかなと、試行錯誤していました。

フェーズ分割開発とそのやり方

いろいろ試していたんですが、そのうちの一つ

一つのタスクをさらにフェーズに分けて分割して、その中で同じように全てのドキュメントを生成して進める形式

を試したところ、タスクの完遂度や正確性が上がった感じがして、今の主流の開発フローになっています。これを勝手にフェーズ開発と読んで使っています。

やり方

フェーズ分割開発は、やっていることはシンプルで、ドキュメント駆動開発の拡張です。

  • 一つのタスクを投げる
  • タスクの内容を相談して目的などを整理
  • 整備した内容を元に全体を大まかに調査
  • 調査結果に基づいて独立した複数のフェーズに分割

あとは、それぞれを独立した一つのタスクとして扱って、同じようにドキュメントベースで進めるだけです。

具体的なフロー

  1. 最初のタスクまたはプロジェクトを投げる
  2. 投げた内容をベースに相談しながら以下ドキュメントを生成
- require.md
- requirement.md
- analyze.md
- research.md
- phases.md
  1. phases.mdでタスクを分割したら、それぞれのフェーズごとに同じようにドキュメント駆動で進める

上記フローで進めた場合の、実際のディレクトリ構造は以下のような感じになります。

docs/project-name/
├── goal.md
├── require.md
├── requirement.md
├── analyze.md
├── research.md
├── phases.md
└── phases/
    ├── phase-01-setup/
    │   ├── requirement.md       # phase-01の詳細要件
    │   ├── analyze.md           # phase-01に関連する分析
    │   ├── research.md          # phase-01固有の調査
    │   ├── design.md            # phase-01の設計
    │   └── tasks.md             # phase-01のタスク一覧
    ├── phase-02-implement-core/
    │   ├── requirement.md
    │   ├── analyze.md
    │   ├── ...
    └── phase-03-testing/
        └── ...

フェーズ分割開発のポイント

このフェーズ分割開発では、以下の2つのポイントがあると思っています。

  • 各フェーズごとに独立したタスクとしてドキュメント駆動で進めること
  • フェーズごとに段階的に進めること

各フェーズごとに独立したタスクとしてドキュメント駆動で進めること

フェーズごとに、ドキュメント駆動で以下のドキュメントを作成しながら進めています。

  • requirement.md - そのフェーズの詳細要件
  • analyze.md - そのフェーズに関連する既存コード分析
  • research.md - そのフェーズ固有の技術調査
  • design.md - そのフェーズの設計
  • tasks.md - そのフェーズのタスク一覧

こうすることで、スコープを絞った状態でのコンテキスト収集になるので、それぞれのフェーズで密度の濃いコンテキストを集めることができます。

フェーズごとに段階的に進めること

手戻りや差し込みが発生する想定なので、一度にすべてのphaseのドキュメントをあらかじめ作成するのではなく、一つphaseを完了させてから、次のphaseディレクトリを作成し、進めるようにしています。

一度にやると、あとでの調整が大変になったり無駄になったりしますが、段階的に進めることで、無駄な作業が減り、かつドキュメントの不整合も減らせます。

プロンプトとしてフェーズ分割開発フローを定義して使い回す

フェーズ分割開発のフローはこれだけですが、毎回使いまわすためにフェーズ開発のプロンプトを作成して、使いまわしています。

私はメモリMCPを使っているので、フローを整理したプロンプトをメモリMCPにproject_workflowという名前でプロンプトとして登録し、

〇〇をしたいです。project_workflowで進めてください。

のように伝えて、MCPからプロンプトを読み出してもらい、あとは対話しながらフローに従って進めていってます。

メモリMCPのようなツールを使っていなくても、スラッシュコマンドでこのフェーズ分割開発のプロンプトを作成して使うと、おそらく同じように使えると思います。

とりあえず動くのであまり整備できてない&長いので要約していますが、AIに要約してもらった参考プロンプトを置いておきます。

プロンプト

全体の流れ

ステップ1: プロジェクト初期化

  • 複雑性を判定（簡単 or 複雑）
  • docs/<project_name>/ ディレクトリを作成

ステップ2: 要求定義

  • goal.md - 目的・成功の定義
  • require.md - ユーザー要求・制約条件
  • requirement.md - 機能要件・受け入れ基準

ステップ3: 事前調査【必須】

  • analyze.md - 既存コードベースの分析
  • research.md - オンライン調査（公式ドキュメント、ベストプラクティス等）

ステップ4: 実行計画

  • phases.md - プロジェクトを検証可能な単位に分割
    • Phase命名規約に従う（例: phase-01-setup-database）
    • 各Phaseで前提条件・完了条件を定義
    • 「単独で動作確認できる」単位に分割

ステップ5: Phase実行ループ

各Phaseで以下のサイクルを実施：

📋 Plan: Phase文書作成

各Phaseの phases/phase-XX-<name>/ 配下に以下5つを作成：

  • requirement.md - 機能詳細、完了確認方法
  • analyze.md - 既存コード分析
  • research.md - 技術調査
  • design.md - 設計
  • tasks.md - 段階的なタスクリスト

🔨 Do: タスク実行

各タスクを以下のサイクルで実行：

  1. tasks.mdから次のタスクを確認
  2. 立ち止まって考える（前提条件、テスト方法）
  3. タスク実行（TDDまたは通常開発）
  4. テスト実行
  5. 動作確認【必須】
  6. tasks.mdチェック更新【必須】
  7. コミット

🚦 Check: Phase完了判定

  • Gate 1: 自動テスト確認（全テストパス、リグレッション確認）
  • Gate 2: 手動検証（requirement.mdの完了確認方法を実行）
  • Gate 3: 人間承認（Phase 1や重要な変更の場合）

✅ Act: 次へ

  • tasks.md完全チェック確認
  • ドキュメント更新
  • 次のPhaseへ

ステップ6: プロジェクト完了

  • 全Phase完了後の最終確認
  • ドキュメント整合性チェック
  • プロジェクト完了報告

計画の見直し

状況に応じて適切なレベルで調整：

  • Taskレベル: tasks.md編集
  • Phaseレベル: phases.md調整
  • Requirementレベル: requirement.md見直し
  • Requireレベル: require.md・goal.md再定義

フェーズ分割開発のメリット

最近は、こんな感じでフェーズ分割開発で個人開発をしているんですが、以下のようなメリットがあると思っています。

  • 密度の高いコンテキストで進められる
  • 別のエージェントに引き継ぎやすい
  • 手戻り・差し込みしやすい

密度の高いコンテキストで進められる

冒頭でも書いたように、一つのフラットなタスクとして扱うと、どうしても一つ一つのドキュメントが大きくなりがちでした。大きめのタスクだと特に。

なので、レビューする自分も辛いし、AIも混乱しがちでした。

フェーズごとにプロジェクト化することで、スコープが小さくなるため、それぞれのドキュメントのボリュームは小さくなりつつも、スコープを絞っているので、密度の高い内容を作れている感覚があります。

フェーズごとにドキュメントを作成するための手間とコンテキストは増えますが、それぞれ小さくしたタスクごとに絞ったスコープで詳細に進められるので、濃いコンテキストを集めながら進めることができます。

結果として、長めのタスクでも完遂率や実装完遂度が上がっている印象です。

次のエージェントに引き継ぎやすい

フェーズごとに分ける前は、全体が大きくなりすぎて、エージェントに引き継ぐ情報が多く、理解してもらう内容も複雑になってしまいました。

フェーズごとにプロジェクト化することで、該当のフェーズを渡すだけでざっくり理解して進めてくれるので、便利です。

フェーズ分割開発はドキュメントが多くなるので、きりのいいタイミングでこまめに新しくエージェントを起動して、コンテキストを綺麗にしながら進めています（/clearや/compactなどでもいいかも）。

ちなみに、osascriptで新しいiTermを起動してコンテキストを渡す引き継ぎスクリプトをメモリMCPに登録しているので、新しいコンテキストを切り替える場合は、osascriptおすすめです。

手戻り・差し込みしやすい

それぞれのフェーズが比較的小さな単位のプロジェクトになっているので、途中の差し込みやロールバックも、調整してもらいやすくなっています。

結果として、破綻せずに修正しなが進められています。

ただ、うまくいかない場合は大元のドキュメント以外はまっさらにしてやり直すこともしばしば。

まとめ

個人的には、できるだけ分割してスコープを減らすことで、より良いコンテキストが集められて、AIが良い情報を持って進められると思っています。

手間がかかるのと、ドキュメントが増えることでコンテキスト消費は増えるかもしれませんが、その分の価値は十分にあるかなと。

まだまだ改善の余地はありますが、参考になれば嬉しいです！

Discussion