AI駆動開発の仕様書・テストリソースを自動更新するワークフロー

仕様書のメンテナンスがAI駆動開発の課題になっている

AI駆動開発において開発スピードの向上は日々加速しています。一方で、機能仕様書やテスト仕様書のメンテナンスが追いつかないという課題が浮き彫りになっています。

なぜ仕様書のメンテナンスが難しいのでしょうか。AIエージェントによる実行計画（Plan）は開発タスクの遂行に最適化された記述になるため、そのままプロダクトの仕様書のマスタとして扱うには適していません。

ではPlan実行時に仕様書のマスタへ直接仕様を書き込むのはどうでしょうか。仕様を明確化して全体共有を図りながら実装できるメリットはありますが、AIエージェントの視点では開発スコープが曖昧になり、開発効率や品質の低下を招くリスクがあります。また、他のメンバーによる仕様書の変更と競合するリスクも見過ごせません。

AI駆動開発や仕様駆動開発を取り入れたいのに、仕様書の置き場に困るという状況はなるべく早い段階で解消しておきたい課題です。NotebookLMのようなドキュメントAI要約サービスを併用する手もありますが、新しい仕様を追加しながら古い情報を取り除くというメンテナンスは、想像以上に手間がかかります。

KATATANが提供するAI駆動開発エコシステム

そこでKATATANが独自に採用しているAI駆動開発環境向けのエコシステムをご紹介します。KATATANとGithubを組み合わせることで、驚くほどシンプルかつ強力に生産性を向上させる仕組みを構築できます。

このワークフローは開発環境のセマンティクスを維持しながら、仕様書とテスト環境を自動的に最新の状態に保ち続けます。必要なものはAIエージェントが使えるモダンなIDEと、GithubとKATATANだけです。

ワークフローの動作の流れ

Step 1. Read issues & specs from Github for planning implementation

AIエージェントにタスクの要件を伝えてPlanを実行しましょう。AIエージェントが実装仕様を含むタスク計画書を作成します。このタスク計画書は実装に最適化された内容のため、そのままプロダクトの仕様書には使えませんが、実装品質を向上させるうえで欠かせないリソースです。

Step 2. Push & create PR

実装と動作確認が終わったら、Githubにコミットをプッシュしてプルリクエストを作成します。ここで重要なポイントがあります。プルリクエストの内容は、仕様書更新のためのハンドオーバー資料として機能します。 実装した機能の仕組みや仕様が明確にわかるように記述することが大切です。

Step 3. Review & merge PR

チームのレビューが通ればプルリクエストをマージします。ただし、マージの前にひとつ準備が必要です。

GithubにはPRマージなどのイベントをフックしてCopilot Cloud Agentを起動するCloud Automationという仕組みがあります。このイベントフックを事前にGithubに設定しておきます。設定が必要なイベントフックは2つだけです。

• PR作成イベント：テスト仕様書を更新するAutomation
• PRマージイベント：機能仕様書・設計書を更新するAutomation

それぞれの詳細は以降のステップで説明します。

Step 4. Trigger PR create with agent automation

PR作成イベントを受けて動作するGithub Cloud Automationです。Cloud AgentにはMCPを設定できますので、KATATAN MCPの設定をCloud AgentのMCP設定に追加してください。

KATATANのMCPアクセストークンはGithub Secretsに保管し、Agent MCP設定からSecretsを参照できます。Secretsの命名にはCOPILOT_MCP_から始まる接頭辞が必要です。詳細はGithubの公式ドキュメントをご確認ください。

なお、KATATANのMCPアクセストークンは個人アカウントに紐付かず、プロジェクトの所有物として管理されます。開発者の異動や退職の影響を受けない点は、チーム運用において大きなメリットです。

Step 5. Update test specs & test code then run E2E test with KATATAN

Copilot Cloud AgentがAutomationのプロンプト指示に従ってE2Eテストを更新します。またAutomation内でPlaywrightを動かすこともできるため、テストの実行から結果の記録までをそのまま自動化できます。

Step 6. Trigger PR merge with agent automation

プルリクエストをマージすると、今度は仕様書の更新を担うCloud Agentが起動します。AutomationのプロンプトにGithub Wikiを更新する指示を記述しておきましょう。

Github WikiはページがMarkdown形式で表現されており、ローカルにクローンすることもできます。AIエージェントとの相性が非常によく、強力なナレッジベースとして機能します。Wikiをうまく運用するコツは、機能ごとにページを分けて管理することです。タイトルに機能名を付けておくとAIエージェントによる検索性が向上し、トークンやコンテキストキャッシュの節約にもなります。

Step 7. Update functional specs and design specs on Github

Github Wikiの内容がアップデートされます。不足しているページは新規作成され、古い情報は新しい内容に更新されます。WikiにもPull requestの仕組みが有効なため、更新差分やコンフリクトの確認も明快です。

Wikiの更新が完了したら、チームメンバーにpullしてもらいましょう。各自のローカル環境に最新のナレッジが同期され、AIエージェントにとって快適な開発環境が維持されます。

---

これでワークフローが1巡しました。新たなタスクに取り掛かる際は、Step 1からStep 7のイテレーションをこなすだけで、機能・仕様・テストケースの同期を保つことができます。

おわりに

今回の記事が皆さんの役に立てば幸いです。ワークフローの構築でお困りのことがあれば、ぜひKATATANまでご相談ください。この記事を参考にワークフローを導入された際の感想やフィードバックもお待ちしております。

連絡先： contact@katatan.com