Portfolio logo
Notes に戻る
🗂️

MonorepoでAGENTS.mdを標準化するための実践ガイド

#agents-md #documentation #monorepo #ai-agent

AIコーディングエージェントと開発者が同じテンポで進めるためには、作業の「共通語」を束ねるハブが欠かせません。Monorepoの中心でその役割を担うのがAGENTS.mdです。この記事では、ルートと各プロジェクトのAGENTS.mdをどのように設計すれば、誰が読んでもすぐに動ける状態をつくれるのかを、具体的なディレクトリ構成や実際の抜粋とともに解説します。

コーディングエージェントが迷わないドキュメント層

エージェントは「開かれたディレクトリから最も近いAGENTS.md」を読み込みます。つまり、どの階層でも一定の品質で動けるよう、AGENTS.mdはレイヤーごとに役割を分担させる必要があります。

  1. リポジトリ直下（全体レイヤー） 実装の細部には踏み込まず、サービス群の構成・ガイドライン・テンプレート・更新ワークフローといった“大枠”だけを説明します。ここでは「どこに何があるか」を伝えることに徹し、具体的な依存やコマンドは下位レイヤーへ委ねます。

  2. サービス直下（サービスレイヤー） 例えばservices/<domain>/配下のAGENTS.mdは、そのサービスに属する複数プロジェクトの関係図や共有ポリシーをまとめる場所です。全体設計の視点で「どのプロジェクトが何を担い、どの順番で参照すべきか」を案内しつつ、実装の詳細は各プロジェクトAGENTS.mdに従うよう明示します。これにより、どこから開いても必ずプロジェクト単位のガイドラインへ辿り着けます。

  3. プロジェクトディレクトリ（プロジェクトレイヤー） services/<domain>/<project>/AGENTS.mdでは、制約・実装ルール・Completion Gateなどを詳細に記述します。エージェントがここだけ読めば作業を完遂できるよう、テンプレートからリンクしたルールを引用しながら、ディレクトリ構成やコマンドを明記します。

この三層構造を守ることで、どの位置でAGENTS.mdを開いてもエージェントが迷子にならず、必要な粒度の情報にすぐアクセスできます。

全AGENTS.mdで統一したAIリマインダー

2025-10-11時点ですべてのAGENTS.mdに次の呼びかけを追加し、作業時に必ずdocs/agent/template/ai_driven.mdを参照するよう徹底しました。

When executing tasks, please refer to docs/agent/template/ai_driven.md.

リポジトリ階層によって相対パスは変わりますが、リンク先は共通テンプレートの「AI-Driven Development Common Guidelines」です。グローバルなルールをファイル横断で共有するアプローチは、Zenn記事「ワークスペース横断のグローバルルールファイル運用術」の実践内容を参考に採用しています。各プロジェクトの冒頭でこのリマインダーを読むことで、品質・テスト・セキュリティに関する意思決定を常に同じガイドラインへ回帰させられます。

ルートAGENTS.mdは作業のコックピット

まず押さえたいのは、リポジトリ直下のAGENTS.mdが「どこに何があるか」を高速に教えるコックピットになっていることです。実際の冒頭から、最初の索引ブロックを抜粋してみましょう。

# Workspace Repository Guide

> Always load the relevant Serena memories before starting work on this service.

## Documentation Index
- **[Service Design Guideline](docs/agent/guideline/service_design.md)** – Structure for services that aggregate multiple projects; emphasizes Serena memory usage.
- **[Frontend Design Guideline](docs/agent/guideline/frontend_design.md)** – Section order and writing rules when documenting frontend services.
- **[TypeScript API Design Guideline](docs/agent/guideline/api_typescript_design.md)** – Clean Architecture framing, contract documentation, and API authoring rubric.
- **[Ubiquitous Language Guideline](docs/agent/guideline/ubiquitous_language.md)** – Process for curating shared terminology with status tracking and Serena integration.
- **[E2E Testing Guideline](docs/agent/guideline/e2e_testing.md)** – Design-only Playwright policy for cross-service end-to-end coverage.

この索引に続いて、テンプレート一覧、サービス別ガイドへの動線、リポジトリ構造、用語集、文書更新ワークフローが連続して並びます。まさに「着席した瞬間に必要なレバーが見えるコックピット」です。

docs/agentディレクトリの地図

テンプレートとガイドラインはdocs/agent/に集約されています。実際のツリーと合わせて、主要ガイドの冒頭も覗いてみましょう。

docs/agent/
├── guideline/
│   ├── service_design.md        # 各サービスのAGENTS.mdを書く際の構成ルール
│   ├── frontend_design.md       # フロントエンド設計ガイドライン
│   ├── api_typescript_design.md # API設計と契約ドキュメント
│   ├── ubiquitous_language.md   # 用語集の更新手順
│   └── e2e_testing.md           # Playwrightを使う際の設計方針
└── template/
    ├── api_layered_architecture.md
    ├── api_testing.md
    ├── frontend_directory_feature_sliced.md
    ├── frontend_shared_ui_component.md
    └── mcp_servers_dev_assistants.md

テンプレートは「そのまま貼る」のではなく、各プロジェクトAGENTS.mdからリンクすることで最新版を参照できるようにしています。たとえばdocs/agent/guideline/frontend_design.mdの冒頭は次のようになっており、求められるセクション構成が即座に分かります。

# Frontend Design Guideline

> This guideline defines how frontend services document their architecture, UI kits, and test strategy.

## Required Sections
1. Completion Gates
2. Project Overview
3. Directory Structure
4. Coding Conventions
5. Component Design
6. Design System
7. State Management & Data Fetching
8. Routing
9. SEO
10. Testing
11. Security & Privacy
12. Accessibility

さらに、API向けのdocs/agent/guideline/api_typescript_design.mdには、Clean Architectureに沿ってエンドポイントを追加する際の手順が明快に書かれています。

### Endpoint Checklist
1. Update OpenAPI spec under `services/<domain>/schema/api/main/openapi/`.
2. Run `mise run codegen` to regenerate TypeScript contracts.
3. Implement use case under `application/usecase`.
4. Add outbound port in `application/ports/outbound` if needed.
5. Wire controller in `interface/controller`.
6. Create presenter in `interface/presenter`.
7. Register route module under `infrastructure/routes`.
8. Mount route in `src/index.ts`.
9. Bind dependencies inside `infrastructure/di/injection.ts`.
10. Write Vitest coverage in `test/`.

こうした抜粋をリンク越しに参照できるため、各プロジェクトAGENTS.mdでは重複を避けつつポイントだけを伝えられます。用語集（Ubiquitous Language）の運用方針については、Zennの記事「ドメイン駆動設計の用語集をチームで活用する」を参考にし、更新プロセスを明示して責任者を割り当てる運用を採用しました。

プロジェクトAGENTS.mdのレシピ

各プロジェクトはservices/<domain>/<surface>/AGENTS.mdのような階層で配置され、ほぼ同じレイアウトで記述されています。実際の記載例として、Completion Gateとプロジェクト概要の抜粋を見てみましょう。

## Completion Gates
- Always run `pnpm tsc --noEmit` and `pnpm run test` and `pnpm run format` before handing off work.
- Verify content linting via `pnpm lint` when editing Markdown notes.

## Project Overview
- **Goal**: Publish a content-driven portfolio with SEO-first pages.
- **Tech**: Astro SSR, Tailwind CSS, Partytown, Shiki for syntax highlighting.
- **Hosting**: Cloudflare Pages with Workers adapter.

  1. Completion Gateを最初に置く 作業完了直前に走らせるコマンド（型チェック・テスト・フォーマッタ）や、確認すべきログの場所を明示。セルフレビューのチェックリストとして使えます。

  2. プロジェクト概要をスナップショット化 ランタイム、主要ライブラリ、ホスティング、CIゲートなどを箇条書きでまとめ、初日に知っておくべき背景を一画面で把握できるようにします。

  3. ディレクトリ構成をASCIIアートで表示 代表的なパスと役割をコメント付きで記載。例としてAPIプロジェクトなら、application/・interface/・infrastructure/を図示し、どこで依存を切っているのかを明記します。

  4. テンプレートへの戻りリンク 「レイヤー責務」「エラーハンドリング」「SEOルール」といった詳細はテンプレートへ誘導。重複した説明を書くのではなく、参照関係で一貫性を保ちます。

  5. 運用チェックリスト スキーマ生成やルーティング追加など、差分が生まれやすい作業を番号付きの手順でまとめ、抜け漏れを防ぎます。

  6. 用語集へのホットリンク ubiquitous-language.mdを参照するよう記述し、新しい用語が生まれたら必ず辞書を更新する流れを定着させています。

このほか、ディレクトリ構成はASCIIアートで明示され、src/やtest/内のサブディレクトリが何を担当するのかコメント付きで説明されています。文章だけでなく実際のファイル構造とコード抜粋を指し示すことで、初見でも迷わず必要な場所に辿り着けるようになっています。

標準化を支えるワークフロー

統一フォーマットを維持するために、CIと自動Issueが常に裏で動いています。

詳しい自動更新フローやCopilotとの連携手順は、別記事「AIエージェント向けAGENTS.mdを自動更新する仕組み」にまとめています。

  • 週次シグナル .github/workflows/__weekly_coding_agent_docs_update.ymlが毎週、サービス配下のAGENTS.md差分を集約したIssueを生成。各サービスの担当者はこのIssueを起点にプロジェクトレベルの更新を行います。

  • 共通ドキュメントの手動更新 リポジトリ直下のAGENTS.mdやdocs/agent/guideline/*.md、docs/agent/template/*.mdをまとめて整えたい場合は、.github/workflows/__update_coding_agent_docs_general.ymlを手動トリガーします。全体レイヤーの設計ガイドだけを対象にしているため、サービス固有の変更と混ざることがありません。

  • Serenaメモリとの同期 ドキュメントに追記した重要ルールはSerenaのメモリにも反映。エージェントが対話開始時に読み込むため、最新ポリシーを即座に共有できます。

導入ステップのチートシート

これから新しいプロジェクトAGENTS.mdを書くなら、以下の順番で進めると迷いません。

  1. メモリをロード – 既存プロジェクトの文脈を把握し、呼称が衝突しないかチェック
  2. ガイドラインを読む – 自分が担当するレイヤーの設計ガイドで構成を確認
  3. テンプレートを選ぶ – 必要なセクションをリンクで取り込み、カスタムが必要な箇所だけ肉付け
  4. Completion Gateを決める – テスト・lint・ビルドなど必須の実行コマンドを具体的に書く
  5. ディレクトリ構成を描く – 実際のsrc/やtest/の役割をコメント付きで整理
  6. 運用チェックリストを作る – スキーマ生成やデプロイなど、日常の作業を手順化
  7. 用語集を整備 – 新しいドメイン用語があればubiquitous-language.mdを更新し、リンクを貼る

まとめ

AGENTS.mdを丁寧に整えることは、単なるドキュメント整備ではありません。誰かが着手した瞬間に「次に何をすればいいか」がわかり、エージェントと人間のアウトプットが揃うための設計行為です。ルートのコックピットで全体像を掴み、各プロジェクトのレシピで具体的な手順を共有し、ワークフローで鮮度を保つ。これらを組み合わせることで、Monorepoのどこで作業しても同じリズムで動けるチーム体験が生まれます。