AI Create / Review AGENTS.md
2つのモード：作成（新しいAGENTS.mdを作成）またはレビュー（既存のAGENTS.mdを研究に基づく品質基準でレビュー）。
モード検出
- ユーザーが既存のAGENTS.mdを提供、またはそれを指定した場合 → レビューモード
- ユーザーが作成/スキャフォールド/生成を依頼した場合 → 作成モード
- 曖昧な場合 → 確認:
(c)reate 新しいAGENTS.mdを作成 または (r)eview 既存のものをレビュー？
作成モード
ステップ 1: 配置場所の確認
AGENTS.md をどこに配置しますか？
(r)oot — リポジトリ全体のベースライン
(p)ath — 特定のディレクトリ（パスを指定）
モノレポの場合: ルート + パッケージごとのファイルを提案。最も近い AGENTS.md が優先されます。
ターゲットパスに既に AGENTS.md が存在する場合 → 確認: ファイルが存在します。(r)eview 既存 / (o)verwrite 上書き / (Q)uit 終了？
ステップ 2: 専門家としての思考
書き始める前に、このプロジェクトについて以下を判断する：
- 何が発見困難か？ package.json、設定ファイル、ディレクトリ構成から推測できないものは？
- 何が危険か？ サイレント障害を引き起こすコマンドやパターンは？
- 何が曖昧か？ 2つの有効なアプローチがあり、エージェントが誤った方を選択する可能性がある箇所は？
- 何が非標準か？ フレームワークのデフォルトと異なる慣習は？
すべての答えが「なし」の場合 — プロジェクトに AGENTS.md は不要かもしれません。その旨を伝えてください。
package.json やビルド設定がないリポジトリ（ドキュメントのみ、データリポジトリ、単純なスクリプト）の場合: ミッションと判断境界のみに焦点を当てる — ツールチェーンとクロージャのセクションは該当しません。
ステップ 3: 優先順位順に記述
以下の順序で、「発見困難テスト」に合格したセクションのみを追加する：
- ミッション（2～4文） — プロジェクトの目的 + エージェントが推測できないコア制約
- ツールチェーンレジストリ — コマンドを表形式で。ツールが強制する内容ではなく
- 判断境界 — NEVER / ASK / ALWAYS の階層
- クロージャ定義 — 「完了」＝ 特定の終了コード
- エスカレーションルール — ブロックされた場合の対処
- タスク別セクション — 「記述時… / レビュー時… / リリース時…」
ステップ 4: 検証
- 合計 ≤ 150行（最適: 60～100）
- 各セクション ≤ 50行
- すべての指示が「このコマンドで完了が証明されるか？」に答えていること
- すべての「禁止」には「代わりにこうせよ」がペアになっていること
- リンタールールの再記述がないこと（ツールチェーンが優先）
- コマンドのない散文段落がないこと
必須 — references/knowledge-base.md を読む — 研究に基づくパターンとエビデンスを参照。
必須 — references/template.md を読む — スターター構造を参照。
ユーザーが完成した AGENTS.md の例を求めた場合、またはリポジトリが JS/TS モノレポの場合のみ references/example.md を読み込む （これは turborepo + pnpm の実例です） — それ以外の場合はスキップ。
レビューモードで、対象の AGENTS.md が 20行未満の場合、references/knowledge-base.md は読み込まない — 本文のチェックリストとアンチパターンリストで十分です。
レビューモード
提供された AGENTS.md を、研究に基づく品質基準で評価します。
スコアリング次元
| 次元 | 重み | 評価内容 |
|---|---|---|
| シグナル密度 | 25% | 発見困難な専門知識の行数割合 VS 汎用的/冗長な行 |
| コマンドファースト | 20% | すべての指示に検証可能なコマンドまたは終了コードがあるか |
| クロージャ定義 | 15% | 具体的なチェックを伴う明示的な「完了」基準 |
| 境界システム | 15% | NEVER/ASK/ALWAYS の階層が存在し、具体的であるか |
| 長さの規律 | 10% | 合計 ≤150、セクションごと ≤50、冗長さなし |
| アンチパターン非存在 | 15% | 失敗が証明されたパターンがないか |
スコアリングガイダンス
- シグナル密度は厳しく評価 — 成熟したリポジトリで確立されたツールチェーンがある場合、ほとんどのコンテンツは冗長である可能性が高い
- クロージャ/境界は寛大に評価 — グリーンフィールドプロジェクトの場合、まだ CI ゲートがない可能性がある
- 長さは厳しく評価 — モノレポのルートファイルの場合、全パッケージのすべてのセッションで読み込まれる
- 合計スコア < 40 の場合: 段階的な修正ではなく書き直しを推奨
アンチパターンチェックリスト
以下があればフラグを立てる（エージェントのパフォーマンスを低下させることが実証されている）：
- コマンドのない散文段落
- 曖昧な指示（「注意して」「可能な限り」）
- 矛盾する優先順位の明示的な順序付けなし
- リンター設定ですでに強制されているスタイルルール
- アーキテクチャ概要（過度な探索を引き起こす）
- 15以上の警告と、それにペアになっていない代替案
-
/initコマンドによる LLM 生成ボイラープレート - ツールチェーンが強制する内容の再記述
- ピンクゾウ違反（長い「禁止」リストが禁止概念をアクティブに保つ）
出力形式
## AGENTS.md レビュー: <ファイル名またはパス>
**スコア**: X/100
**判定**: [本番準備完了 / 修正が必要 / 書き直し推奨]
### 長所
- ...
### 問題点（重要度順）
1. [CRITICAL] ...
2. [HIGH] ...
3. [LOW] ...
### 書き直し提案
1. ...
2. ...
適用
レビュー自体が成果物ではありません — より良い AGENTS.md が成果物です。レビュー提示後、以下を提案：
適用しますか？ (a)ll すべて / (s)elect 番号で選択 / (n)one なし
(a) または (s) の場合: ファイルをその場で編集し、番号項目を1つずつ処理、その後スコアリング次元を再実行し、新しいスコアを古いスコアとともに報告する。レビューでフラグが立っていない行はそのまま維持 — レビューは書き直しの命令ではなく、黙って「改善」することは著者の意図と文体を損なうレビューパスです。
ユーザーがパスではなくインラインでコンテンツを提供した場合、またはファイルが書き込み不可の場合は、この提案をスキップする。改善を適用したと報告するのではなく、その旨を伝えること。
必須 — references/knowledge-base.md を読む — 各基準の背後にある研究エビデンスを参照。
禁止事項 (NEVER)
- エージェントがリポジトリ構造から発見できるコンテンツを絶対に含めない — package.json のスクリプト、ディレクトリレイアウト、設定ファイルは自己文書化されています。再記述はトークンを無駄にし、メンテナンスのずれを生みます。代わりに: ファイルを参照する（
see biome.json） - リンター/フォーマッタのルールを絶対に再記述しない — ツール自体が制約です。重複は陳腐化を生み、不要な要件はエージェントのパフォーマンスを積極的に低下させます。代わりに: 実行コマンドのみをリストする（
Lint: \pnpm lint``） - 「禁止」を「代わりにこうせよ」なしで絶対に書かない — 警告のみのドキュメントは過度な探索を引き起こします。15以上の禁止と代替案なしは、エージェントを保守的にし、生産性を低下させます。代わりに: すべての禁止には正しい代替案をペアにする
- 絶対に150行を超えない — このしきい値を超えると、利得は逆転し、ファイルは品質を積極的に損ないます。代わりに: 詳細は参照ファイルに抽出するか削除する
- LLM 生成コンテンツを最終版として絶対に使用しない —
/initの出力はエージェントが既に知っていることの目録です。パフォーマンスを低下させ、コストを増大させます。代わりに: 下書きの目録として扱い、ツールチェーンが既に強制しているものはすべて削除する - 絶対に散文段落を書かない — エージェントはスキップします。コマンド、テーブル、検証可能な成果を伴う箇条書きを使用してください。代わりに: コマンド + 終了コード + 1行の説明に変換する