GitHubのエージェント機能がリポジトリ横断の文書作成を自動化

MicrosoftでAspireを開発する10人規模のチームは、GitHub Agentic Workflowsを使い、製品コードの変更からドキュメントの草案を自動生成する仕組みを構築しました。製品リポジトリと文書サイトが別々に管理される環境で、リリースとドキュメント公開の間に生じる遅れを解消する狙いです。Aspire 13.3と13.4では、82件の文書プルリクエストが製品側のマージから中央値44.8時間で公開され、いずれも機能を実装した本人がレビューしました。

従来はドキュメント担当者が数週間後に変更へ気づき、閉じたプルリクエストの差分を読み解いて執筆する「リバースエンジニアリング税」が発生していました。GitHub Agentic Workflowsは、GitHub Actionsの処理役をAIモデルが担う仕組みで、英語のプロンプトを書いたマークダウン1枚でワークフローを定義できます。エージェントは差分や関連する課題を読み、ドキュメントが必要かどうかを判断して草案を作成します。

最大の難所は、製品リポジトリと文書リポジトリをまたぐクロスリポジトリ自動化でした。広い権限を持つトークンをエージェントに渡さずに実現するため、同チームは書き込みを直接行わない設計を採用しています。エージェントは作成したいプルリクエストの内容をJSONで出力し、safe-outputsと呼ばれる別処理が、2つのリポジトリだけに権限を絞ったGitHubアプリ経由で実際の反映を担います。

生成されるプルリクエストは常にdraft（下書き）で、自動マージはしません。レビュー担当には元の機能を承認したエンジニア自身が指定され、AGENTS.mdや依存関係の定義ファイルは編集対象から除外されます。5月から6月の30日間では、396件の製品プルリクエストに対しワークフローが396回動き、そのうち82件で文書草案が作られ、すべてがマージされました。

一方で、初期版には課題もありました。当初はドキュメント化の要否判定が甘く、CIの調整やログ整理といった内部変更にも草案を作ってしまい、約13%が却下されたのです。チームはプロンプトに「ユーザー向けの変更」の定義と否定例を加えて誤検知を抑え、大きな差分がプロンプトの上限を超える問題には、事前にメタデータを抽出して渡す方法で対処しました。

同チームは、この仕組みが文書担当者を置き換えるのではなく、負担を軽くするものだと強調します。定型的な参照ページの更新をボットが引き受けることで、担当者は解説記事やサンプルなど人にしか書けない仕事に集中できるようになりました。強固なセキュリティ制約こそがシステムをより信頼でき正確なものにするというのが、同チームの得た教訓です。