第3章：AGENTS.md 設計

この章で扱うこと

• 何を書くか（規約/手順/品質基準/禁止事項）
• 適用範囲（ディレクトリツリー）と運用（更新・レビュー）の考え方

AGENTS.md の役割

AGENTS.md は、エージェントに対する 運用ルールの固定 です。 個々の会話で都度説明するのではなく、リポジトリに「期待するやり方」を資産として置きます。

期待効果は次の通りです。

• 再現性：実行手順と品質ゲートが一定になり、成果が安定する
• 統制：禁止事項/承認境界/変更禁止領域を明文化できる
• オンボーディング：新規メンバー/新規エージェントに同じ指示を適用できる

何を書くか（推奨構成）

最低限、次を含めます。

• 目的（このリポジトリで達成したい状態）
• 基本ルール（言語、トーン、断定禁止、根拠提示など）
• リポジトリ運用（編集対象、生成物の扱い、実行すべきコマンド）
• 品質基準（lint/test/build、差分サイズ、レビュー観点）
• 禁止事項（Secrets、破壊的操作、監査性を損なう行為）

例（骨格）：

# Agent Instructions

## 基本
- 出力言語、表記、断定禁止、根拠提示

## リポジトリ運用
- 編集対象ディレクトリ
- 実行コマンド（例: npm test）

## 禁止事項
- Secrets を出力しない
- force push 等は事前承認

適用範囲（スコープ）

運用上は「どの指示が、どのディレクトリに効くか」が重要です。 一般に、AGENTS.md は 配置したディレクトリ配下のツリー に適用され、サブディレクトリにより詳細な AGENTS.md がある場合は上書きされます。

この性質を使うと、例えば次が可能になります。

• 全体：基本ルール/品質ゲート/禁止事項
• 特定領域：生成物ディレクトリは編集禁止、DB マイグレーションは承認必須、などの例外を明記

運用（更新・レビュー）

AGENTS.md は「規約」なので、変更管理が必要です。

• 変更理由と影響範囲を PR に残す（なぜ変えたか）
• 例外対応は恒久化せず、ルールに還元する（再発防止）
• 四半期棚卸しで陳腐化（コマンド、フォルダ、手順）を点検する

Companion 資産（参照先）

Companion repo: itdojp/GitHub-AgentOps-companion

• エージェント指示: AGENTS.md

章末チェックリスト（ドラフト）

注記: 本チェックリストは最小構成です。実運用では「編集対象/生成物/禁止領域」など、リポジトリ固有の条件を追記してください。

• 目的/禁止事項/品質基準/推奨手順が明記されている
• 適用範囲と例外（サブディレクトリの上書き）が運用できる