full-nfr

name

full-nfr

description

Use when the user says "非功能性设计", "NFR", "副作用分析", "风险评估", "non-functional design", "安全性分析", "性能分析", or has finished issues.md and needs to analyze side effects of the chosen solutions. Produces non-functional-design.md. Step 4 of 6. Not for issue decomposition/priorities (Step 3) or code architecture (Step 5). Not for writing code. Not for defining new features — only analyzing existing solutions' side effects.

核心目标

Step 3 的 issue 解决方案对系统有什么副作用？如何解决？

每个方案的架构/模块/模型改动都引入非功能性影响。本阶段系统识别并设计缓解，避免「功能能跑但系统不可靠」。

7 维度（详见 references/nfr-dimensions.md）：系统安全 / 业务数据安全 / 性能 / 并发控制 / 稳定性·高可用 / 兼容性 / 可观测性。

执行流程

按 ../full-shared/references/loop-skeleton.md（共享参考目录）的 6 步循环执行。（loop-method.md 的方法论仅 clarity 首次 read，本阶段无需 read。）

Step 1（交互+初稿）— Grilling 遍历副作用分析树：

[状态追踪] 开始时调 design_status start_phase nfr 标记阶段开始（会校验 issues 已 completed）。 有 design_status tool 优先用 tool：design_status(action: start_phase, phase: nfr)；无 tool（Claude Code/Cursor/shell）用 CLI：design-status start-phase nfr。CLI 完整用法见 loop-skeleton.md「CLI 完整用法」。

[按 loop-skeleton Step 1.0] grilling 前先获取已确认决策：

[复杂度档位] 先读 _progress.md 的 complexity_tier：L1 档跳过 context-builder（主 agent 直读 decisions.md + 必问决策点引用的上游章节）；L2/L3 派 context-builder。追踪/审查/重建帧的降级见 loop-skeleton「复杂度自评与降级档位·三档执行矩阵」。本阶段上游较多，派 context-builder subagent（fresh）读 {topic_dir}/decisions.md（本 topic 已确认决策）+ 相关长期文档（NFR.md/ADR/ARCHITECTURE.md）+ 上游 .md，输出「阶段工作摘要」（不可推翻决策清单 + 设计树入口 + 接口契约）注入主 agent context。grilling 不得重新确认已 confirmed 决策；每个 D 类决策拍板后按 Step 1.2 即时 append decisions.md。

副作用分析（根：每个 issue 的已决策方案）
├── Issue #1 → 方案 A
│   ├── 安全 / 数据 / 性能 / 并发 / 稳定性 / 兼容性 / 可观测性（每维度给推荐）
│   └── 不适用 → 写理由（防偷懒跳过）
├── Issue #3 → 方案 B（同 7 维度）
└── 残余风险 → 接受理由 + 监控方式

遍历纪律：一个 issue 的 7 维度走完再走下一个 issue（每方案副作用独立）。 不确定性高的副作用（并发死锁/缓存命中率）→ 标记为需⑤骨架验证，不纯靠脑力推演（见 references/nfr-dimensions.md）。 初稿用 references/deliverable-template.md。

Step 1 末尾 — 机器检查前置（零成本提速）： 初稿写完后，主 agent 调 cw(action=clarify) / cw(action=detail) 触发 CW gate 的机器检查，FAIL 当场修低级硬伤（缺章节/占位符/缓解项缺验收方式），不必等 Step 6。

Step 2（追踪）— 拆两部分：正向追踪 + 回灌指针重建器（反向覆盖）：

视角1（副作用覆盖性）+ 视角2（缓解可行性）是正向核查（像 ①⑤⑥，单 agent 串行够）。但视角3（回灌完整性）是反向覆盖问题——主 agent 声明「去 ③ 新 issue #7」时若漏建/写错编号，自己填表也查不出（同源自证），需 fresh context 他证。

① 正向追踪（按 issue 拆并行，每 issue 1 fresh subagent）： 7 维度认知帧不正交（并发族内重叠、性能↔稳定性重叠），按维度族拆会产重叠 gap + 丢跨族 gap；真正正交的拆轴是按 issue 拆（N issue = N 个不同代码面 = 认知帧天然正交，与③ issues 并行同款）。issue ≥ 3 时每 issue 派 1 fresh subagent，同 subagent 内跑视角1（副作用覆盖性：该方案 7 维度全评？不适用有理由？）+ 视角2（缓解可行性：缓解可落地？残余可接受？）；issue ≤ 2 时不划算，保持单 agent 串行。每个 subagent 显式接收：对应 issue 的方案摘要 + 7 维度模板 + 验收方式四选一规则。跨 issue 重复登记的缓解项由主 agent dedup（合并去重后回灌）。各 subagent 产出合并为 tracing-round-{N}.md。

正向追踪 subagent Task prompt（issue ≥ 3 时每 issue 派 1 个 fresh subagent）：

你是独立正向追踪 subagent。上下文与主 agent 隔离。只负责分配给你的 issue（{issue_id}: {方案摘要}）。
**决策账本纪律：** decisions.md（作为 context 参数注入）里 status=confirmed 的决策是用户已拍板结论，已 confirmed 决策不得当 gap 重报；有下游新证据推翻须标 `[REVISIT of D-NNN]` + 附新证据走 Step 6b 反哺（D-不可逆须主 agent ask_user）。
1. read 对应 issue 的方案摘要 + 7 维度模板（references/nfr-dimensions.md）+ 验收方式四选一规则
2. 视角1（副作用覆盖性）：该方案 7 维度全评？不适用有理由？
3. 视角2（缓解可行性）：缓解可落地？残余风险可接受？
4. 产出的 gap 标 F/K/D，写入合并到 tracing-round-{N}.md

② 回灌指针重建器（新增 1 fresh subagent，只做视角3，反向重建）：

时序约束（决定能查什么）： ④ 执行时③ issues.md 已存在、⑤ code-arch 尚未产出。

• ③ 指针（即时承诺，本重建器查）：④ 说「去 ③ 新 issue #N」→ 从 issues.md 反向核对 #N 真实存在
• ⑤ 指针（延期承诺，④ 查不了）：⑤ 还没写。但这条闭环已被 ⑤ 接住——⑤ code-arch §6「来源 B：NFR 风险→用例映射表」+ ⑤ Step2 反向核对每条 验收方式=代码测试 的缓解项有 ≥1 对应用例。④ 不重复查 ⑤，只对现在能查的 ③ 指针负责。

重建器机制： 读 issues.md（③，不先读 ④ 回灌表——避免被锚定）重建「issues.md 里有哪些 issue」，再读 ④ 回灌表，对每条「回灌去向=③issue」的行 diff。产出三态 gap：

• PHANTOM：④ 说「去 ③ 新 issue #7」但 issues.md 无 #7（漏建/写错编号）
• MISMATCH：④ 说「新 issue #7 是 P1」但 issues.md 里 #7 是 P2 / 标题不符（属性不一致）
• ORPHAN（反向）：issues.md 有 issue 声称来自 ④ 回灌，但 ④ 回灌表无对应登记（仅当 issues.md 有来源标注时查；当前 issue-template 无此字段则跳过）

重建器 Task prompt：

你是独立回灌指针重建 subagent。上下文与主 agent 隔离。
**决策账本纪律：** decisions.md（作为 context 参数注入）里 status=confirmed 的决策是用户已拍板结论，已 confirmed 决策不得当 gap 重报；有下游新证据推翻须标 `[REVISIT of D-NNN]` + 附新证据走 Step 6b 反哺（D-不可逆须主 agent ask_user）。
1. read issues.md（③，真相源）—— 重建「issues.md 里真实存在哪些 issue（编号+P级+标题）」
2. read non-functional-design.md 的「缓解项回灌登记」表
3. 对每条「回灌去向」含 ③issue 的行，核对指向的 #N 是否真实存在于 issues.md：
   PHANTOM（#N 不存在）/ MISMATCH（P级或标题不符）/ ORPHAN（issues.md 有来源标注但④无登记，若有）
4. ⑤ 指针不查（⑤尚未产出，闭环由⑤来源B接住）
5. 每条 gap 标类型（F/K/D）。写入 {topic_dir}/changes/tracing-round-{N}-backfeed.md

机器化降级空间：CW gate 的机器检查已覆盖「回灌③指针 PHANTOM」「验收方式列合法」「无不可接受项」——即回灌重建器视角3 的机器可判子集，这些由 CW gate 在 cw(action=clarify) / cw(action=detail) 调用时自动完成，不占 subagent 预算。subagent 只做机器做不了的：副作用的语义风险评估（缓解方案是否真消除风险）与回灌重建器视角3 之外的盲区。机器检查未覆盖前维持回灌重建器 subagent。

Step 3-4 — gap 分流(F/K/D) → 收敛复核。 按 loop-skeleton.md。

Step 5（定稿+HTML）— 按 references/deliverable-template.md 定稿 non-functional-design.md；派 fresh subagent 渲染 non-functional-design.html（机制见 loop-skeleton.md Step 5b）（主角图：风险矩阵热力图 issue×7维度 ✅⚠️❌着色）。

Step 6（审查）— 派 fresh-context 审查 subagent（按 ../full-shared/references/review-agent.md 规范，CW gate 的机器检查 FAIL 硬阻断），6 维评审（含红队维度），报告写 changes/review-nfr.md（frontmatter 含 verdict + machine_check）。APPROVED 后进 Step 6b 反哺检查（回扫 ①②③上游），再交接。

Phase Loop 机制

• 收敛失败 → 回 Step 3 补充分析
• 副作用无法缓解 → 回 Step 3 重新选方案（D 类 issue 可能改答案）
• 审查 CHANGES_REQUESTED → 审查意见当 gap 回 Step 3
• 反哺触发上游修订（详见 loop-skeleton.md Step 6b）→ 上游 .md 更新后，本阶段可能需重新对齐 → 回 Step 2 重追踪
• Stagnation（连续 3 轮 gap 不降）→ 强制收敛

Self-Check

[MANDATORY] 禁止在未完成 loop-skeleton 全流程（含 Step 6 审查 APPROVED）时声称完成。

• non-functional-design.md 存在，frontmatter 含 verdict: pass
• decisions.md 已读（Step 1.0）+ 本阶段 D 类决策（取舍原则例外/残余风险接受）已即时 append
• changes/backfeed-round-{{N}}.md 存在（Step 6b 反哺检查真执行了；entries=0 也算，只要文件产出）
• non-functional-design.html 存在，风险矩阵热力图正确渲染（✅⚠️❌着色）
• changes/tracing-round-{N}.md 存在（正向追踪）
• changes/tracing-round-{N}-backfeed.md 存在（回灌指针重建，含 PHANTOM/MISMATCH diff）
• changes/review-nfr.md 存在且 verdict: APPROVED
• issues.md 的每已决策方案评估了 7 维度（不适用有理由）
• 标注的风险都有缓解方案或显式列为残余风险（接受理由）
• 无 ❌（不可接受）项——如有则已回 Step 3 重新选方案
• 不确定性高的副作用标记为需⑤骨架验证（有验证要点记录）
• 缓解项回灌登记表存在，每条缓解有明确去向（⑤章节 / ③新issue / 运维项）
• 每条缓解标了验收方式（代码测试/骨架约束/性能混沌/运维项四选一）；代码测试类附 NFR-AC（归属 UC + 断言摘要），性能混沌类指向⑥独立 perf/chaos Wave
• 回灌到 ③的新 issue 已在 issues.md 中出现（双向可查）

本地目录覆盖规则

• 主目录： .xyz-harness/（项目根）
• 子目录： ${yyyy-MM-dd}-${主题简短标题}
• 路径： .xyz-harness/${主题}/non-functional-design.md + .html
• 不同主题不同子目录，禁止混放。 单次写入超 1000 字优先拆分子文档。

下游衔接

perf/chaos 类缓解路由（不进⑤）： 验收方式=性能混沌 的缓解项不进⑤ code-arch（⑤来源B 只接单测/集成测），路由到⑥ execution-plan 的独立 perf/chaos Wave 或 pre-prod gate。⑤⑥文件不在本阶段改动范围，此处仅声明路由契约。

审查 APPROVED 后向用户交接（按 loop-skeleton.md Step 6 格式）：

[状态追踪] 交接前调 design_status complete_phase nfr 收尾——自动校验 non-functional-design.md + verdict:pass + review APPROVED，过了才标 completed。 有 tool 优先用 tool：design_status(action: complete_phase, phase: nfr)；无 tool 用 CLI：design-status complete-phase nfr。

✅ ④非功能性设计 已完成并通过独立审查。
   产出：non-functional-design.md + non-functional-design.html
   审查报告：changes/review-nfr.md（verdict: APPROVED）
下一步：⑤代码架构设计 — 工程目录/契约/包管理/类方法时序图
调用：/full-code-arch
是否现在进入下一步？

用户确认后才加载下一 skill。

标记说明

标记	含义	修改约束
[MANDATORY]	流程强制要求	必须严格遵守