GitHub Agentic Workflowsによるクロスリポジトリドキュメント自動化

ソフトウェア開発において、ドキュメントの遅延は共通の課題です。分散アプリケーション向け開発ツールを構築する小規模チームAspireも例外ではありませんでした。エンジニアが機能コードをマージした後、ドキュメント作成者は変更内容をリバースエンジニアリングするのに数週間を要していました。現在、彼らはGitHub Agentic Workflowsを活用してクロスリポジトリのドキュメント自動化を実現し、このプロセスを数週間から中央値44.8時間に短縮しました。

核心的な課題はクロスリポジトリの自動化です。製品コードはmicrosoft/aspire、ドキュメントサイトはmicrosoft/aspire.devと、異なるリポジトリ、デプロイターゲット、レビューチェーンを持っています。従来の方法は広範なリポジトリスコープのトークンに依存していましたが、セキュリティチームは通常これを制限します。GitHub Agentic Workflowsは、エージェントの意図と実際の実行を分離することでこの問題を解決します。エージェントはJSON記述（意図）のみを生成し、権限が制限されたセーフアウトプットハンドラが書き込み操作を実行します。

具体的なフローは次のとおりです。ワークフローpr-docs-check.mdはmicrosoft/aspireでマージされたPRをリッスンします。まず、決定論的なBashスクリプトがPRマイルストーン（例：13.4）を使用してドキュメントリポジトリの対応するリリースブランチ（例：release/13.4）を解決します。次にエージェントがdiffを読み取り、関連するIssueをスキャンし、ドキュメントが必要かどうかを判断します。必要な場合、aspire.devワークスペースに既存の規則に従ってコンテンツを作成し、セーフアウトプットをトリガーしてPRを作成します。このPRはドラフトとしてマークされ、製品PRのレビュー担当者がドキュメントレビュアーとして設定され、ラベル[docs-from-code]が付与され、mainまたはrelease/*ブランチにのみ送信できます。

セキュリティ対策として、各ワークフローは独立したGitHub Appトークンを使用し、2つのリポジトリのみにアクセス権を付与します。エージェントはAGENTS.mdや依存関係マニフェストなどの保護ファイルを変更できません。PR作成に失敗した場合は自動的にIssueが作成されます。

30日間のウィンドウ（Aspire 13.3および13.4のリリースをカバー）では、システムは396個の製品PRを処理し、82個のドキュメントPRを生成しました。すべてがマージされ、中央値マージ時間は44.8時間、96%が7日以内にマージされました。エージェントはドキュメントが必要な変更を正確に特定し、300以上の内部リファクタリングやテスト修正を正しく除外しました。

このソリューションの成功の鍵は、マイルストーンからブランチへのマッピング、ドラフト＋開発者レビューモデル、および厳格な権限制御です。初期バージョンでは「ドキュメントが必要か」の判断が甘く、プロンプトを厳格化（反例を追加）することで誤検出率が低下しました。また、大規模なdiffはプロンプト予算を超過するため、プリプロセスで主要メタデータを抽出することで解決しました。

最終的に、ドキュメントは後付けではなく、製品完成の一部となりました。エンジニアはコードマージ後数分でドキュメントドラフトを受け取りレビューできます。ドキュメント作成者は機械的なリバースエンジニアリングから解放され、ナラティブページ、サンプルプログラム、コンセプトガイドなど、人間にしかできない作業に集中できるようになりました。セキュリティ制約により、システムはより信頼性が高く正確になりました。製品とドキュメントが別リポジトリにあるチームにとって、このパターンは再利用可能な参考事例となります。