Zenn
🤖

AIエージェント開発向けドキュメント整備 PM主導体制を反映（開発日記 No.062）

に公開
AI
ドキュメント
開発日記
idea

関連リンク

はじめに

昨日は Content-Converter の仕様書の詳細を詰める作業を行いました。今日は少し視点を変えて、既存の開発関連ドキュメントを見直し、AIエージェントとの協業を前提とした開発プロセスに合わせて内容を洗練させることに取り組みました。

背景と目的

これまで利用してきた開発ドキュメントは、人間が主体となって開発を進めることを前提としていました。しかし、今後はAIエージェント、特にCursorやClineのようなコーディングエージェントを活用し、私自身はプロジェクトマネージャー（PM）として指示出しやレビュー、承認に専念する開発体制を目指しています。

この新しい体制では、従来のドキュメントでは実態にそぐわない部分が出てきます。そこで、以下の4つのドキュメントを、AIエージェント開発、特に「人間PM + AI開発者」という体制に最適化する必要がありました。

  • Docs/dev-docs/project_management_guide.md
  • Docs/dev-docs/pytest_best_practices.md
  • Docs/dev-docs/quality_dashboard_guide.md
  • Docs/dev-docs/development_process_guide.md

目的は、AIエージェントが迷いなく効率的に開発を進められるよう、明確なプロセス、役割分担、そしてルールをドキュメントとして定義することです。

検討内容

まず、AIエージェントに「これら4つのドキュメントを、AIコーディングエージェントでの開発に特化させてほしい。人間中心の記述を削除し、MCPサーバーの利用ルールも検討して。技術スタックはPython, Docker, Pytest, GitHub Actionsで固定」と指示し、初期修正を依頼しました。

LLM（AIエージェント）がWebでMCP情報を検索しつつ、各ドキュメントの修正を進めてくれました。しかし、修正内容を確認する中で、単にAI向けに書き換えるだけでは不十分だと気づきました。

重要なのは、「私がPMとしてコードを書かず、テストも実行せず、指示出しとレビュー、承認を行う」という役割分担を明確にし、それを開発プロセス全体に反映させることです。そこで、LLMに追加で以下の指示を出しました。

「前提として、私はPMでコードは書かない。AIエージェントを指示・管理するのが役割。この前提で、チケット駆動開発、Human-In-The-Loop (HITL)、人間によるプルリクエスト承認の概念を組み込んで、再度ドキュメントを修正してほしい。」

この指示に基づき、以下の点を重視してドキュメントを再修正する方針を固めました。

  • 役割分担の明確化: PM（人間）とAIエージェントの責任範囲を定義。
  • チケット駆動開発: GitHub Issuesを開発の起点とし、タスク管理を行うプロセスを定義。
  • Human-In-The-Loop (HITL): TDDの指示、コードレビュー、品質チェック、最終的なPR承認など、人間の判断が必要な箇所をプロセスに明示的に組み込む。
  • 技術スタックの明記: Python, Docker, Pytest, GitHub Actions を前提とする。

実装内容

LLMに上記の検討内容を伝え、再度4つのドキュメントの修正を依頼しました。

  1. 初期修正:
    • 人間による手作業を前提とした記述を削除。
    • MCPサーバー利用に関する項目を追加（ただし、具体的なルールは「検討中」とした）。
    • 技術スタック（Python, Docker, Pytest, GitHub Actions）を明記。
  2. 再修正:
    • PMの役割: ゴール設定、GitHub Issuesによるタスク指示、進捗確認、コードレビュー、テスト結果確認、最終的なプルリクエストの承認。
    • AIエージェントの役割: 指示に基づき、コーディング、テスト作成・実行、ドキュメント修正、プルリクエスト作成。
    • 開発プロセス:
      1. PMがGitHub Issueを作成し、開発内容を指示。
      2. AIエージェントがIssueに基づき、コーディングとテスト（TDD）を実施。
      3. AIエージェントがプルリクエストを作成。
      4. PMがコードレビュー、テスト結果（Quality Dashboard含む）、動作確認を行う (HITL)。
      5. PMがプルリクエストを承認・マージ。
    • project_management_guide.md: PMとAIの役割分担、チケット駆動プロセスを明記。
    • pytest_best_practices.md: AIエージェントがテストを作成・実行する前提に修正。TDDの進め方、カバレッジ目標などを記載。PMによるテスト結果確認のプロセスを追加。
    • quality_dashboard_guide.md: AIエージェントがテスト結果をダッシュボードに反映させる手順、PMがダッシュボードを確認するタイミングなどを記載。
    • development_process_guide.md: 上記のチケット駆動、HITL、人間によるPR承認を含む一連の開発フロー全体を定義。

LLMはこれらの指示に基づき、4つのドキュメントを順次修正してくれました。

技術的なポイント

今回のドキュメント整備における技術的な（あるいはプロセス設計上の）ポイントは以下の通りです。

  • AIエージェントとの役割分担: 人間（PM）とAI（開発者）の責任範囲を明確に分けることで、スムーズな協業を目指しました。PMは戦略と品質に集中し、AIは実行に集中します。
  • Human-In-The-Loop (HITL) の組み込み: AIに任せきりにするのではなく、指示、レビュー、承認といった重要な判断ポイントで人間が必ず介在するプロセスを設計しました。これにより、品質を担保しつつAIの能力を活用します。
  • チケット駆動開発の徹底: 全ての開発作業はGitHub Issuesから始まることをルール化し、タスクの可視性とトレーサビリティを高めました。これはAIエージェントへの明確な指示伝達にも繋がります。
  • ドキュメントによるプロセス定義: AIエージェントが自律的に動くためには、拠り所となる明確なルールが必要です。今回整備したドキュメントが、そのガイドラインとしての役割を果たします。

所感

最初は既存ドキュメントの単純な書き換え作業のつもりでしたが、AIエージェントとの協業体制、特に自分がPMとしてどう関わるかを具体的に定義する良い機会になりました。「コードを書かないPM」という役割を前提にプロセスを考えると、指示の出し方、レビューの観点、承認の基準などをより明確にする必要性を感じました。

AIエージェント（今回はLLM）にドキュメント修正作業を依頼することで、思考の整理と実際のドキュメント作成を並行して効率的に進められたのは大きな利点でした。ただし、AIに指示を出す際には、前提条件や期待する役割分担を明確に伝えることが非常に重要だと改めて認識しました。最初の指示だけでは、意図した通りのドキュメントにはならなかったでしょう。

ドキュメント整備は地味な作業ですが、AIとチームを組んで開発を進める上では、コミュニケーションの基盤となる非常に重要な要素だと実感しました。MCPサーバーの利用ルールについては今回具体化できませんでしたが、今後の検討課題として認識しています。

今後の課題

  • MCPサーバー利用ルールの具体化: 今回は検討に留まったMCPサーバーの利用に関する具体的なルールやガイドラインを策定する必要があります。
  • 実運用と改善: 今回修正したドキュメントを実際のAIエージェント開発プロセスで運用し、使い勝手や改善点についてフィードバックを得て、継続的に見直していきます。
  • AIへの指示（プロンプト）標準化: AIエージェントに対して、より効率的かつ正確に指示を出すためのプロンプトテンプレートやベストプラクティスを検討・整備したいです。

まとめ

本日は、既存の開発関連ドキュメント4点を、人間PMがAI開発エージェントを主導する新しい開発体制に合わせて修正しました。チケット駆動開発、Human-In-The-Loop、人間によるプルリクエスト承認といった概念をプロセスに組み込み、PMとAIエージェントの役割分担を明確化しました。これにより、AIとの協業を円滑に進めるための基盤となるドキュメントを整備することができました。今後は、このドキュメントを実際の開発で活用し、改善を続けていきます。

GitHubで編集を提案

Discussion