ns-harness-prepare

Harness Prepare

在 harness init 之后，编排完整的存量项目接入流程。你不会取代各个工作技能，而是按顺序逐一运行它们，每次只执行一个阻塞步骤。启动检查通过时，无需事先征求确认。

状态保存在磁盘文件中，而非聊天记录中。开始后续步骤前，重新读取输出。

Harness 发现

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

输出	路径
技术章程	{harness_root}/rules/architecture-rules.md
技术栈／模块映射（面向 Agent）	{product_root}/docs/context/brownfield-map.md
业务逆向规格（面向人类）	{product_root}/docs/context/system-reverse-spec.md
业务逆向索引（面向 Agent）	{product_root}/docs/context/system-reverse-spec.agent.md
项目 Agent 入口文件	{product_root}/AGENTS.md
Claude 指针文件	{product_root}/CLAUDE.md

适用场景

触发条件	操作
harness init 之后立即执行（brownfield 预设）	运行完整准备流程
用户说“准备项目”／/ns-harness-prepare	运行完整准备流程
重大重构、新增模块／技术栈，或上下文文档过时	重新运行完整准备流程
用户只需要一个工作步骤	不要使用此技能——直接调用对应的工作技能
Greenfield 项目，没有应用代码	停止——说明准备流程需要扫描代码库

前提条件

1. 已完成 harness init（或满足等效条件：存在 .agents/skills/ + .nextstage-harness/）。
2. 已安装工作技能：ns-harness-architecture-rules、ns-harness-bootstrap-brownfield、ns-harness-codebase-reverse-spec、ns-harness-agents-md。
3. 对 {product_root} 下的应用源代码具有只读访问权限。

如果缺少工作技能，请停止并告知用户：

npx @nextstage-brasil/harness --preset spec-driven --yes

启动（每个会话必须执行一次）

1. 根据 Harness 发现流程解析 {product_root} 和 {harness_root}。
2. 应用默认设置（检查通过时不要询问）：
   • Markdown 工件的输出语言 = 用户对话所用语言
   • 逆向规格（system-reverse-spec.md + .agent.md）= 仅限英语（优先于对话语言）
   • 逆向规格范围 = 整个产品；深度 = 执行层面
   • 模式 = 根据磁盘上现有工件选择创建或刷新
3. 运行启动检查：
   • 工作技能已安装（ns-harness-architecture-rules、ns-harness-bootstrap-brownfield、ns-harness-codebase-reverse-spec、ns-harness-agents-md）
   • {product_root} 下存在应用代码（清单、src/、app/ 等）
4. 如果任一检查失败：显示简短的失败表格（失败项 + 修复方法），然后停止。不要要求用户确认有问题的范围。
5. 如果所有检查均通过：用一行或简短摘要列出范围（{product_root}、{harness_root}、语言、逆向规格默认设置、创建／刷新），并立即进入步骤 1——不要等待用户回复“确认？”或批准。

编排要求

• 启动摘要成功后，在同一轮回复中开始步骤 1（无需等待确认）。
• 按以下固定顺序执行全部四个工作步骤。
• 步骤之间不要询问“继续下一步吗？”。
• 启动检查全部通过时，不要询问“确认？”或请求批准范围。
• 不要在父会话中自行执行工作流程——在同一会话中遵循每个工作技能的流程（每个步骤开始时读取对应的 SKILL.md）。
• 不要跳过 ns-harness-codebase-reverse-spec——完整准备流程包含此步骤。
• 步骤 1 之后、步骤 2 之前，运行 npx @nextstage-brasil/harness sync（shell）。

保存前压缩（必需）

面向 Agent 的输出不是给人看的。每次对 Agent 产物执行 Write 前，都要阅读并遵循：

../ns-harness/references/agent-artifact-compress.md

写入	压缩
architecture-rules.md	是
brownfield-map.md	是
system-reverse-spec.agent.md	是
AGENTS.md	是
system-reverse-spec.md	否（面向人的正文）
CLAUDE.md	否（Rules 引导 + AGENTS.md + .claude/agents）

由工作者负责压缩；对于标记为“是”的文件，如果相较于该参考中的软性目标显得冗长如文章，prepare 必须拒绝继续推进。

步骤顺序

步骤 1 — 架构规则

技能： ns-harness-architecture-rules

目标： 创建或刷新 {harness_root}/rules/architecture-rules.md。

提示锚点：

Scan {product_root} and generate or refresh architecture-rules.md.
Evidence-based only; mark inferred items. Target 80–200 lines.
Telegraphic tables/bullets — agent hot memory, not prose.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md (caveman ultra).

完整遵循工作者技能工作流。只读应用代码。

步骤 1b — 同步规则适配器（shell）

在项目根目录中运行：

npx @nextstage-brasil/harness sync

同步成功前不要继续步骤 2。

步骤 2 — Brownfield 映射

技能： ns-harness-bootstrap-brownfield

目标： 创建或更新 {product_root}/docs/context/brownfield-map.md。

提示锚点：

Bootstrap brownfield analysis for {product_root}.
Agent-dense brownfield-map.md (tables only). Link architecture-rules.md for stack — do not duplicate.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md (caveman ultra).

遵循工作者技能工作流。只读应用代码。

步骤 3 — 业务逆向规格

技能： ns-harness-codebase-reverse-spec

目标： 创建或更新 {product_root}/docs/context/system-reverse-spec.md 和 system-reverse-spec.agent.md。

提示锚点：

Reverse-engineer {product_root} into a technology-agnostic system description.
Executive depth (default). Save human body to docs/context/system-reverse-spec.md
and agent-dense index to docs/context/system-reverse-spec.agent.md.
Both files MUST be English only (titles, labels, prose, rules) — never mix with conversation language.
Compress only the agent index before Write (agent-artifact-compress.md). Leave human body readable.
Autonomous run: use boot defaults for scope; English for reverse-spec; skip recon checkpoint unless a blocker.

遵循工作者技能工作流。输出仅限与技术无关的内容。

步骤 4 — AGENTS.md（最后执行）

技能： ns-harness-agents-md

目标： 刷新 {product_root}/AGENTS.md 并写入最简版 {product_root}/CLAUDE.md。

提示锚点：

Refresh AGENTS.md for {product_root} from installed skills and artifacts produced in this session.
Link to architecture-rules.md, brownfield-map.md, system-reverse-spec.md, and system-reverse-spec.agent.md — do not duplicate their bodies.
Preserve hand-edited sections unless recon proves them wrong.
Before Write: apply ../ns-harness/references/agent-artifact-compress.md — target ~95–110 lines.

最后运行此步骤，以确保链接指向步骤 1–3 生成的产物。

每步验证

继续下一步前，确认本步骤的输出文件存在且不是空壳：

步骤	文件	最低有效内容
1	architecture-rules.md	包含实际路径的技术栈、布局或约束
2	brownfield-map.md	已填写模块表；技术栈仅作指引（而非大段文字说明）
3	system-reverse-spec.md + .agent.md	面向人的正文包含实体/用例；Agent 索引包含实体/规则表
4	AGENTS.md	链接到 harness 规则和 docs/context/

如果某步骤只生成空壳或发生错误，立即停止——报告失败步骤及缺失内容。不要在上游产物为空时继续。

停止条件

条件	操作
{product_root} 下没有应用代码	停止——显示失败；没有可扫描的 greenfield
未安装工作者技能	停止——显示失败；建议使用 harness --preset spec-driven --yes 或 harness init
步骤输出缺失或仍是 harness 空壳	停止——继续前先修复该步骤
harness sync 失败	停止——报告错误
用户在链式运行中途停止	在当前步骤边界处停止

完成摘要

所有步骤成功后，报告：

1. 已写入或刷新的路径（四项输出 + sync）。
2. 建议的 git 提交消息：chore: harness prepare — rules, brownfield map, reverse spec (+ agent index), AGENTS.md
3. 下一步 SDD：准备好规划 1.0 版本时，执行 ns-sdd-clarify-requirements。

禁止事项

• 启动检查通过后，不要询问是否确认范围——直接显示摘要并继续。
• 不要调整步骤顺序（尤其不要在 constitution 和上下文产物之前运行 ns-harness-agents-md）。
• 架构规则生成后，不要跳过 harness sync。
• 完整 prepare 流程中，不要跳过 ns-harness-codebase-reverse-spec。
• 不要跳过 Agent 面向文件的保存前压缩（agent-artifact-compress.md）。
• 不要把面向人的逆向规格正文或 CLAUDE.md 改写成简陋版本。
• 不要直接编辑 .cursor/ 或 .claude/——只编辑规范源。
• prepare 期间不要修改应用源代码。

调用示例

/ns-harness-prepare

I just ran harness init on this brownfield repo. Run full prepare for {product_root}.

Prepare the project — architecture rules, brownfield map, reverse spec, and AGENTS.md in one go.

集成

阶段	技能
CLI 安装 + 脚手架搭建	npx @nextstage-brasil/harness init
检查前置条件	npx @nextstage-brasil/harness prepare
prepare 后进行 SDD 规划	ns-sdd-clarify-requirements → ns-sdd-requirements-generator