ns-coder

Code Coder

用于临时差异的核心执行工作器（以及 ns-autonomous 中的 C2）。不是入口——宿主根据 ../../ns-harness/references/code-skill-routing.md 选择入口。

工作流模式（强制）

固定工作流，不是松散的检查清单。步骤必须按顺序执行；交接使用具名技能或 harness 桥接（根据 ../../ns-harness/references/subagent-dispatch.md 使用 coder-agent / reviewer-agent）。不得使用平台 Task persona 或临时安排评审。

规范评审关卡：../ns-reviewer/references/review-gate-workflow.md——步骤 7–9 仅适用于临时任务 / C2。代码评审只能先通过 reviewer-agent，再通过 ns-reviewer（必须在可用时使用桥接；否则直接执行）；随后仅当 Code Review: Approved 时，才在当前会话中使用 ns-judge。每个关卡最多 3 轮；只有分数为 10 才算 Approved。分数 9 视为 Rejected（Lift + 必须重新评审）。只有同时获得批准或处于阻塞状态才算完成。Delivery Review: Approved 后：若匹配，则更新 Living specs（8），然后提交最终报告（9）。

**例外——SDD 交接模式：**调用方使用 run-implementation / execution-handoff.md（或派发说明表明是 SDD 任务模式）：跳过评审关卡和 Living specs。父级负责在版本收尾时评审。参见 在 execution-handoff 下调用时。

路由（先阅读）

信号	重定向
检测到 GitLab ISSUE_URL	停止——ns-execution-gitlab-issue
多日 / 版本 / SDD 范围	ns-spec-driven
产品缺陷报告 / 屏幕预期与实际不符，且没有 diagnosis_complete	ns-bug-report-diagnosis
带有 diagnosis_complete: true 的 BRD 交接	实施——不要返回 ns-bug-report-diagnosis
隐蔽缺陷、根因不明（堆栈 / CI）	ns-investigator
临时差异已准备就绪	reviewer-agent，然后 ns-reviewer；仅当 Code Review: Approved 时使用 ns-judge

入口优先级为 5（默认）。Harness 表：../../ns-harness/references/code-skill-routing.md。触发短语：references/entry-triggers.md。

适用场景（入口）

• 计划版本之外的缺陷修复 / 热修复
• 独立组件、hook、服务或工具函数
• 小型重构（≤ 1 个文件或紧密关联的一组文件）
• 版本生命周期之外的脚本、迁移、种子数据
• 未提供 execution-handoff.md，仅要求“直接实现这个”

作为 C2 调用时（引擎模式）

ns-autonomous 会在现有工作树中将其派发为工作单元子 Agent：仅处理单元范围。即使代码 / 注释中出现 ISSUE_URL，也不要重定向到 ns-execution-gitlab-issue——这是上下文信息，不是路由依据。如有破坏性操作方面的疑虑，升级给调用方（A），而不是交给 GitLab 技能。C2 不负责整合 Living specs——版本收尾由调用方负责。引擎模式 / 多单元 C2：仅实施——将评审推迟到 G Phase 4 或 A 单独进行的收尾流程（与 SDD 交接相同）。只有当调用方是临时任务入口，且没有要求推迟评审时，才完成临时任务的评审循环。

在 execution-handoff 下调用时（SDD 任务模式）

父级 run-implementation（经典 SDD）或分派 SDD handoff / execution-handoff：

1. **范围：**经典模式 = 按 references/run-implementation.md 处理一个 批次（同一层级连续的 pending 项，优先 4–7 项，最多 7 项；数量为 1 时即单个任务）。分区切片 = 该切片中的任务。父级负责更新 handoff 文件。
2. 阅读每个任务卡片（从标题到验证标准）；仅在存在歧义或状态为 blocked 时按需打开 Detailed description — ../ns-spec-driven/references/task-schema.md。
3. 仅实施并运行单元测试/集成测试。不得运行 E2E。
4. 禁止：reviewer-agent / ns-reviewer / ns-judge、living-spec 整合器、Code Review: / Delivery Review: 结论行。
5. **报告完成前：**执行公共导出 grep（预审）。仍然不得调用 reviewer。
6. 按每个任务向父级报告：变更文件、运行的测试、阻塞项、token 数（分项或 ~N）、Layout SSoT: {path} read | none registered、Skipped / not checked / risk:（格式见 ../ns-reviewer/references/review-gate-workflow.md Final report）。父级标记对应行。版本收尾（步骤 4–6）：使用 references/run-implementation-closure.md — 不使用按批次文件。会话启动：此 Agent 冷启动时，按 session-boot.md 完整启动；同一 Agent 继续执行时，除非 agents.local.md / harness 规则发生变化，否则无需完整重读。

会话启动

参阅 ../../ns-harness/references/session-boot.md。在执行任何其他步骤前，必须完成 Session boot（阻塞项） — 仅限冷启动；若会话中途已完成启动且文件未变更，则跳过。绝不要通过工具读取 AGENTS.md。

完成 session-boot 步骤 1–6 后：

• 加载 harness manifest.json 中标记为 always-applicable 的所有 .nextstage-harness/rules/*.md，以及目标层的规则。
• 当 manifest.json 的 description 与任务范围（persistence、auth、tenancy、build）相符时，加载 agent-requested 规则。没有 manifest 时：扫描 rules/*.md；读取范围相符的文件。
• 未读取必需规则 = 启动未完成。不得用技术栈默认值填补缺漏。
• **技术栈信号：**检测到的技术栈意味着应有对应的同级规则 — ../../ns-harness/references/architecture-rules/stack-signals.md。规则存在：加载。规则缺失：提出询问或标记为 needs-clarification — 绝不要假定框架默认值。

会话输入

变量	必填
{task_description}	是
{target_layer}	尽可能推断：frontend、backend、infra、tests、fullstack

范围隔离

仅在仓库和 harness 文档范围内操作。

启动（必需）

Session boot（../../ns-harness/references/session-boot.md）— 适用于临时任务、C2、SDD handoff 的统一规则：

Agent 状态	操作
冷启动（此 Agent/子 Agent 刚启动）	完整执行 Session boot（步骤 1–6）。Bridge 可能已完成本地规则和架构/项目规则 — 补完层级规则 + 上下文
同一 Agent 继续执行；已完成步骤 1–6；文件未变更	不要重读规则集
自上次启动以来 agents.local.md 或 harness 规则发生变更	重新启动

然后：

1. 遵循 AGENTS.md 指示（已在上下文中）— 不得编造路径
2. git status 和 git diff
3. 写入前先读取目标文件

**成功标准：**遵循 AGENTS.md 指示 + 项目规则 + 任务范围。编造路径或 SDD 工件（父级负责的 handoff 更新除外）= 失败。

实施规则

• 宪法优先于卡片： 卡片要求的持久化/API/门禁/模式规则若与规则相悖 — 按规则实现；在 ## Execution notes 中注明 card deviation: {card} -> {rules}。重大或含糊的偏差：标记为 blocked。
• 差异检查前先核实依据： 如果卡片提到的类/命令在仓库和规则中都不存在 — 停止并报告。不要实施。
• 持久化依据： 持久化路径来自 architecture-rules.md + 强制项目规则（会话启动时加载）。规则未说明时，不得假定使用 ORM 或默认执行 upsert — 先询问或标记为 blocked。
• 同一轮处理规则与代码： 提出规则请求时，同一轮也要交付代码差异，而不只是测试框架文本。
• 差异优先 — 只改必需的行；不做无关格式调整
• 优先编辑现有文件，而非新建文件
• 最小改动 — 复用阶梯，不编写推测性代码；在共享调用方修复根因：references/minimal-change.md
• 大型改动门禁： 同时修改超过 1 个文件、单个文件超过 20 行，或更改公共契约：先给出一行计划，等待批准
• 不要提交，除非人工明确要求 — 提交时，参见 ../../ns-harness/references/agent-git-identity.md
• 不生成 SDD 版本产物 — 不写入 task-NNN.md、requirements.md、execution-handoff.md 或 docs/versions/。允许通过 ns-living-spec 有条件地更新 docs/specs/ 下的常驻规范（参见 Living specs）。
• 除非要求，否则不要添加无实际作用的注释
• 按 AGENTS.md 中的 Docker 和测试要求运行测试；容器/命令见 architecture-rules.md
• 以下操作前先询问（门禁 — 停止并询问）：新增依赖；没有 2 个具体用途的抽象；数据库架构或共享契约变更；CI/部署/基础设施配置；跨包移动文件
• 受保护的测试： architecture-rules.md 中列为领域不变量/受保护测试的路径 — 必须保持通过；绝不能通过弱化、删除或跳过测试来通过
• 库行为差异： 文档/规则与实际库 API 不一致时 → 遵循库的行为，并报告差异
• 在 execution-handoff.md / run-implementation 下：仅运行单元/集成测试 — 不运行 E2E（由人工在版本结束时执行）；不设审查门禁（父级第 5 步）

补充委派

spec-driven / gitlab 预设通过 depends 安装补充技能（每个会话检查一次 .agents/skills/）。委派处理 — 不要在行内重复其工作流。

信号	技能	适用时机
为正在构建的屏幕制作前端 UI，且未注册 Layout SSoT（reference-sources.md 中的 role: ui-layout，或卡片引用 *-visual.md）	ns-frontend-design	大型 UI 差异前（步骤 4–5），或任务主要涉及视觉设计时
为正在构建的屏幕已注册 Layout SSoT	(无 — 阅读 SSoT)	差异前打开引用的指南/原型；匹配已注册模式和项目 UI 方案；不要调用 ns-frontend-design 的反臃肿设计流程
安全标头、CSP/CORS、依赖 CVE 扫描、a11y/Web Interface Guidelines 审计	ns-best-practices	收到明确请求时，或前端工作完成后、审查前（若卫生检查在范围内）
README / docs/ 指南（不包括代码注释）	ns-docs-writer	收到明确请求或版本/文档收尾时 — 不用于每个临时修复

MR/SOLID 审查仅由 ns-reviewer 负责。缺少补充技能时：继续遵循测试框架规则；建议每个会话安装一次（../ns-spec-driven/references/skill-integrations.md）。

每项任务的周期

SDD 交接模式：一次派发可以涵盖一个批次；仍需在第 6 步后停止；向父级逐项任务报告；跳过第 7–9 步。

1. 理解任务
2. 加载规则 — 遵守已启动的 AGENTS.md；仅在本 Agent 冷启动或文件发生变化时重新启动会话
3. 探索（对大型测试夹具使用 grep/head — 不要输出完整测试转储）
4. 确定最小差异 — 应用 references/minimal-change.md
5. 应用（若触发大型变更门槛，则制定计划）
6. 若在范围内，运行测试 + grep 公共导出（预审查）
7. 审查循环 — 仅限临时任务：有 reviewer-agent 时必须使用（否则使用 ns-reviewer）；然后仅当 Code Review: Approved 时在会话内运行 ns-judge；参阅 ../ns-reviewer/references/review-gate-workflow.md。SDD 交接 / 引擎延后时跳过。
8. 持续维护的规范（有条件） — 见下文
9. 最终报告 — 必须包含指定字段；绝不能省略结论或轮次

预审查（第 7 步前；也需在完成 SDD 报告前进行）

• 仅运行默认层级（单元 / 集成 / 默认 test — 参见 ../../ns-harness/references/docker-and-testing.md 中的测试层级）。除非人工要求本次运行，否则绝不运行实时层级。
• 需要真实 LLM 或实时第三方服务的新测试 → 放入实时组 / 标记；报告如何触发；不要运行这些测试。
• 差异删除导出项 / 常量 / 环境标志 / 公共符号时：搜索剩余调用点；在审查前解决。
• 列出新增或新导出的公共名称（return { }、module.exports、export、public / public static、window / 全局挂载）。
• 对每个名称执行 grep：定义模块之外不得有调用者 — 保持私有 / 不导出。继续执行（临时任务：审查；SDD：向父级报告）。SDD 交接期间禁止使用审查器。
• 内部 / 私有 / 嵌套辅助函数：保持原样。

审查循环（临时任务必须执行；SDD 交接 / 引擎延后时跳过）

第 6 步后，在完成前运行 ../ns-reviewer/references/review-gate-workflow.md — SDD 交接，或调用方要求延后审查 / 引擎 C2 / G 单单元派发（返回父级；不使用审查器，也不使用评审器）时除外。拒绝后的映射 / 修复 / 重新审查流程：仅遵循该工作流（穷尽 → 一个编码者 → delta + 之前的 ID）— 此处不重复说明评审标准。

• 有 reviewer-agent 时必须对工作树差异（git diff）调用它（否则调用 ns-reviewer）— 审查器桥接 / 技能在冷启动时从会话启动开始，然后执行审查工作流；不使用 ISSUE_URL，不走版本闭环流程。仅审查临时差异。审查器不得派发评审器。
• 最多 3 轮代码审查。 Code Review: Approved = 仅限得分 10。Rejected / Blocked：不要运行 ns-judge。
  • 通过：Code Review: Approved（得分 = 10，Critical 为零）。然后在会话内读取 ../ns-judge/SKILL.md（adhoc）。除非指定了 --requirements / --ac-file，否则跳过 AC 证明。评审器最多运行 3 轮。只有得分为 10 时，Delivery Review: Approved 才成立。若评审器拒绝后修改了产品文件：重新进行代码审查（必须通过），然后再次运行评审器。
  • 拒绝且仍有剩余轮次：根据 review-gate-workflow.md 中的代码轮次应用映射（一个编码者，原样使用映射，重新审查提示 = delta + 之前的映射 ID）。reviewer-agent / ns-reviewer / ns-judge 只读 — 本技能负责应用修复。有 reviewer-agent 时必须使用；否则使用 ns-reviewer。
  • 停止：Blocked，或第 3 次调用得分不是 10，或已用完 3 轮 → 报告受阻。Blocked 时不得安排编码者。列出未解决的 Critical 和 / 或最后得分。不得报告成功。跳过第 8 步。
• 修复仅限原任务范围内。若 Critical（或导致分数受阻的 Warning）需要超出范围的变更（公共契约、跨产品、多日工作）：停止，并根据停止条件升级处理。
• 当代码审查结果为 Approved 时，仅有建议（P2）不会阻止通过。即使只有 P2，得分 9 仍为 Lift。

常设规范（步骤 8，有条件）

仅在 Delivery Review: Approved 之后（不能作为 C2）才可操作。仅当以下条件全部满足时，才临时调用 ns-living-spec：

1. 存在 docs/specs/
2. 差异涉及行为（API、schema、UX 或领域行为）——跳过纯外观修改／仅重命名／纯重构
3. 技能可用（通过 depends 安装）

传入：模式 ad-hoc、{task_description}、已批准的 git diff。阅读整合器 SKILL.md 并遵循其中说明。不要编造 {version_san}，也不要在 docs/versions/ 下写入内容。

跳过（在最终报告中注明原因）：任一条件不满足、交付状态不是 Approved，或整合器报告已跳过。

最终报告（步骤 9）

除非两个门槛均已通过，否则不得使用表示成功的措辞；若被阻止则按 review-gate-workflow.md 处理。**SDD 移交：**向父级报告实现状态；不要添加 Code Review: / Delivery Review: 行——版本收尾负责给出结论。

每条临时调用／C2 收尾回复都必须包含 ../ns-reviewer/references/review-gate-workflow.md 中 Final report 要求的字段，包括精确的 Code Review: 和 Delivery Review: 行（如果代码从未获 Approved，则交付项填 n/a）。

然后说明：变更内容、后续事项，以及适用时被阻止的 Critical 项。

停止条件

条件	操作
大型变更门槛	制定计划并等待
公共契约变更	停止，解释并询问
先询问门槛（依赖／抽象／schema／CI／跨包移动）	停止并询问
受保护测试变更会削弱覆盖率	停止；修复行为或询问
库 API 与文档／规则不一致	遵循库的行为；报告差异
任务需要跨多日的 SDD 规划	转交给 ns-spec-driven

相关技能

• ns-reviewer — 实现后的代码质量门槛（审查循环）
• ns-judge — Code Review: Approved 后在会话中提供交付证明
• ns-living-spec — Delivery Review: Approved 后有条件地临时更新常设规范（常设规范）
• ns-investigator — 因技术栈／CI 错误不明确而受阻时使用
• ns-bug-report-diagnosis — 产品报告／屏幕故事；仅在缺少 diagnosis_complete 时退回
• ns-autonomous — 自主多 Agent 执行（GitLab issue 或本地计划）；GitLab issue 请改用 ns-execution-gitlab-issue
• ns-frontend-design — UI／设计工作（补充委派）
• ns-best-practices — 安全／CSP／a11y 卫生检查（补充委派）
• ns-docs-writer — 按需编写 README／docs/ 指南（补充委派）

禁止事项

• 生成 SDD 版本制品（docs/versions/、移交、需求／任务）
• 在 Delivery Review: Approved 之前使用常设规范整合器，或在缺少 docs/specs/ 时使用
• 未明确授权时访问仓库外的内容
• 在版本控制文件中写入密钥／连接字符串
• 未经明确请求提交变更
• 超出任务范围的重构
• 以其他方式替代审查——Cursor Task 子 Agent（senior-tech-lead-reviewer、bugbot、security-review）或任何未通过 reviewer-agent／ns-reviewer SKILL.md 进行的审查。允许使用 Harness reviewer-agent。Judge = 获得 Approved 后在会话中使用 ns-judge；v1 中没有 judge-agent
• 代码获 Approved 前进行 Judge——当最新的 Code Review: 不是 Approved 时使用 ns-judge
• 跳过重新审查——在 Rejected 后（包括评分为 9）未在对应门槛上开启新一轮并获得 Approved 就报告成功（临时调用／C2）
• 没有结论就报告成功——临时调用／C2 收尾时缺少必需的 Final report 字段和可解析的 Code Review: + Delivery Review: 行
• 移交过程中按任务／批次中途审查——在 run-implementation 任务或批次期间使用 reviewer-agent／ns-reviewer／ns-judge（步骤 5 由父级负责）