ns-harness-agents-md

Agents.md 生成器

为编码 Agent 生成项目入口文档：{product_root}/AGENTS.md，根据仓库中实际安装和检测到的内容进行定制，而不是使用通用的 harness 脚手架模板。

然后，使用固定的 Rules 启动模板编写 {product_root}/CLAUDE.md（见步骤 5）。

设计原则

1. 以证据为依据——只列出项目中实际存在的技能、路径和工作流。猜测时标注 inferred。
2. 入口指引，而非根本大法——技术栈、布局和约束应写在 architecture-rules.md（ns-harness-architecture-rules）中。AGENTS.md 应引导 Agent 找到合适的文件和技能。
3. 不要复制粘贴 harness 模板——不要将 packages/harness/templates/AGENTS.md 原样复制到项目中。使用 references/agents-md.template.md 作为骨架，并根据侦察结果填充内容。
4. 精简——目标为 约 95–110 行（硬性上限为 130 行）。链接到 docs/context/ 和 harness 参考文档，不要将内容直接内嵌。
5. 优先面向 Agent——保存的文件供 Agent 使用，而非面向人类。保存前，使用 ../ns-harness/references/agent-artifact-compress.md 压缩内容。
6. 安全刷新——更新时，除非侦察结果证明内容有误，否则保留稳定且经过人工编辑的部分（语言例外、GitLab 服务名称、团队约定）。

Harness 发现

参见 ../ns-harness/references/harness-discovery.md 和 ../ns-harness/references/rules-sync.md。

输出	路径
项目 Agent 入口	{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 生成的基线内容
棕地项目／monorepo／README 中有团队约定	根据证据生成或刷新
用户手动编辑了 AGENTS.md 并希望 AI 合并	刷新并保留自定义部分
用户只需要磁盘中的技能列表	改用 npx @nextstage-brasil/harness agents-md——无需 AI

工作流

步骤 1 — 锚定

1. 确定 {product_root}（仓库根目录或 monorepo 产品目录）。
2. 如果 {product_root}/.nextstage-harness/ 存在，则将其确定为 {harness_root}。
3. 判断是创建还是刷新；如果 AGENTS.md 存在，则读取它。
4. 记录 {product_root} 下是否存在 agents.local.md（文件名不区分大小写）——在输出中加入本地覆盖规则；不要将其内容复制到 AGENTS.md。

步骤 2 — 侦察

按照 references/reconnaissance-checklist.md 执行。只读应用程序源代码。

最低要求：

1. 列出 .agents/skills/（已安装技能的目录名称）。
2. 检测 harness 路径（.nextstage-harness/、docs/、旧版 .cursor/rules/）。
3. 浏览 README.md，了解项目名称和摘要。
4. 记录 docs/context/ 下的棕地项目／上下文资料。

**检查点（建议）：**展示检测到的技能和拟定的 SDD 流程链；写入前确认。仅在明确要求自主运行时跳过。

步骤 3 — 起草 AGENTS.md

使用 references/agents-md.template.md 作为骨架。

编写规则：

• 首要操作 — 必须包含的章节：读取 AGENTS.md，然后在存在时读取 agents.local.md（不区分大小写），随后记录项目笔记中的 GitLab MCP 服务。
• 如何开始 — 必须包含的表格：Planning / Implementation / Ad-hoc，列出技能入口。
• Implementation 路由 — 必须包含优先级表（1–5），内容取自 code-skill-routing.md；链接到已安装的 ns-harness，以查看完整交接流程。
• 硬性停止条件 / 禁止事项 — 必须包含的章节：不得虚构角色，不得跳过 architecture-rules，ISSUE_URL → gitlab-issue 技能，不得使用推测性的版本文件夹。
• 产品锚点 — {product_root} = .（相对于此 AGENTS.md）。绝不写入绝对本地路径。
• 本地覆盖项 — 存在 agents.local.md 时（不区分大小写），Agent 在读取 AGENTS.md 后读取它。在 Layout 中标明存在/不存在；绝不将其内容内联。
• 已安装技能 — 使用 .agents/skills/ 中的准确名称，按角色分组，置于紧凑表格中。仅根据已安装技能构建 SDD 链。
• 不设角色章节 — 仅列出技能；不得包含“Agent personas”/子 Agent。
• Layout — 用一行简洁地列出存在/不存在项，或使用小型表格：rules、skills、local、docs/context|specs|versions。不得写成一篇显而易见的多行说明文。
• 不设 Workflows → Implementation 章节 — 路由表已涵盖此内容。仅保留 SDD 链及 brownfield/context 链接。
• Ownership + Language + Project notes — 合并为一个简短区块（≤5 个项目符号）：路由与 architecture-rules 的关系、语言、GitLab MCP / 特殊情况。
• Docker 和测试 — 始终保留 MUST NOT compose / restart without ask。仅添加侦察所得的主机与容器测试证据（例如主机上的 Vitest）。只有在有 PHP/PHPUnit 证据时，才纳入 ../ns-harness/references/docker-and-testing.md 中的完整 PHPUnit 区块；否则省略 PHPUnit 子章节。
• 保留 ``（如存在）。
• 不得内联架构规则 — 仅保留一行指向规则的说明。
• AGENTS.md 中仅使用英文。

**保存前（必须）：**应用 ../ns-harness/references/agent-artifact-compress.md（caveman ultra）。目标约 95–110 行；最多 130 行。仅写入压缩后的文件。

步骤 4 — 编写 AGENTS.md

1. 编写 {product_root}/AGENTS.md（压缩后）。
2. 除非用户明确要求，否则不要修改应用源代码。
3. 如果 architecture-rules.md 仍是 harness 存根，则添加说明，提示下一步运行 ns-harness-architecture-rules。

步骤 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.

不得包含其他内容。如果文件中有额外内容，则完全替换，除非用户要求保留某些特定内容。

步骤 6 — 报告

用简短的项目符号列出（3–5 项）：产品根目录、检测到的技能、建议的下一项技能（如果缺少 constitution，则为 ns-harness-architecture-rules）、是创建还是刷新。

刷新模式

更新现有 AGENTS.md 时：

1. 如果仍然准确，保留 Project-specific notes、语言策略以及 GitLab/MCP 名称。
2. 根据当前证据替换已安装技能、Layout 和工作流章节。
3. 如果 CLAUDE.md 偏离，则按照步骤 5 的模板重写。

质量标准（保存前自检）

• 已应用 agent-artifact-compress.md（极简风格）
• 包含首要操作部分（AGENTS.md → agents.local.md → GitLab MCP 服务）
• 包含“如何开始”表格（规划 / 实施 / 临时任务）
• 包含实施路由表（优先级 1–5）
• 包含硬性停止条件 / 禁止事项部分
• 所有权、语言和备注合并为一个简短区块
• 没有单独重复路由表的“工作流 → 实施”部分
• 包含本地覆盖规则（agents.local.md，不区分大小写）
• 不是对 harness templates/AGENTS.md 的逐字复制
• 列出的每项技能都存在于 .agents/skills/ 下
• 技能按角色分组（而非平铺所有名称）
• 没有“Agent 角色”/子 Agent 部分
• {product_root} 使用相对路径（. 或 monorepo 相对路径，绝不使用机器上的绝对路径）
• 不得出现 Docker；仅在有 PHP 依据时才出现 PHPUnit
• SDD 链仅使用已安装的技能
• CLAUDE.md 符合步骤 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 — 制品路径和关卡