writing-agents-md

AGENTS.md の作成

目的

AI コーディングエージェント向けの唯一の信頼できる情報源を生成または更新します。CLAUDE.md は @AGENTS.md のインポートとともに生成されます。その他のエージェント用ファイルは、依頼があった場合に作成します。**対象範囲：**現在の作業ディレクトリ（CWD）。出力パスはすべて POSIX 形式で、CWD からの相対パスです。

使用する場合／使用しない場合

次の場合に使用します：

• ユーザーが AGENTS.md、CLAUDE.md、またはエージェント用コンテキストファイル（.cursorrules、.windsurfrules、GEMINI.md、CODEX.md、.github/copilot-instructions.md）の作成または更新を依頼した場合。
• ユーザーが AI エージェントをプロジェクトに導入したい場合。
• ユーザーが既存の AGENTS.md のレビュー、採点、監査を依頼した場合 — このスキルがその入口です（reviewing-agents-md は別途存在しません）：references/review-prompt.md にある読み取り専用の批評と、references/independent-critic.md にあるルーブリックを使わないブラインドレビューを実施し、指摘事項を報告します。その後ユーザーから修正を依頼されない限り、ファイルの生成、更新、書き込みは行いません。

次の場合は使用しないでください：

• 単一ファイルのスクリプト、ビルド設定のない使い捨て PoC、または README しかないリポジトリ。最低条件は、実行可能なコマンドを少なくとも1つ含むビルド設定ファイルがあることです。

ルーティングのセルフテスト（この依頼はここで扱うべきですか？）：

依頼	ルート
「AGENTS.md、CLAUDE.md、またはエージェント用コンテキストファイルを作成／更新する」	ここ — 書き込みモード
「AGENTS.md をレビュー／採点／監査する」	ここ — 読み取り専用の批評モード（書き込みなし）
「スキル（SKILL.md）を作成またはリファクタリングする」	writing-skills
「スキルのフォルダーをレビュー／採点する」	reviewing-skills
「ルーブリック／仕様書／設計文書を作成する」	writing-rubrics／writing-specs／writing-designs

品質基準（デフォルト）

目標とする成果：

• 仕様違反なし（形式／スキーマ／検証チェック）、および
• ルーブリックスコア ≥ 4.5/5.0（A 評価）、および
• 批評レビューで P1 の指摘事項なし

ルーブリック：references/agents-md-rubric.md（唯一の信頼できる情報源）。

安全性／制約（必須）

• シークレット（例：.env、API キー、トークン、秘密鍵、認証情報）を読み取ったり、要求したり、貼り付けたりしないでください。
• ユーザーが明示的に依頼しない限り、ウェブの閲覧や外部システムの呼び出しを行わないでください。
• 分析／検証の一環として、破壊的なコマンド（データベースのリセット、デプロイ、公開）を実行しないでください。
• ユーザー確認のセクションに従い、ユーザーの明示的な承認を得てからファイルを書き込んでください。

分析フェーズ

事実を収集するため、以下の手順を実行します。最終ファイルに分析結果を含めないでください。

優先順位とトリアージ： コンテキストや時間が限られている場合は、次の順で取り組んでください。これらの T レベルはセクションの優先順位を示すものであり、評価基準における レビュー指摘事項 の P1/P2/P3 の優先順位とは別です。混同しないでください。

• T0（必須、絶対に省略しない）： CRITICAL セクションの正確性、コマンドの正確性、構造の妥当性、セキュリティ
• T1（推奨）： ドメインとコンテキスト、パターン、テスト戦略、環境。ワークスペース設定が検出された場合（turbo.json、nx.json、pnpm-workspace.yaml、package.json 内の workspaces、Cargo.toml 内の [workspace]、go.work）は、モノレポを T1 に引き上げてください。
• T2（あるとよい）： モノレポ（T1 に引き上げられていない場合）、CI、ツールの設定、検索、Git、デバッグ

行数の上限を超える場合は、優先順位の低いセクションから削除してください。まず T2（デバッグ -> CI -> Git -> 検索 -> ツールの設定 -> モノレポ）、次に T1（環境 -> テスト戦略 -> パターン -> ドメインとコンテキスト）を削除します。**T0 セクションは絶対に削除しません。行数の上限を理由に、セキュリティや安全に関する内容を省略してはいけません。**同じ優先順位内では、具体的な内容がより多いセクションを優先して残してください。

対象を絞った更新： ユーザーが特定のセクションの更新を依頼した場合は、そのセクションに関連する分析手順のみを実行してください。全体の再分析は省略します。変更したセクションと CRITICAL のみを検証してください（CRITICAL は常に再検証します）。

ファイルと環境の安全性： 安全性／制約に関するルールが適用されます。さらに、分析中は以下を守ってください。

• 環境変数ファイルのテンプレートのみを読み取ります：.env.example、.env.template、.env.sample、.env.local.example
• バイナリのロックファイル（例：bun.lockb）は読み取りません。glob を使って存在を検出しても、内容は読み取らないでください。
• 環境セクションの値には、説明用のプレースホルダーを使用します（例：DB_PASSWORD=<from secrets manager>）。.env.example やソースコード内の実際のデフォルト値をコピーしないでください。
• 例外：よく知られたローカル開発用のデフォルト（localhost、5432、postgres）は使用できます。

シンプルなプロジェクトのショートカット： 以下の条件をすべて満たす場合に適用します：（1）主要なビルド設定が 1 つ（uv run ... を呼び出す Makefile などの補助的なラッパーは数えません）、（2）主要なソースディレクトリが 1 つ（テスト／スクリプト／ドキュメントは数えません）、（3）モノレポのワークスペース設定がない。適用する場合は、ステップ 0～3 をすべて実行し、ステップ 4 ではメインのエントリーポイントのみを読み取ってください。

コンテキスト予算： 分析で多くの大きな設定ファイルを扱うなど、コンテキストを過剰に消費する場合は、検出範囲の拡大を止め、収集済みの情報を使って生成に進んでください。出力に `` を追加してください。1 つのカテゴリですべてのファイルを読み込むよりも、幅広く浅く（すべてのカテゴリを検出する）調査することを優先してください。

0. 既存の AGENTS.md とエージェントのコンテキストファイルを確認する

AGENTS.md が存在する場合は、まずそれを読んでください。出発点として扱い、絶対的なものとはみなさないでください。以下の厳選されたセクションを検証してください。

セクション	検証対象
Domain & Context	README、パッケージの説明、ソースコード
Patterns	実際のディレクトリ構成、インポート規則、コードスタイル
Testing Strategy	テスト設定ファイル、テストディレクトリの構成
Security	.gitignore、シークレットマネージャーのインポート、環境変数のパターン
Git conventions	git log --oneline -20、ブランチ名（Git リポジトリでない場合はスキップ）

既存のエージェントコンテキストファイル（.cursorrules、.windsurfrules、GEMINI.md、CODEX.md、.github/copilot-instructions.md）も確認してください。見つかった場合は、これらを AGENTS.md と併せて更新できることをユーザーに伝えてください。

セクションの更新ポリシー：

更新モード	セクション	再実行時の動作
自動検出（常に再生成）	CRITICAL、Commands、Structure、Env、Execution Context、Data & State、Search、Monorepo、CI、Tool Preferences、Debugging	プロジェクトファイルから上書き
厳選（有効な場合は保持）	Domain & Context、Security	既存の内容を保持し、検証可能なほど古くなっている場合のみ更新（下記参照）
ハイブリッド（検出してマージ）	Patterns、Testing Strategy、Git	検出結果からベースを再生成し、手動追加分をマージ

古くなったと判断する基準： README の目的や名前が変更された、プロジェクトの種類が変わった、または重要な用語が存在しない識別子を参照している場合、Domain & Context は古くなっています。シークレットの読み込み方法が変更された、.gitignore のパターンにずれが生じた、または新しい環境変数テンプレートに未記載の機密変数が含まれている場合、Security は古くなっています。

強制再検証（例外措置）： 上記の限定的な古さの基準では、誤っていてもこれらのテスト上は古くない厳選コンテンツが、再実行のたびに残る可能性があります（たとえば、コード内で別の既存識別子に名称変更された概念など）。ユーザーから厳選セクションの再検証を明示的に依頼された場合、またはスキーマのバージョンが上がった場合は、ソースから Domain & Context と Security を再導出し、保持されている内容との差分を確認してください。黙って保持するのではなく、ユーザーが確認できるよう差分を提示してください。この場合、厳選コンテンツを自動で上書きしてはいけません。まず提示し、その後の判断はユーザーに委ねてください。

古くなった内容の削除： 自動検出セクションでは、存在しないツール、パス、コマンドへの言及を削除してください。ハイブリッドセクションでは、削除された項目に `` の印を付けてください。

競合： プロジェクトファイルを優先してください。判断できない場合は `` を追加してください。

ドメイン用語の抽出： README（見出し、太字・斜体の用語、用語集セクション）、エントリーポイントのドキュメントコメント、設定の説明を調べ、ドメイン固有の用語（頭字語、ビジネス概念、プロジェクト固有の専門用語）を抽出してください。コード識別子にも使われており、文脈がなければエージェントが意味を誤解する可能性のある用語を含めてください（例：Workspace が「テナント」を意味し、「IDE のワークスペース」を意味しない場合）。API、URL、JSON など、広く理解されている用語は省略してください。ドメイン用語が見つからない場合は、Key Terms フィールドを省略してください。

既存の AGENTS.md がない場合： すべてのセクションをプロジェクトファイルから推定してください。具体的な根拠があるセクションのみを記載してください。最低限必要な出力： T0 セクションである CRITICAL、Commands、Structure のすべてに具体的な内容が必要です。また、プロジェクトにシークレットを扱う処理、デプロイ、公開、またはマイグレーションの対象領域がある場合は、Security も必要です（これらすべてが「優先度とトリアージ」で定義された、決して省略してはならない T0 セクションです）。目的や種類を推定できる場合は、Domain & Context も記載してください。Commands が空になる場合は生成せず、プロジェクトの構造が不十分であることをユーザーに伝えてください。

1. スタックを検出し、制約を特定する

プロジェクトのルートで設定ファイルを検索します。ビルド設定ファイルがサブディレクトリにしかない場合（例：backend/pyproject.toml と frontend/package.json）、1 階層下も検索します。glob を使って検出し、詳細を読み取ります。大きなファイル（500 行超）については、依存関係のセクションだけを grep してください。

検出の目的： references/detection-reference.md に記載されているファイルを、次のカテゴリ全体にわたって検索します：ビルドとランタイム、品質とフック、インフラとデプロイ、データと API、セキュリティと可観測性、ドキュメントとメタデータ。

判別ルール：

• template.yaml -> 最初の 20 行に AWSTemplateFormatVersion／Transform: AWS::Serverless がある場合のみ SAM とします
• app.json -> expo フィールド、または依存関係に react-native がある場合のみモバイル用とします
• package.json の volta -> Node/npm/yarn のバージョンが固定されています
• config.yaml／config.yml -> apiVersion と kind が含まれる場合は Kubernetes、そうでなければアプリ設定とします
• package.yaml -> *.cabal または stack.yaml もある場合のみ Haskell（hpack）とし、そうでなければ汎用設定として扱います
• Makefile -> ターゲットが npm／uv／cargo／go／mix を呼び出す場合はタスクランナーのラッパー、そうでなければビルドシステムとします
• マルチサービスのリポジトリにある Dockerfile -> 各サービスとその Dockerfile のパスを Structure に記載します

制約の導出： ロックファイルによって必須のパッケージマネージャーが決まります。同じエコシステム内で競合するマネージャーは禁止します（JS：npm/yarn/pnpm/bun、Python：pip/uv/poetry/pdm/pipenv）。異なるエコシステムのロックファイルは競合しません。

検出対象	必須	禁止
エコシステム内のロックファイル	そのパッケージマネージャー	同じエコシステム内で競合するマネージャー
biome.json	biome	eslint、prettier
依存関係に ruff	ruff	flake8、black、isort
Cargo.toml	cargo fmt、cargo clippy	--
go.mod + .golangci.yml	golangci-lint	--
deno.json	deno fmt、deno lint	--
.editorconfig	インデントのスタイル／サイズを遵守	--
Pre-commit フック	--	--no-verify
依存関係にある相互排他的なライブラリ	選択されたライブラリ	置き換えられる代替ライブラリ
pom.xml（build.gradle* なし）	mvn	gradle
build.gradle または build.gradle.kts（pom.xml なし）	gradlew がある場合は ./gradlew、なければ gradle	mvn
project.clj	lein	clj
deps.edn（project.clj なし）	clj	lein
build.sbt	sbt	mill
build.mill	mill	sbt
stack.yaml	stack	cabal
*.cabal + cabal.project（stack.yaml なし）	cabal	stack
.scalafmt.conf	scalafmt	--
.clj-kondo/	clj-kondo	--
checkstyle.xml	checkstyle	--

追加ルール：

• ロックファイルの競合 -> CI を確認して、どのマネージャーを使うか判断します。そのマネージャーを必須とします。不明な場合は ``。
• プライベートレジストリ -> 認証情報は含めず、URL を Env に記載します。
• コンテナー -> アプリが Docker で動作する場合に限り、docker compose run/exec を使います（データベースなど、インフラ専用の場合は除く）。
• モノレポ -> turbo.json -> turbo run、nx.json -> nx run／nx affected を使います。ルートとパッケージのどちらのスコープかを記載します。
• ポリグロット（ワークスペース設定なし） -> コマンドにスタックを示すラベルを付けます（例：# install (backend)）。オーケストレーション用ツールがない場合、モノレポのセクションは使いません。
• Git サブモジュール -> Structure にパスを記載します。
• 認識されていないスタック -> README とビルド設定を確認してコマンドを特定します。推測せず、根拠がないセクションは省略します。
• Java の併存：pom.xml と build.gradle* の両方がある場合、CI を確認してどちらを主に使うか判断し、その一方を必須とします。
• Clojure の併存：deps.edn と project.clj は併存することがあります。CI の根拠を優先します。CI がない、または判断が難しい場合は、project.clj があれば lein、なければ clj とします。不確かな場合は `` を追加します。
• Gradle ラッパー：gradlew がある場合は、gradle の代わりに ./gradlew を使います。
• Haskell の併存：stack.yaml と *.cabal の併存は通常の状態です。Stack がツールチェーンを管理するため、stack を使います。

2. エントリーポイントとデータの把握

主なエントリーポイント、テストランナーのエントリーとフィクスチャの場所、CI 設定を特定します。

実行コンテキスト： ホスト（デフォルト／Docker はインフラのみ） | Docker（アプリを Compose で実行） | Devcontainer | Nix | ハイブリッド | サーバーレス（Lambda／Cloud Functions など）

プロジェクトの種類 — 次のように分類します：ライブラリ（公開用スクリプトあり、デプロイなし） | アプリケーション（デプロイ設定、Dockerfile、エントリーポイントあり） | CLI／ツール（bin／[project.scripts] エントリーあり、デプロイなし） | 両方（公開とデプロイの両方あり）。判別に迷う場合は、公開とデプロイの両方があれば「両方」を優先し、不明な場合は「アプリケーション」とします。

データ、インフラストラクチャ、生成コード — 次の項目を検出し、振り分けます：

• DB／ORM／マイグレーション／ブローカー／API スキーマ -> データと状態（パスとメタデータのみ。実行可能なコマンドは重複を避けるため「コマンド」に記載）
• IaC／K8s／Helm -> 実行コンテキスト + 構成；シークレット -> セキュリティ；Env の読み込み + テンプレート -> Env
• ビルド出力ディレクトリ（dist/、target/、.next/） -> 構成（生成物）；コード生成ディレクトリ -> 構成（(generated -- do not edit)）+ CRITICAL NEVER
• コード生成ワークフロー（OpenAPI codegen、protobuf、GraphQL codegen） -> 生成コマンドを「コマンド」に、ソーススキーマを「データと状態」に、出力先を「構成」に記載
• 可観測性 -> パターン；ADR／RFC -> ドメインとコンテキスト；依存関係スキャン -> セキュリティ；デバッグツール -> デバッグ
• 仮想環境 -> 「構成」から除外し、「Env」に記載

3. コマンドの抽出

ビルド設定のスクリプト、タスクランナー（Makefile、Justfile、Taskfile.yml）、またはツールの慣例から正確なコマンドを特定します。公開／リリース、ドキュメント、デプロイ／IaC、デバッグ／REPL、スクリプトが存在する場合はコード生成のコマンドも含めます。CI またはビルド設定に記載されたツールの固定バージョンを反映します。設定ファイルでコマンドの存在を確認してください。分析中にコマンドを実行してはいけません（読み取り専用のものも含みます）。作業ディレクトリ： サブディレクトリから実行する必要があるコマンド（例：特定のパッケージにおけるマイグレーション）には、「コマンド」のコードブロック内で cd <path> && を先頭に付け、リポジトリのルートからコピーして実行できるようにします。

復旧手順： 各コマンドについて、失敗時の復旧アクションを特定します。情報源には、対応する :fix スクリプト（例：lint -> lint:fix）、キャッシュのクリアコマンド（例：rm -rf node_modules）、単一ファイルの再実行方法（例：vitest run <file>）、診断手順（例：「出力で型エラーを確認」）があります。そのツールに広く知られた修正コマンドがある場合は、それを使用します。ない場合は、診断アクションを指定します。

4. アーキテクチャパターンを検出する

対象範囲： ステップ 1 で検出したエコシステムのみを調査します。

アプローチ：

1. references/framework-patterns.md のチェックリストを使い、エントリーポイントまたは依存関係から主要なフレームワークを特定します。
2. ソースファイルを検索し、そのフレームワークで知られている規約の指標を確認します（framework-patterns のリファレンスを参照）。
3. 特定のフレームワークに依存しない横断的なパターンを調査します（framework-patterns のリファレンスの「Cross-cutting」表を参照）：エラー処理、ログ記録、設定の読み込み、インポート規約などです。モノレポの場合： パッケージ間のインポート規約（例：@org/pkg のようなスコープ付きパッケージ名と相対パスのどちらを使うか）を明示的に検出します。Patterns には必須のインポート方法を指示として記載します：「常に @scope/package-name 経由でインポートすること。パッケージ境界を越えて相対パスを使用しないこと。」
4. コード規約を検出する — 検出可能な場合、これらは Patterns の必須サブ項目です。
   • モジュールシステム： import／export（ESM）と require／module.exports（CJS）のどちらが使われているかを検索します。package.json の "type"、tsconfig.json の module 設定、または言語に相当する指標を確認します。混在している場合は、新規コードで使用すべき方式を記載します。
   • 非同期パターン： async／await、.then(、コールバックのシグネチャを検索します。主流のパターンを記載します。混在している場合は、新規コードで使用すべき方式を記載します。
   • 命名規約： ソースファイル名を 10～20 個サンプルし、大文字・小文字のパターン（kebab-case、camelCase、PascalCase、snake_case）を確認します。同じサンプルから、コンポーネント／クラス／関数の命名も確認します。サンプルの 80% を超えて一貫している規約のみを記載します。
5. 検出したパターンを示す代表的なファイルを最大 3 個読み、具体的な内容を確認して記録します。

具体的な根拠があるパターンのみ記録してください。 通常は 4～8 項目（最大 12 項目）です。あるカテゴリに 2 つのパターンが併存している場合（例：古いモジュールではコールバック、新しいモジュールでは async／await）、新規コードで使うべきパターンを明記し、もう一方にはレガシーとラベルを付けます。指示形式で記載します：「新規コードでは X を使用すること。古いモジュールには Y が存在しますが、依頼がない限り変更しないでください。」両方を説明するだけでは不十分です。エージェントには、どのように記述すべきかを示す必要があります。1 カテゴリあたり最大 2 項目とし、2 項目を超える場合は主流のものを記載して `` を追加します。

ツールの優先設定は、エージェントプラットフォームごとに異なります。対象エージェント（Claude Code の場合は shell より Read／Edit／Glob／Grep を優先）と、CRITICAL に記載されたプロジェクトの必須要件に基づいて設定します。プロジェクト固有の優先設定については、README／CONTRIBUTING.md を確認します。

AGENTS.md テンプレート

この正確な構造を生成します。簡潔な表現を使い、文章は最小限にします。具体的なデータがないセクションは省略します。テンプレート／プレースホルダーの HTML コメントは削除します。以下のコメントタイプは出力に保持します：, , , , ``（ユーザーが追加したものの場合）。

agents-md-version は出力スキーマを追跡するもので、セクションの追加、削除、再構成時にのみ更新します（内容の変更では更新しません）。現在のスキーマ：1。変更履歴については references/schema-changelog.md を参照してください。

古いスキーマバージョンの処理： 既存の AGENTS.md が古い agents-md-version の場合も、通常どおり Auto-detect／Curated／Hybrid の更新ポリシーを適用します。現在のスキーマバージョンで追加されたセクションを追加します。バージョン間で非推奨になったセクションを削除します。バージョンタグを現在のものに更新します。

バージョンタグ： 必須のスキーマバージョンタグとして を使用します。別個の 日付タグを任意で追加することもできます（ユーザーによる追加。最終生成日の追跡用）。見つかった場合は保持しますが、生成はしないでください。

行数の上限： シングルパッケージリポジトリでは 150 行未満、モノレポでは 200 行未満、複雑なマルチスタックのモノレポでは最大 250 行です。上限を超える場合は、Analysis Phase の優先順位に従って整理します。

具体的な Next.js + Prisma の例については、references/example-output.md を参照してください。

# AGENTS.md


## CRITICAL

- MUST: [package manager command]
- MUST: [lint command] before commit
- MUST: [test command] before PR
- MUST: Use `[dependency command]` to change deps (DO NOT edit config manually)
- NEVER: [forbidden tool/pattern]
- NEVER: Force push (`git push --force`, `git push -f`) to shared branches
- NEVER: Skip pre-commit hooks (--no-verify)
- NEVER: Commit or read secrets (`.env`, API keys, tokens, private keys)
- NEVER: Edit generated files in `[path]`
- PREFER: Built-in tools (file reader, editor, glob, grep) over shell equivalents (`cat`, `sed`, `find`, `grep`)
- ON FAIL: Read full error output before retry. Check Env for missing deps.
- ON FAIL (lint): If autofix available: run `[lint:fix command]`, then re-run `[lint command]`. Fix remaining errors manually.
- ON FAIL (test): Run single test file first: `[single test command]`
- ON FAIL (monorepo): Verify working directory with `pwd`

## Domain & Context

- Goal: [1 sentence project purpose]
- Type: [Library | Application | CLI/Tool | Both]
- License: [SPDX identifier]
- Key Terms:
  - `[Term]`: [Definition]
- Decisions: `[path to ADR/RFC dir]`

## Data & State

- Source of Truth: `[path to schema file]`
- Database: [engine]
- ORM/Driver: [name]
- Migrations: `[path]` (commands in Commands section)
- Seeding: `[path or reference to Commands]`
- API Schema: `[path]` ([OpenAPI | GraphQL | Protobuf])
- Codegen: `[command]` -> `[output path]` (generated -- do not edit)
- Broker: [type]

## Execution Context

- Run on: [Host | Docker | Devcontainer | Nix | Hybrid | Serverless]
- Prefix: [e.g., "docker compose exec app" or "N/A"]
- Deploys to: [target]
- Submodules: [paths]

## Monorepo

- Manager: [tool]
- Root: [commands that affect all packages]
- Scope: `[filter syntax]`
- Packages: [pattern]
- Deps: [root-level | package-level | both]

| Type | Path | Stack |
|------|------|-------|
| [category] | `[path]` | [runtime/tools] |

**Table compaction:** When multiple packages share the same type and stack, group them in a single row using brace expansion (e.g., `packages/{auth,billing,users}`). Use individual rows only where the stack differs meaningfully. Aim for under 12 rows. Every package must appear in the table — verify full coverage against the workspace listing.

## Commands

```bash
# install
[exact command]                # ON FAIL: [recovery step]
# test:unit
[exact command]                # ON FAIL: [recovery step]
# lint
[exact command]                # ON FAIL: [recovery step]
# [additional detected categories...]
[exact command]                # ON FAIL: [recovery step]
```

**ON FAIL comments:** Every command must include an inline `# ON FAIL: ...` comment with a concrete recovery step. Use the command's actual fix/retry mechanism (e.g., `# ON FAIL: rm -rf node_modules && pnpm install`). If no programmatic recovery exists, state the diagnostic step (e.g., `# ON FAIL: check output for type errors`). Omit ON FAIL only for commands where failure is self-explanatory (e.g., `dev` server start). **Never** use a destructive command (data-dropping reset, force-push, publish) as an `# ON FAIL:` recovery step — if the only recovery is destructive, omit ON FAIL and rely on the named danger guard in CRITICAL/Security instead.

## Structure

```
[dir]/          # [2-4 word purpose]
[dir]/          # [2-4 word purpose] (generated -- do not edit)
```

## Patterns

- **Module:** [ESM | CJS | dual]
- **Async:** [async/await | callbacks | Promises | mixed (use X for new code)]
- **Naming:** [file-naming-convention] files, [ComponentCase] components, [functionCase] functions
- [Framework/architectural pattern]: [where it applies]

## Search

- Semantic: `[tool] [index] "[query]"` -- conceptual queries . Exact: `[grep tool] "[pattern]" [path]` -- regex . Files: `[glob pattern]`

## Testing Strategy

- Runner: [tool]
- Fixtures: `[path]` [and/or factory library]
- Separation: [method]
- Coverage: [threshold or "No threshold"]
- E2E: [tool]
- Conventions: [key conventions]

## Security

- NEVER read/write: [paths]
- NEVER log/commit: [patterns]
- Secrets via: [mechanism]
- CI secrets: [mechanism, e.g., "GitHub Actions secrets", "Vault"]
- Dep scanning: `[command]`

## Env

- [Runtime]: [version or version file]

```bash
# Required vars
[VAR]=[description]
# Env-specific config
[path or mechanism for dev/staging/prod differentiation]
# Local setup
[commands]
```

## Debugging

- Logs: [how to access application logs locally]
- REPL: `[command]`
- Debugger: [launch config or attach instructions]

## Git

- Branch: `[pattern]`
- Commit: `[format]`
- Hooks: [description]
- PR: [requirements]
- Reviews: [conventions, e.g., "DB migrations require DBA review"]
- PR template: `[path]`
- Code owners: `[path]`

## CI

- Runs: [jobs]
- Required checks: [list]
- Artifacts: [location]

## Tool Preferences

| Task | Prefer | Avoid |
|------|--------|-------|
| [task] | [preferred tool] | [avoided alternative] |

再実行するタイミング

パッケージマネージャーの切り替え、テスト／lint フレームワークの変更、モノレポへのパッケージ追加、主要な依存関係（ORM、フレームワーク、ブローカー）の追加、CI の再構成、またはディレクトリ構成の再編成があった場合に再生成します。通常のコード変更や軽微な依存関係の更新では再生成しません。

ユーザーレビュー

シナリオ	ユーザーに表示する内容	アクション
新規	概要：セクション名＋各セクションの1行要約	書き込む前に確認を求めます。依頼があればドラフト全文を表示します。
更新（全体）	変更・追加・削除されたセクションを差分で表示し、変更のないセクションは名前のみを一覧表示	確認を求めます。
更新（対象指定）	依頼されたセクションのみを差分で表示	確認を求めます。
却下	該当なし	変更が必要なセクションを尋ね、その部分のみを再分析して再提示します。依頼がない限り、全体の再分析は省略します。
無人実行	何も表示しません	レビューを省略し、直接書き込みます。ユーザーが明示的に依頼した場合に限ります。

承認後にのみファイルを書き込みます。

実行

承認後、AGENTS.mdを書き込み、同じディレクトリにCLAUDE.mdを作成または更新します。

CLAUDE.md のマージ戦略：

• 既存ファイルがない場合 -> @AGENTS.mdインポートを含めて作成します。
• すでに@AGENTS.mdをインポートしている場合 -> すべての内容を保持し、ヘッダーコメントを更新します。
• 内容はあるがインポートがない場合 -> 既存の内容を読み込み、AGENTS.md と重複するセクション見出し（## CRITICAL、## Commandsなど）を確認します。重複が見つかった場合は、該当するセクション名を具体的に挙げてユーザーに警告し、上書きとして保持するか、マージするか、重複を削除するかを尋ねます。その後、@AGENTS.mdインポートを先頭に追加します。追加の@インポートは必ず保持します。

CLAUDE.md の内容 — 常に生成されたヘッダー``とインポートを含めます：

シナリオ	CLAUDE.md のインポート
単独リポジトリ	@AGENTS.md
モノレポのサブプロジェクト（親ディレクトリにCLAUDE.md/AGENTS.mdがある）	@AGENTS.md + @<relative-path>/CLAUDE.md（.gitルートまで上位をたどって親ファイルを探し、相対パスを計算します）
パッケージごとの分割（ルートが250行を超え、スタックが異なる）	@AGENTS.md + @<relative-path>/AGENTS.md（ローカルとルートの両方）

パッケージごとの分割ルール： ルートのAGENTS.mdには共通セクション（CRITICAL、Monorepo、Git、CI、Tool Preferences）を記載します。パッケージのAGENTS.mdにはパッケージ固有のセクション（Commands、Structure、Patterns、Testing、Env、Data & State）を記載します。パッケージのセクションはルートを上書きします。CRITICALは追加的です（矛盾がある場合はパッケージ側を優先し、``を追加します）。単一ファイルでは行数上限を満たせない場合に限り、分割します。

再実行の範囲： リポジトリのルートから実行する場合はルートのみを対象とします（古くなったパッケージごとのファイルについて警告し、再実行が必要な可能性のあるパッケージを一覧表示します）。パッケージのディレクトリから実行する場合は、そのパッケージのみを対象とします。CWDの外にあるファイルを、ユーザーに知らせずに更新してはいけません。

部分的な失敗： AGENTS.mdの書き込み後にCLAUDE.mdの書き込みが失敗した場合は、AGENTS.mdの書き込みが成功したことと、CLAUDE.mdを手動で作成する必要があることをユーザーに伝えます。AGENTS.mdをロールバックしてはいけません。AGENTS.md自体の書き込みが失敗した場合は、CLAUDE.mdの処理に進んではいけません。

その他のエージェント用コンテキストファイル

ユーザーから依頼があった場合に限り、同等のファイル（.cursorrules/.windsurfrules（内容をインラインで記述）、GEMINI.md/CODEX.md/.github/copilot-instructions.md（内容をコピー））を生成します。すべてのファイルに、固定の同期ヘッダー``を含めます。git shaやタイムスタンプは使用しません。これにより、AGENTS.mdの内容が変わらなければ、派生ファイルはバイト単位で同一のままになります（git-shaヘッダーはコミットごとに差分を生み、冪等性を損ないます）。AGENTS.mdを唯一の正とし、更新時には派生ファイルを再生成します。シンボリックリンクは使用しません。

エージェント固有の調整： Claude以外のエージェント向けに生成する場合は、そのエージェントの機能に合わせてTool Preferencesを調整します（例：Cursorはターミナルコマンドを使用し、Copilotはインライン提案を使用します）。Claude固有のツール名（Read/Edit/Glob/Grep）は、一般的な同等語またはそのエージェントのツール名に置き換えます。

検証

作成後、次の項目を確認してください。

構造チェック（1～10）：

1. コマンドが存在し、定義されている — 各コマンドのバイナリ名／スクリプト名をビルド設定で検索し、追跡可能であることを確認します。さらに、参照先が単に名前だけでなく、実際に定義されていることを確認します。npm／pnpm スクリプトの本体が空でないこと、Makefile／Justfile／Taskfile にターゲットが存在すること、またはバイナリが依存関係、bin/ エントリー、文書化された外部ツールのいずれかに解決されることを確認してください。本体が空、または存在しないスクリプトを指すコマンドは、このチェックに失敗します。その場合は `` を付けてください。（名前を追跡することは必要ですが、それだけでは不十分です。テストのためにコマンドを実行してはいけません。）
2. 構成が一致している — 記載されている各ディレクトリを glob で検索し、ディスク上に存在することを確認します。
3. プレースホルダーがない — [value] 形式の角括弧が残っていないことを確認します。
4. 古いコメントがない — , , , , `` を除き、HTML コメントが残っていないことを確認します。
5. 行数 — 上限（150／200／250 行）以内であることを確認します。
6. CLAUDE.md が有効 — @ インポートのパスが解決することを確認します（対象ファイルを glob で検索）。
7. 生成ディレクトリに明記がある — コード生成／ビルド出力ディレクトリがすべて「Structure」に注記されていることを確認します。
8. CRITICAL の必須項目がそろっている — パッケージマネージャー、lint、テストについて、それぞれ少なくとも 1 つ MUST ルールがあることを確認します。不足があればユーザーに警告してください。
9. 最低限のコマンドがそろっている — install、lint、および少なくとも 1 つの test コマンドが存在することを確認します。不足があれば警告してください。
10. 制約の整合性 — すべての NEVER が Step 1 の検出結果に対応していることを確認します（例：uv.lock が検出されたため NEVER pip）。対応する検出がない NEVER には `` を付けてください。

品質チェック（11～16）： 11. 具体性の lint — CRITICAL と Patterns を確認し、隣接する具体例を伴わない曖昧な指示がないか調べます。follow conventions、use standard、as appropriate、see docs、when necessary などの表現を検出してください。各指示にはコマンド、パス、または文字列どおりの例を含めてください。曖昧な項目には を付けてください。 12. **失敗からの復旧対応** — Commands のコードブロック内にある各コマンド（`dev`／サーバー起動コマンドを除く）に、`# ON FAIL:` コメントがあることを確認します。復旧コメントがない場合は を付けてください。 13. ドメイン用語の網羅性 — Domain & Context に Key Terms リストがある場合、各用語がほかのセクション（Structure、Patterns、Commands、Data & State）の少なくとも 1 つにも記載されていることを確認します。ファイル内のほかの箇所にない用語は削除するか、を付けてください。 14. **規約の最低限の網羅性** — Patterns セクションがあり、プロジェクトにソースコードが含まれている場合、適切なスタックに応じて Module、Async、Naming のサブ項目、またはその一部が含まれていることを確認します。検出されたスタックに必要な規約がない場合は を付けてください。 15. 対応が必要な REVIEW コメントが残っていない — 検証中に追加したすべての `` に、明確で実行可能な説明があることを確認します。検証で解決したものは削除してください。 16. 安全性の最低基準を適用 — Step 1 でシークレットを扱う箇所、デプロイ、公開、または破壊的なマイグレーションを検出した場合、ファイルに Security セクション、および／またはそれを保護する CRITICAL 項目が必須です。これは構造上の最低基準（Priority & triage の T0）です。セキュリティ上の対象を検出したのに保護策がない状態は、行数上限にかかわらず決して許容されません。不足している場合は、作成を中止してください。保護策を追加するか、プロジェクトに保護されていないセキュリティ上の対象があることをユーザーに報告してください。

失敗時： 修正して再検証してください。修正に再分析が必要な場合は、無効な項目を削除してください。検証に失敗するファイルを作成してはいけません。解決できない問題はユーザーに報告してください。

品質ゲート

検証後、2 段階のレビューを実施します。目標：Quality Bar（スコア 4.5 以上、P1 の指摘事項なし）。

フェーズ 1：自己批評レビュー

references/agents-md-rubric.md を使用して、生成された AGENTS.md を評価します。プロジェクトに初めて触れるつもりでファイルを読みます。

確認事項：

1. 曖昧な CRITICAL ルール — エージェントが合理的に誤解し得る MUST／NEVER がないか確認します。判定基準：このルールが何を求めているのか、能力のある開発者 2 人の意見が分かれる可能性はありますか？ある場合は、より具体的にします。
2. セクション間の矛盾 — CRITICAL で参照されているコマンドが Commands にない、Commands にあるツールが Env で言及されていない、Structure のパスが他のセクションのパスと一致しない、といった点を確認します。
3. 危険な操作へのガード不足 — ステップ 1 で検出されたリスクの高いツール（データベース、IaC、デプロイ、パッケージ公開）ごとに、CRITICAL または Security に、破壊的なコマンドを具体的に挙げた対応する安全策があり、禁止事項が明記されていることを確認します（「マイグレーションには注意」のような曖昧な記述は不合格です）。例：DB マイグレーションを検出した場合 -> NEVER: \prisma migrate reset` / `drizzle-kit drop` をローカル開発環境以外で実行しない（データが削除されます）、デプロイツールを検出した場合 -> NEVER: ローカルからデプロイしない（`vercel --prod`）— CI 経由でのみデプロイする、公開設定を検出した場合 -> NEVER: ローカルから `npm publish` を実行しない — CI のタグ経由でのみリリースする。また、破壊的なコマンドを # ON FAIL:のリカバリ手順に**決して**記載してはいけません（例：リカバリ手順としてmigrate reset` を使う）。代わりに、明示的な警告を付けたガード付きコマンドに誘導します。
4. 解決できない参照 — 定義されていない用語、関連する内容を要約せずに外部ドキュメントを参照しているパス、バージョンやインストール方法が記載されていないツール名を確認します。

対応：

• 再分析なしで修正できる場合（表現の明確化、相互参照の追加、曖昧なルールの具体化）-> その場で修正します。
• 再分析またはユーザーの入力が必要な場合 -> `` を追加して続行します。
• スコアが 4.5 未満、または P1 の指摘が残る場合は、P1／P2 の不足を修正し、先に進む前に Validation チェックを再実行します。

フェーズ 2：新しいコンテキストでの批評レビュー

レビュー担当者の判定が、このスキル自身のルーブリック（生成側もそれに最適化されており、同じルーブリックを使う批評担当者も盲点を共有する可能性があります）だけに依存しないよう、新しいコンテキストで 2 回に分けて批評レビューを実施します。

1. ブラインドレビュー（ルーブリックなし） — references/independent-critic.md を使用し、実作業に取りかかるエージェントとして、第一原則からファイルを評価します。このレビューではルーブリックやその評価項目を参照してはいけません。「このファイルに従うエージェントを、何が失敗させ、誤解させ、危険にさらすか」だけを確認します。目的は、ルーブリックに含まれていないリスクを見つけることです。
2. ルーブリックレビュー — references/review-prompt.md を使用し、共通のルーブリックに照らして採点・評価します。
3. 照合 — ブラインドレビューで挙がり、ルーブリックレビューで扱われなかったリスクは、すべてブラインドレビューでの深刻度のまま修正リストに加えます。見落とされたリスクはルーブリックの不備を示すものであり、そのリスクが軽微であることの証明ではありません。

実行方法：

• 環境がサブエージェントに対応している場合は、各レビュー用に新しいコンテキストのサブエージェントを起動します（ブラインドレビューにはルーブリックを渡してはいけません）。対応していない場合は直接レビューを実施します。ただし、同じコンテキストでのレビューは独立したレビューではありません。生成された AGENTS.md の先頭に `` を追加し、ユーザー向けの要約でその旨を明記します。
• P1 と P2 の修正に加え、ブラインドレビューで挙がり、照合の結果エスカレーションされたすべてのリスクを適用します（P3 は最後に対応します）。
• Validation チェックを再実行します。
• 最大 3 回繰り返し、品質基準を満たした時点で早期終了します。
• 3 回のループを経ても基準を満たさない場合は、実際の評価と残っている P1／P2 の指摘をパッチ文面とともにユーザーへ報告し、修正を適用するか現状のまま受け入れるか確認します。現状のまま受け入れられたファイルや基準未満のファイルを、グレード A または「基準を満たしている」と決して提示してはいけません。実際の評価と未解決の指摘を伝えます。

出力ルール

1. 最小限の文章 — 箇条書き／表を優先します。プレースホルダーは使用しません（該当セクションを解決するか省略します）。例は使用しません（実際の値のみ）。
2. 行数の上限 — 優先度の低いセクションから省略します（トリアージ順を参照）。ASCII のみを使用します（絵文字は使用しません）。
3. 安全性 — 安全性／制約のルールを適用します（シークレット、ウェブ、破壊的なコマンドは禁止です）。
4. 冪等性 — 変更のないプロジェクトでは、出力を同一にします。タイムスタンプ、Git SHA、ランダムな値は使用しません。セクションは固定のテンプレート順に出力し、表の行と CRITICAL の箇条書きは決定論的な順序にします。`` は、実行時にどれだけ読み取ったかではなく、ディスク上に根拠がないカテゴリに対応させます。実行時の読み取り予算が少なかったという理由だけで GAPS を追加してはいけません。内容に変更のない状態で再実行した場合、バイト単位で同一のファイルを生成します。
5. ツールの優先順位 — 組み込みのファイルリーダー、glob、grep ツールを主要な方法として使用します。Bash コマンドは代替手段です。エージェントに組み込みの同等機能がない場合にのみ使用します。
6. レジリエンス — 読み取れない設定ファイル（アクセス拒否エラーを含む）、空の glob、バイナリファイル、具体的なデータがないセクションはスキップし、値を捏造してはいけません。分析が不完全な場合は、`` を AGENTS.md の1行目に追加します。