AIによる複数リポジトリ横断設計の自律化への道

こんにちは。AmebaLIFE事業本部エンジニアのsatominです。

この記事では、ビジネス要求を起点に、要求レビューと横断設計を自律化した仕組みを紹介します。横断設計とは、フロントエンド、バックエンド、インフラなど、複数リポジトリ・複数職種にまたがる設計です。

昨今はAI活用が盛んで、単一リポジトリや単一職種単位での設計・実装・テストの自動化が各所で進んでいます。その中で、上流工程の質が出力精度に大きく影響することも明らかになってきました。しかし、要求や横断設計に本格的に取り組んでいる人は、身近にはまだいない状態でした。

要求レビューやリポジトリを横断する設計には、明確な指標がなく、担当者の知識・経験・勘に依存しがちでした。暗黙知が属人化しており、状況によって考慮の深さにばらつきが生じるため、安定した品質を継続的に出すことが難しい状態でした。

フェーズごとにも、具体的な課題がありました。

要求フェーズ – 要求精度／事前見積り

要求には未定義の項目が多く、設計段階での確認・ヒアリングが増え、要求の品質を高めるプロセス自体に多くの工数がかかっていました。例えば、成功時の期待値は書かれていても、失敗時の振る舞いや境界条件が未定義のまま設計に持ち込まれる、といった状況が続いていました。

また、要求が固まる前に見積りを求められることがあり、不確かな前提のもとで仮の設計を組み立てる必要がありました。こうした仮設計は実現可能性とのズレが大きく、見積りの精度も低下していました。

横断設計フェーズ – 全体像の把握不足

横断設計の際、関わる全員がサービスのアーキテクチャ全体を完璧に把握しているわけではありません。そのため、「実現できる」という前提で議論が進み、後工程で詳細を詰めると実現不可能であることが判明し、上流工程に戻るということが起こりました。

運用フェーズ – ドキュメントの陳腐化／属人化と再現性

開発が進むにつれてドキュメントと実装の間に差分が生じることは多く、既に運用されているシステムに改修が入った場合は、そもそもドキュメントが更新されないこともよくありました。

本取り組みは、これらの課題に向き合いながら、以下のことを目指して実施しました。

• 要求書や設計書を確実に残す文化の醸成
• レビューや設計の暗黙知を明文化し、属人化を解消して組織資産化すること
• 要求・設計の品質と再現性の確保

人間（要求者）による要求起票を起点に、AIがレビューを実施します。NGなら修正を促し、要求者が修正して再レビューのサイクルを繰り返します。AIがOKと判断したら、続けて横断設計のPull Request（PR）を作成します。人間（エンジニア）によるPRレビューを受け、AIが再設計したり、要求フェーズに差し戻して要求者に修正を促したりします。エンジニアがPRを承認すると、要求書と横断設計がセットでリポジトリ管理されます。横断設計には、影響するリポジトリごとの実装指示・実装順序・概算工数などが含まれます。

AIの呼び出しはGitHub Actionsのワークフローで実施しています（Claude Sonnetを使用）。人間の関与は、要求の起票・修正、および設計のレビュー・承認です。

なぜ人間の承認を必要としたのか

AIが自律的に生成したものであっても、問題が発生した際の責任は最終的に人間が負う必要があると考えています。そのため、生成物は一定の制約・品質基準を満たす必要があり、その判断のために人間の承認フローを設けています。

横断設計には、概算見積りの自動算出を加えました。経験値に基づくパターン別の工数対応表を用意し、職種間の並列可能な処理やバッファも含めて、現実に近い見積りとなるように調整しました。

次章以降では、このフローのポイントとなる箇所を順に説明します。

3. 要求レビューの評価ステップ

「よい要求はよい設計に通ずる」という考えのもと、要求書の品質向上、暗黙知の明文化、レビュー品質の再現性に取り組み、要求レビューの自動化を実現しました。以下がそのプロセスです。

前段1: 要求の粒度評価と分割提案

要求の規模を評価し、複数の機能が混在した大きな要求の場合は分割を提案します。粒度を細かくすることで各工程で考慮すべき対象が小さくなり、レビューと設計それぞれの出力精度が向上します。また、問題のある部分を切り分けて残りを先行して進められるため、プロジェクト全体の進行速度が上がります。

要求の内容を指定フォーマットに正規化します。起点となるGitHub Issueにはテンプレートを用意していますが、これまで要求書を書く習慣がなかった人に、いきなり全項目を記載してもらうのは負担が大きいです。使い慣れたドキュメントツールで作成した文書でも音声入力でも、テキストであれば形式を問わず自由に入力してもらうことで、要求書作成のハードルを下げることを狙っています。

レイヤー1: 一般的品質チェック

背景・課題・目的・達成条件などの必要項目が揃っているか、書かれた内容をチェックリスト形式で評価します。

「なぜ？」を繰り返し問うことで、要求の根幹にある課題や背景（Why）を引き出します。要求が手段（How）として伝えられてくることがありますが、課題を深掘りすることで、より効果的または効率的な別の解決手段を提案できる余地が生まれるためです。

レイヤー2: 開発者視点レビュー

このまま実装を始めたら判断に迷う点は何か、書かれていない事項を検知します。

ポイントは視点の切り替えです。要求者には自明でも、実装者には自明でないことがあります。「これを実装するならば、手を動かす前に何を確認しなければならないか」という立場で読み直すことで、そうした問いを引き出します。

例えば、処理の実行タイミングによって設計が大きく異なる場合があります。しかし、要求書にその記載がないことが多く、記載がなければ設計者が都度確認を取ったり推測で決めることになります。推測で決めた箇所は、後から認識のズレにつながりがちです。達成手段を設計者に任せたい場合もあると思うので、その場合はその旨を記載するよう促します。一言も言及されていない状態を作らないことが、このレイヤーの目的です。

人間がレビューを繰り返すと「きっとそういうことだろう」と内容を補完してしまいがちですが、常に要求書を初めて見た状態を再現できるAIは、レビュアーとして非常に相性が良いです。

レイヤー3: アーキテクチャ整合性チェック

現在のシステム構造で実現可能か、コードベースに固有のチェックを行います。

サービス間の通信制約、インターフェース定義、既存アーキテクチャのルールに照らし合わせて、当該サービスで実現できるかを評価します。一般的な品質基準に、現在のシステム構成への適合チェックを加えることで、設計フェーズに進んでから「この前提は成立しない」と判明する手戻りを、要求段階で防ぐことができます。

このレイヤーの土台となるのが、次章で説明するコードと同期したドキュメントです。

4. コードと同期したドキュメントの自動生成

要求レビューと横断設計の精度向上を支えるのが、この仕組みです。

AIが対象サービスに関わるリポジトリを特定し、以下の情報を抽出して統合ドキュメントとして更新します。

• サービス全体のアーキテクチャ構成、通信経路、リポジトリ依存関係
• リポジトリ間の通信制約、インターフェース定義、禁止事項
• 各システムの基本設計書、画面仕様書、機能仕様書

現在はGitHub Actionsのワークフローで定期実行しています。コードの変更にドキュメントが追従するため、常に最新の情報を保つことができます。

要求レビューのレイヤー3は、このドキュメントを根拠として「今のシステムで実現できるか」を評価します。また、横断設計もこのドキュメントを参照することで、現在のシステム構造に根ざした設計を生成します。

ドキュメントが存在しない場合でも、アーキテクチャ整合性チェックをスキップして一般的なレビューと設計として動作するため、この仕組み自体は他のサービスへもそのまま流用できます。

5. プロンプト構築プロセスの反復サイクル

仕組み化における具体的な作業のサイクルです。

実際の案件の要求書を用いました。まずは従来通り人間がレビューします。そこで出た指摘を「なぜこれを指摘したか」という観点で一般化し、要求レビューのプロンプトに組み込んで実行します。自分の気付きと同じ内容が出力されるまで、この調整を繰り返しました。要求者にも協力いただき、実際のフローを試してもらい、フィードバックをもとに修正を重ねました。

例えば、「0件のときの表示が書かれていない」「エラー時の振る舞いが未定義」という指摘は、「正常系は書かれているが境界値・異常系の振る舞いが未定義」というパターンに一般化します。これが要求レビューにおけるレイヤー2の検知ルールになります。

横断設計においては、AIに仮実行させ、不足情報や的外れな設計が出力された場合は、横断設計のプロンプトを修正し、場合によっては要求レビューのプロンプトに戻るサイクルを繰り返しました。人間がこれまで行ってきた要求レビューと横断設計のフローに、プロンプト調整サイクルを追加した形です。これは、個人の暗黙知をパターン化し、システムに転写していく作業でもありました。

この仕組みを実現したことで、複数の変化が生まれました。

要求書の初期レビューをAIに完全移譲できた

初期レビューが要求者とAIの間で完結するようになったため、エッジケースや境界値・異常系の網羅性が高まり、要求書初稿の品質が向上しました。その結果、エンジニアがレビューに要する時間が減り、最初からより込み入った観点でレビューに臨めるようになりました。

要求書作成スキルをAIと共に伸ばせる仕組みができた

一定品質のAIフィードバックを繰り返し受けることで、要求者が考慮すべき観点を能動的に深められるようになりました。

設計草案の作成効率が向上し、レビューがポジティブになった

ゼロから設計草案を書き起こす作業時間が短縮され、方針が変わった場合の再作成も容易になりました。また、レビューにおいて指摘の対象がAIの自動生成物になるため、フラットに「違うよ」と指摘できるなど、レビュアー間の議論がより建設的になりました。

設計作業前に概算工数を把握できるようになった

横断設計がこれまでの仮設計に相当するため、開発規模を事前に把握しやすくなりました。

レビュー品質が安定し、再現性が生まれた

レビュー観点がプロンプトに転写・蓄積されることで、属人化の解消と品質の安定化が実現できました。

決定の経緯まで遡れるようになった

要求・設計レビューの過程が記録として残るため、第三者が後から背景や判断理由といった経緯を把握できるようになりました。

ドキュメントが常に最新の状態を保てるようになった

コードの変更に自動追従するため、実装との乖離が生まれなくなり、長年の課題だったドキュメントの陳腐化が解消されました。また、ドキュメントとして概要が整備されたことで、専門分野以外も含めたサービス全体像の把握がしやすくなりました。

具体実装を含めた全工程の自動化への道筋

単一リポジトリではすでに、詳細設計・実装・テスト・PRレビューの自動化が進んでいます。横断設計によるリポジトリ別の指示を適切に伝達できれば、全工程の自動化が現実的になります。エンジニアの役割は「要求・横断設計の承認」と「各リポジトリのPR承認」に絞り込まれていくでしょう。

AIによる出力内容はまだまだチューニングの余地があります。今回は著者一人のノウハウを詰め込みましたが、他のメンバーの知見や今後の実案件での経験値を取り込むことで、その精度をさらに高められると考えています。

現在はGitHubでの入力が前提なので、SlackやNotionなどを入口として、他職種のメンバーが参加しやすい形への拡張も進めていきたいと考えています。また、他サービスへの導入も併せて進めていければと思っています。

他にも、まだ構想段階ですが取り組んでみたいことがあります。

ひとつは、会議の自動文字起こしを要求の発足起点にすることです。「誰かが話したことを、本人すら覚えていないまま案件化する」という、これまでにない要件定義の入口が生まれるかもしれません。

もうひとつは、蓄積したアーキテクチャデータの活用です。非技術者からの問いかけに対して、集約ドキュメントから仕様を答えてくれる仕組みを実現してみたいと思っています。さらに、複数サービスへの展開が進みデータが蓄積されれば、新規サービス立ち上げ時に、サービス特性に応じたアーキテクチャ構成を提案できるようになるかもしれません。

この仕組みを起点に、次々と活用のアイデアが湧いてきており、拡大の可能性を感じています。

横断設計を自律化したいという想いから始まりましたが、満足できる出力を実現するには、要求レビューとドキュメント生成の自律化にも取り組むことになりました。

全体フローとしては一通り作り切ることができました。しかし、現時点では「初期」レビューや横断設計の「草案」であり、そのまま無条件に採用できる品質ではありません。それでも、この仕組みが動き始めただけで、既に大きな恩恵がありました。

もしこの記事が、同じ領域や課題に向き合っている方の参考になれば幸いです。