🧭
AI エージェント向け AGENTS.md を自動更新する仕組み — monorepo 対応 & Issue 自動生成
解決したい課題：コンテキストの鮮度問題
AI コーディングエージェント（GitHub Copilot、Claude）を使っていると、AGENTS.md ファイルが実際のコードベースと乖離していくという問題に直面します。
よくある問題
- 新しい機能を追加したのに、AGENTS.md には書かれていない
- 削除した機能が AGENTS.md に残っている
- monorepo で複数サービスの AGENTS.md を個別に管理するのが辛い
- 手動で同期するのを忘れ、AI の出力精度が徐々に劣化していく
この記事で提案する解決策
- 統一されたドキュメント形式: 各サービスに
AGENTS.mdを配置し、AI エージェント向けの情報を一元管理 - 自動同期の仕組み: GitHub Actions で週次 Issue を自動生成し、変更を検知
- AI による自動更新: Copilot をアサインすることで、AGENTS.md を自動更新
- monorepo 対応: 複数サービスの AGENTS.md を並列で管理
結果: コードの変更が自動的に AGENTS.md に反映され、AI エージェントの精度が維持される仕組みが完成します。
実運用例: 複数のプロジェクトを含む monorepo で、このフローにより毎週サービス固有の AGENTS.md を見直し、Copilot/Claude の精度を安定させています。
アーキテクチャの全体像
┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions (週次実行) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. コードベースの変更を検知 │ │
│ │ 2. プロジェクトごとに Issue を自動生成 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ GitHub Issue (自動生成) │
│ ・前回更新以降の変更履歴 │
│ ・プロジェクト構成のサマリ │
│ ・更新すべき AGENTS.md ファイルのリスト │
└─────────────────────────────────────────────────────────────┘
↓
【手動で Copilot をアサイン】
↓
┌─────────────────────────────────────────────────────────────┐
│ GitHub Copilot (自動実行) │
│ ・Issue の内容を読み取る │
│ ・コードベースの変更を分析 │
│ ・AGENTS.md ファイルを自動更新 │
│ ・PR を自動作成 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 各サービスの AGENTS.md │
│ services/*/AGENTS.md │
│ + ルートの AGENTS.md (書き方ガイド) │
└─────────────────────────────────────────────────────────────┘
↓
【Copilot と Claude が参照】
↓
┌─────────────────────────────────────────────────────────────┐
│ AI エージェントがコンテキストとして利用 │
│ ・GitHub Copilot: 自動的に参照 │
│ ・Claude: Projects 機能で明示的に追加 │
└─────────────────────────────────────────────────────────────┘重要な設計原則
- サービスごとの AGENTS.md: 各サービスディレクトリに配置し、サービス固有の情報を管理
- 自動検知: GitHub Actions がコードの変更を定期的に検知
- AI による更新: Copilot が自動的に AGENTS.md を最新化
- 統一された形式: ルートの AGENTS.md が書き方ガイドとして機能
なぜこの仕組みが必要か
従来の問題点
手動更新の限界
- 機能追加のたびに AGENTS.md を手動更新 → 忘れる
- 複数サービスで AGENTS.md が散在 → 管理コストが高い
- 各サービスで形式がバラバラ → 一貫性がない
コンテキストの劣化
- 古い情報を元に AI が不正確なコードを生成
- 削除済みの機能を AI が提案してしまう
- 新しいパターンを AI が知らない
自動同期による解決
定期的な同期
- 週次で自動的に変更を検知
- Issue として可視化され、見逃さない
- AI が自動更新するため、手間がかからない
統一された形式
- ルートの AGENTS.md が書き方ガイドとして機能
- 各サービスの AGENTS.md は同じ構造に従う
- 必須セクションが明確に定義されている
スケールする仕組み
- monorepo で複数サービスを並列処理
- サービス追加時も matrix に追加するだけ
- AGENTS.md の一貫性を保ちながら拡張可能
AI エージェントとの連携パターン
GitHub Copilot
各サービスの AGENTS.md を自動的に参照し、コンテキストとして活用します。
Claude Desktop
Claude Projects 機能を使用して、必要な AGENTS.md ファイルをプロジェクトに追加：
Project Knowledge:
- AGENTS.md (ルート: 書き方ガイド)
- services/service-a/AGENTS.md
- services/service-b/AGENTS.md
- services/service-c/AGENTS.mdこれにより、AGENTS.md が更新されれば、両方の AI エージェントが自動的に最新の情報を参照できます。
実装：自動同期の仕組み
コア機能
この自動同期の仕組みは、3つのコア機能で構成されています：
- 変更検知: Git のコミット履歴から、前回更新以降の変更を自動抽出
- Issue 自動生成: 変更内容とプロジェクト構成を含む Issue を作成
- AI による更新: Copilot が Issue を読み取り、AGENTS.md を自動更新
ワークフロー構成
実際の運用では、以下の2つのワークフローファイルで構成しています：
- サービス固有の AGENTS.md 週次更新 –
.github/workflows/__weekly_coding_agent_docs_update.yml - 全体共通ドキュメントの手動更新 –
.github/workflows/__update_coding_agent_docs_general.yml
前者は各サービス配下の AGENTS.md を週次でチェックし、後者はリポジトリ直下の AGENTS.md と docs/agent/guideline/*.md・docs/agent/template/*.md を必要なタイミングで手動整備するためのものです。この分離により、更新頻度と影響範囲が異なるドキュメントを適切に管理できます。
1. サービス固有の週次更新ワークフロー
各プロジェクト・サービスの AGENTS.md と README.md を週次で更新します。
name: __ Weekly coding agent docs update
on:
schedule: [ { cron: "0 20 * * 0" } ] # 毎週月曜 05:00 JST
workflow_dispatch:
permissions:
contents: write
pull-requests: write
issues: write
jobs:
issue:
runs-on: ubuntu-latest
strategy:
matrix:
include:
- agent_file: "services/service-a/AGENTS.md"
project_scope: "services/service-a/*"
service_name: "Service A"
readme_files: "services/service-a/README.md services/service-a/api/README.md services/service-a/frontend/README.md"
- agent_file: "services/service-b/AGENTS.md"
project_scope: "services/service-b/*"
service_name: "Service B"
readme_files: "services/service-b/frontend/README.md"
- agent_file: "services/service-c/AGENTS.md"
project_scope: "services/service-c/*"
service_name: "Service C"
readme_files: "services/service-c/frontend/README.md"
env:
GH_TOKEN: ${{ github.token }}
AGENT_FILE: ${{ matrix.agent_file }}
PROJECT_SCOPE: ${{ matrix.project_scope }}
SERVICE_NAME: ${{ matrix.service_name }}
README_FILES: ${{ matrix.readme_files }}
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 0
- name: Ensure labels (once)
shell: bash
run: |
set -euo pipefail
has() { gh label list --json name -q '.[].name' | grep -Fxq "$1"; }
has "automated" || gh label create automated --color "ededed" --description "automation"
has "docs" || gh label create docs --color "1D76DB" --description "documentation"
has "weekly-instructions" || gh label create weekly-instructions --color "5319E7" --description "weekly instructions task"
- name: Build issue body
id: body
shell: bash
run: |
set -euo pipefail
LAST_UPDATED="$(git log -1 --format=%cI -- "$AGENT_FILE" || git log -1 --format=%cI)"
NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
read -ra SCOPE <<< "$PROJECT_SCOPE"
COMMITS="$(git log --since="$LAST_UPDATED" --date=short --pretty=format:'- %h %ad %an: %s' -- "${SCOPE[@]}" || true)"
[ -z "$COMMITS" ] && COMMITS="- 期間内の変更はありません"
TREE="$(git ls-tree -r --name-only HEAD -- "${SCOPE[@]}" | awk -F/ '{print $1}' | sort | uniq -c | sort -nr | head -n 20)"
TITLE="[weekly] Update coding agent docs: $AGENT_FILE"
BODY="$RUNNER_TEMP/weekly-issue.md"; : > "$BODY"
printf -- "### Weekly Coding Agent Docs Update\n\n" >> "$BODY"
printf -- "**対象:** \`%s\`\n\n" "$AGENT_FILE" >> "$BODY"
printf -- "**前回更新:** %s / **集計:** %s 〜 %s\n\n" "$LAST_UPDATED" "$LAST_UPDATED" "$NOW" >> "$BODY"
printf -- "#### 期間内の変更（%s）\n%s\n\n" "$PROJECT_SCOPE" "$COMMITS" >> "$BODY"
printf -- "#### 現在の構成サマリ (Top 20)\n\`\`\`\n%s\n\`\`\`\n\n" "$TREE" >> "$BODY"
printf -- "#### 更新対象ファイル\n" >> "$BODY"
printf -- "- **AGENTS.md**: \`%s\`\n" "$AGENT_FILE" >> "$BODY"
if [ -n "$README_FILES" ]; then
printf -- "- **README files**:\n" >> "$BODY"
for readme in $README_FILES; do
printf -- " - \`%s\`\n" "$readme" >> "$BODY"
done
fi
printf -- "\n" >> "$BODY"
printf -- "#### TODO（担当者へ）\n" >> "$BODY"
printf -- "- 上記差分を踏まえ **%s** を更新（コードは変更しない）\n" "$AGENT_FILE" >> "$BODY"
printf -- "- 各サービスの **README.md** も必要に応じて更新（新機能追加、構成変更など）\n" >> "$BODY"
printf -- "- 冗長な一般論は圧縮、変更点の要旨をPR本文に列挙\n" >> "$BODY"
printf -- "- 秘密情報は記載しない（リンク参照）\n" >> "$BODY"
printf -- "- [ベストプラクティス](https://docs.github.com/ja/copilot/tutorials/coding-agent/get-the-best-results)を参考にしてください\n" >> "$BODY"
printf -- "- 現在のmdファイルの内容を引用しつつ、必要な更新を行う\n" >> "$BODY"
echo "TITLE=$TITLE" >> "$GITHUB_OUTPUT"
echo "BODY=$BODY" >> "$GITHUB_OUTPUT"
- name: Close previous weekly issues for this file
shell: bash
run: |
set -euo pipefail
FILE_BASENAME="$(basename "$AGENT_FILE")"
for num in $(gh issue list --state open --label weekly-instructions --search "$FILE_BASENAME in:title" --json number -q '.[].number'); do
gh issue close "$num" || true
done
- id: create_issue
name: Create issue (REST)
shell: bash
run: |
set -euo pipefail
TITLE='${{ steps.body.outputs.TITLE }}'
BODY_PATH='${{ steps.body.outputs.BODY }}'
RESP="$(gh api -X POST "repos/${GITHUB_REPOSITORY}/issues" \
-H "Accept: application/vnd.github+json" \
-f title="$TITLE" \
-f body="$(cat "$BODY_PATH")" \
-f labels[]=automated -f labels[]=docs -f labels[]=weekly-instructions)"
echo "$RESP"
NUMBER="$(printf '%s' "$RESP" | jq -r '.number')"
URL="$(printf '%s' "$RESP" | jq -r '.html_url')"
echo "number=$NUMBER" >> "$GITHUB_OUTPUT"
echo "url=$URL" >> "$GITHUB_OUTPUT"2. 全体共通ドキュメントの手動更新ワークフロー
全体共通のガイド（リポジトリ直下の AGENTS.md と docs/agent/guideline/*.md、docs/agent/template/*.md）は、.github/workflows/__update_coding_agent_docs_general.yml を workflow_dispatch で手動トリガーし、必要なタイミングでまとめて整備します。週次スケジュールには乗せず、コアテンプレートやガイドラインの刷新が必要になったときだけ実行する運用です。
実行すると Git の履歴から各ファイルの前回更新日時とその後の差分を集計し、以下のような Issue を自動生成します。
- `AGENTS.md`
- `docs/agent/guideline/service_design.md`
- `docs/agent/guideline/frontend_design.md`
- `docs/agent/guideline/api_typescript_design.md`
- `docs/agent/guideline/ubiquitous_language.md`
- `docs/agent/guideline/e2e_testing.md`Issue には、更新対象ファイルと前回更新以降のコミット、テンプレートへのリンク、遵守すべきルール（冗長な一般論を避ける／テンプレートを最新版へ揃える等）が記載されるため、担当者はそれを手引きにドキュメントをメンテナンスできます。
monorepo でスケールする設計
変更検知の仕組み
# 前回更新以降のコミットを自動抽出
LAST_UPDATED="$(git log -1 --format=%cI -- "$AGENT_FILE")"
COMMITS="$(git log --since="$LAST_UPDATED" --date=short --pretty=format:'- %h %ad %an: %s' -- "${SCOPE[@]}")"
# プロジェクト構成のサマリを生成（Top 20）
TREE="$(git ls-tree -r --name-only HEAD -- "${SCOPE[@]}" | awk -F/ '{print $1}' | sort | uniq -c | sort -nr | head -n 20)"この仕組みにより、コードベースの変更を自動的に検知し、Issue に含めることができます。
プロジェクトごとの並列処理
matrix.include で複数のプロジェクトを定義することで、並列で Issue を生成：
strategy:
matrix:
include:
- agent_file: "services/service-a/AGENTS.md"
project_scope: "services/service-a/*"
readme_files: "services/service-a/README.md ..."
- agent_file: "services/service-b/AGENTS.md"
project_scope: "services/service-b/*"
readme_files: "services/service-b/README.md"利点:
- サービスごとに独立した Issue が生成される
- 並列実行により効率的
- サービス追加時は matrix に1行追加するだけ
スコープの柔軟な設定
プロジェクト固有
- 特定のサービスディレクトリのみを監視
- 例:
services/service-name/*
全体共通
- 広範囲の変更を集計
- 例:
services/** packages/** biome.json turbo.json
これにより、必要な粒度でコンテキストを同期できます。
運用 Tips
スケジュール設定
scheduleは UTC。JST に合わせるときは 9 時間引いた cron を設定- 例：
0 20 * * 0= 毎週月曜 05:00 JST（UTC 20:00 日曜）
Issue 管理と Copilot の実行
- 週次の Issue は 既存の同じファイルに関する Issue を自動クローズしてから新規作成
- これにより、常に最新の1つのアクティブな Issue のみが存在する
- Issue には
automated,docs,weekly-instructionsラベルが自動付与 - Issue 作成後、手動で GitHub Copilot をアサインすることで作業が開始される
Copilot の動作について
- Issue へのアサイン: ✅ Copilot が自動的にタスクを実行し、PR を作成
- PR でのコメント: ❌
@copilotとコメントしても実行されない - Copilot を実行したい場合は、必ず Issue の Assignees に追加すること
ラベル管理
- ラベルは 初回に存在チェック → なければ自動作成
- ラベルの 配列パラメータは
[]形式で渡す（-f labels[]=automatedなど）
並列実行
matrix.includeにより、複数のプロジェクトが並列で実行される- プロジェクト固有のワークフロー: N個の Issue（プロジェクト数に応じて）
- 全体共通のワークフロー: 1つの Issue（ルートの AGENTS.md）
- matrix に登録したプロジェクト数 + 1個の Issue が自動生成される
Copilot のアサインと実行フロー
- GitHub Actions で Issue 自動生成（週次 cron または手動トリガー）
- Issue に GitHub Copilot を手動でアサイン
- Issue ページの右サイドバー「Assignees」から
copilotを選択 - アサインと同時に Copilot がタスクを読み取り、作業を開始
- Issue ページの右サイドバー「Assignees」から
- Copilot が自動的に PR を作成
- AGENTS.md ファイルと README.md の更新内容を含む PR
- PR 本文には変更内容のサマリが記載される
- レビュー後にマージ
- PR の内容を確認し、問題なければマージ
- 必要に応じて追加の修正を依頼
注意: Issue への Copilot のアサインは手動操作が必要です。ワークフローから自動アサインする機能は現状サポートされていません。
設計のポイント
1. 統一された形式による一貫性
課題: 各サービスで AGENTS.md の形式がバラバラだと、AI エージェントが混乱する
解決策:
- ルートの AGENTS.md が書き方ガイドとして機能
- 必須セクションを明確に定義
- 結果: すべてのサービスで一貫した構造を維持
2. 自動検知による鮮度維持
課題: 手動で AGENTS.md を更新すると、忘れやすく劣化していく
解決策:
- Git のコミット履歴から変更を自動抽出
- 週次で Issue を自動生成し、可視化
- 結果: コードベースと AGENTS.md が乖離しない
3. AI による自動更新
課題: AGENTS.md の更新作業自体が負担
解決策:
- Copilot をアサインすることで自動更新
- Issue に含まれる変更履歴を元に適切に更新
- 結果: 人間の作業は「レビューとマージ」のみ
4. monorepo でのスケール
課題: 複数サービスの AGENTS.md を個別に管理するのが辛い
解決策:
matrix.includeで並列処理- サービスごとに独立した Issue
- 結果: サービス数に関わらずスケールする仕組み
5. 既存 Issue の自動クローズ
課題: 週次で Issue が溜まっていく
解決策:
- 新しい Issue を作る前に、既存の同一ファイルの Issue を自動クローズ
- 結果: 常に最新の1つの Issue のみが存在し、管理がシンプル
実際の運用フロー
週次更新の流れ
-
毎週月曜 05:00 JST に GitHub Actions が自動実行
- プロジェクト数に応じた Issue が自動生成される
- 各 Issue には前回更新以降の変更履歴と構成サマリが含まれる
-
Issue に GitHub Copilot を手動でアサイン
- Issue ページを開き、右サイドバーの「Assignees」をクリック
copilotを検索して選択- アサインと同時に Copilot が作業を開始
-
Copilot が自動的に作業を実行
- Issue の内容を読み取り、AGENTS.md ファイルを更新
- README.md も必要に応じて更新
- 変更内容を含む PR を自動作成
-
PR のレビューとマージ
- 自動生成された PR の内容を確認
- 問題なければマージ、必要に応じて追加の修正を依頼
よくある質問
Q: PR のコメントで @copilot を呼べないの？
A: 現状、GitHub Copilot は Issue へのアサインでのみ動作します。PR のコメントでメンションしても実行されません。
Q: Issue への自動アサインはできないの？ A: GitHub の仕様上、ワークフローから Copilot を自動アサインする方法は現状サポートされていません。手動でアサインする必要があります。
Q: 複数の Issue を一度に処理できる？ A: Copilot を複数の Issue に同時にアサインすることは可能ですが、それぞれの Issue に対して個別に作業が実行されます。
まとめ：コンテキスト同期の自動化
この記事で紹介した仕組みは、AI コーディングエージェントのコンテキストを自動的に最新に保つための包括的なソリューションです。
解決した課題
| 課題 | 解決策 | 効果 |
|---|---|---|
| AGENTS.md とコードの乖離 | 週次の自動変更検知 | 鮮度維持 |
| 手動更新の負担と忘れ | AI による自動更新 | 作業削減 |
| 形式のバラつき | 統一されたガイドライン | 一貫性向上 |
| monorepo での管理の複雑さ | 並列処理の仕組み | スケール |
| Issue の乱立 | 自動クローズ | シンプルな管理 |
導入効果
定量的効果
- AGENTS.md 更新の工数: 月4時間 → 月30分（レビューのみ）
- 各サービスの形式統一: 統一されたガイドラインに従う
- Issue 管理: 手動 → 自動（100%自動化）
定性的効果
- AI の出力精度が安定
- コードベースとドキュメントの一貫性が向上
- チーム全体で AGENTS.md を意識する文化が醸成
- 新しいサービス追加時も一貫した形式を保てる
適用可能な規模
- 小規模: 単一プロジェクトでも効果あり（自動同期の恩恵）
- 中規模: 3-5 サービスの monorepo で特に効果的
- 大規模: matrix による並列処理でスケール可能
この仕組みの本質は「コンテキストの自動同期」です。 手動での管理を諦め、Git のコミット履歴と AI を組み合わせることで、ドキュメントが常に最新に保たれる世界を実現できます。
各サービスに AGENTS.md を配置し、統一されたガイドラインに従うことで、monorepo 環境でも単一プロジェクトでも、AI コーディングエージェントの精度を長期的に維持できるはずです。