ns-harness-agents-md

Agents.md ジェネレーター

コーディングエージェント向けのプロジェクトエントリードキュメントである {product_root}/AGENTS.md を、リポジトリに実際にインストールされているものや検出されたものに合わせて作成します。汎用ハーネスのひな形は使用しません。

続いて、固定 Rules ブートテンプレートを使って {product_root}/CLAUDE.md を作成します（ステップ 5 を参照）。

設計原則

1. 証拠に基づく — プロジェクトに実在するスキル、パス、ワークフローのみを記載します。推測した場合は inferred と記します。
2. 憲章ではなく、エントリーポインター — スタック、構成、制約は architecture-rules.md（ns-harness-architecture-rules）に記載します。AGENTS.md は、エージェントを適切なファイルやスキルに案内します。
3. ハーネステンプレートのコピー＆ペーストは禁止 — packages/harness/templates/AGENTS.md をプロジェクトにそのままコピーしないでください。references/agents-md.template.md を骨組みとして使用し、調査結果を反映します。
4. 簡潔に — 目標は約 95～110 行（上限は130 行）です。内容をインラインで記述するのではなく、docs/context/ とハーネスの参考資料へのリンクを使用します。
5. エージェント優先 — 保存するファイルは人間ではなく、エージェント向けです。保存前に ../ns-harness/references/agent-artifact-compress.md に従って圧縮します。
6. 更新に強い — 更新時は、調査結果によって誤りだと判明しない限り、安定した手編集セクション（言語に関する例外、GitLab サーバー名、チームの規約）を保持します。

ハーネスの検出

../ns-harness/references/harness-discovery.md と ../ns-harness/references/rules-sync.md を参照してください。

出力	パス
プロジェクトのエージェントエントリー	{product_root}/AGENTS.md
Claude Code ポインター	{product_root}/CLAUDE.md

サポートスキル（読み取り専用ヘルパー）

スキル	調査中の用途
ns-harness-architecture-rules	憲章が存在するか、またはまだスタブかを確認します。重複させず、リンクします
ns-harness-bootstrap-brownfield	brownfield-map.md がある場合はリンクします
ns-harness-codebase-reverse-spec	system-reverse-spec.md と .agent.md がある場合はリンクします

使用するタイミング

トリガー	アクション
harness init の後（CLI ですでに agents-md を実行済み）	プロジェクトのコンテキストに合わせて調整します。CLI のベースラインを重複させないでください
ブラウンフィールド、モノレポ、または README にチーム規約がある場合	証拠に基づいて生成または更新します
ユーザーが AGENTS.md を手編集しており、AI に統合を求める場合	カスタムセクションを保持して更新します
ユーザーがディスク上のスキル一覧だけを必要としている場合	代わりに npx @nextstage-brasil/harness agents-md を使用します。AI は不要です

ワークフロー

ステップ 1 — 基点の確認

1. {product_root}（リポジトリのルート、またはモノレポ内のプロダクトフォルダー）を特定します。
2. {harness_root} を特定します。存在する場合は {product_root}/.nextstage-harness/ です。
3. 新規作成か更新かを判断し、既存の AGENTS.md があれば読みます。
4. {product_root} に agents.local.md（ファイル名の大文字・小文字を区別しない）が存在するか確認します。出力にはローカルオーバーライドのルールを含めますが、その内容を AGENTS.md にコピーしないでください。

ステップ 2 — 調査

references/reconnaissance-checklist.md に従います。アプリケーションソースは読み取り専用です。

最低限、次を行います。

1. .agents/skills/（インストール済みスキルのディレクトリ名）を一覧表示します。
2. ハーネスのパス（.nextstage-harness/、docs/、レガシーの .cursor/rules/）を検出します。
3. プロジェクト名と概要を把握するため、README.md をざっと読みます。
4. docs/context/ 内のブラウンフィールド／コンテキスト関連アーティファクトを確認します。

チェックポイント（推奨）： 検出したスキルと提案する SDD チェーンを提示し、書き込み前に確認を求めます。明示的に自律実行する場合のみ省略します。

Step 3 — AGENTS.md のドラフト作成

references/agents-md.template.md をひな形として使用します。

執筆ルール：

• 最初に行うこと — 必須セクション：まず AGENTS.md を読み、次に agents.local.md が存在する場合は（大文字・小文字を区別せず）読み、その後、プロジェクトのメモから GitLab MCP サーバーを確認します。
• 開始方法 — 必須の表：Planning／Implementation／Ad-hoc と、スキルのエントリーポイントを記載します。
• 実装の振り分け — code-skill-routing.md に基づく優先順位の表（1～5）が必須です。完全な引き継ぎ手順については、インストール済みの ns-harness にリンクします。
• 明確な停止条件／禁止事項 — 必須セクション：ペルソナを創作しない、architecture-rules を飛ばさない、ISSUE_URL は gitlab-issue スキルに振り分ける、推測でバージョンフォルダーを作らない。
• 製品の基準パス — {product_root} = .（この AGENTS.md からの相対パス）です。絶対ローカルパスは記載しません。
• ローカルの上書き設定 — agents.local.md が存在する場合（大文字・小文字を区別しません）、エージェントは AGENTS.md の後に読みます。Layout には存在／不在を記載し、内容をインラインで記載しません。
• インストール済みスキル — .agents/skills/ にある正確な名前を、役割ごとにグループ化して簡潔な表にまとめます。SDD チェーンは、インストール済みのスキルだけで構成します。
• ペルソナのセクションは設けない — スキルのみとし、「Agent personas」やサブエージェントは記載しません。
• Layout — rules、skills、local、docs/context|specs|versions の有無を、簡潔な1行または小さな表で示します。ほぼ自明な内容を複数行にわたって説明しません。
• Workflows → Implementation セクションは設けない — 振り分け表で網羅されます。SDD チェーンと brownfield／context のリンクのみを残します。
• Ownership + Language + Project notes — 短いブロック1つ（箇条書き5項目以内）：振り分けルールと architecture-rules、言語、GitLab MCP／注意事項を記載します。
• Docker とテスト — 必ず「依頼がない限り compose／再起動をしてはならない」を残します。調査で確認できたホストとコンテナーのテスト証跡のみを追加します（例：ホスト上の Vitest）。PHP／PHPUnit が確認できた場合に限り、../ns-harness/references/docker-and-testing.md の PHPUnit ブロック全体を含めます。それ以外の場合は PHPUnit の小見出しを省略します。
• `` がある場合は保持します。
• architecture rules をインラインで記載しません。参照先を示す1行のみ記載します。
• AGENTS.md の内容は英語のみとします。

保存前（必須）： ../ns-harness/references/agent-artifact-compress.md を適用します（caveman ultra）。目標は約95～110行、最大130行です。圧縮したファイルのみを書き込みます。

Step 4 — AGENTS.md の作成

1. {product_root}/AGENTS.md を作成します（圧縮後）。
2. 明示的に依頼されない限り、アプリケーションのソースを変更しません。
3. architecture-rules.md がまだハーネスのスタブである場合は、次に ns-harness-architecture-rules を実行するよう記載します。

Step 5 — CLAUDE.md の作成

{product_root}/CLAUDE.md に次の内容をそのまま記載します。

# Rules

CRITICAL — NO EXCEPTIONS.

Before any work: read `AGENTS.md` full → load every file it requires → follow its flow.

Must load:
- `AGENTS.local.md` (every session / every turn)
- all `alwaysApply: true` rules (`.nextstage-harness/rules/`)
- any NON-NEGOTIABLE / FIRST ACTION file for the task

No skip. No defer. No memory-only. Missing file → stop, ask human.

Then skills / subagents / task as AGENTS.md says.

## Subagents

`@.claude/agents` — use them; model optional per agent.

ほかの内容は記載しません。ファイルに追加の内容がある場合、ユーザーが特定の内容の保持を求めていない限り、全置換します。

Step 6 — 報告

簡潔な箇条書き（3～5項目）：製品の基準パス、検出したスキル、推奨する次のスキル（constitution がない場合は ns-harness-architecture-rules）、新規作成か更新か。

更新モード

既存の AGENTS.md を更新する場合：

1. 引き続き正確であれば、Project-specific notes、言語ポリシー、GitLab／MCP の名称を保持します。
2. インストール済みスキル、Layout、ワークフローの各セクションは、最新の証拠に基づいて置き換えます。
3. CLAUDE.md の内容が Step 5 のテンプレートからずれている場合は、書き直します。

品質基準（保存前にセルフチェック）

• agent-artifact-compress.md を適用済み（極限まで簡潔に）
• 最初のアクションのセクションがある（AGENTS.md → agents.local.md → GitLab MCP server）
• 開始方法の表がある（Planning / Implementation / Ad-hoc）
• 実装のルーティング表がある（優先度 1～5）
• ハードストップ／禁止事項のセクションがある
• 所有権／言語／メモを、1 つの短いブロックにまとめている
• ルーティング表と同じ内容を「Workflows → Implementation」として別途記載していない
• ローカル上書きのルールがある（agents.local.md、大文字と小文字を区別しない）
• ハーネスの templates/AGENTS.md をそのままコピーしていない
• 記載されているすべてのスキルが .agents/skills/ に存在する
• スキルが役割ごとに分類されている（すべての名前を平坦に列挙していない）
• 「Agent personas」／サブエージェントのセクションがない
• {product_root} が相対パス（. またはモノレポ内の相対パス。絶対的なマシンパスは不可）
• Docker を記載していない。PHP が確認できる場合のみ PHPUnit を記載している
• SDD チェーンで、インストール済みのスキルのみを使用している
• CLAUDE.md が Step 5（Rules boot + AGENTS.md + .claude/agents）に準拠している（圧縮なし）
• スタック／モジュールの詳細な掘り下げがない（architecture-rules.md の範囲）
• 行数が 130 以下（理想は 95～110）

関連スキル

• ns-harness-architecture-rules — 技術的な憲章（後で、または並行して実行）
• ns-harness-bootstrap-brownfield — SDD 計画のためのブラウンフィールドマップ
• ns-harness-codebase-reverse-spec — ビジネス動作仕様
• ns-harness — 成果物のパスとゲート