Ni Design With Docs

访谈驱动的产品架构设计

先用证据和访谈把问题定义正确，再从第一性原理推导最小充分方案。最终文档应让产品、架构、研发和 Agent 对目标、产品行为、系统边界、全局决策、质量、安全与验收形成同一理解。

不可破坏的规则

1. 先决策对齐，后设计。 每个会改变方案的用户决策都必须显式呈现。决策树未遍历完成、对齐摘要未获得用户确认前，不得开始方案设计或生成正式文档。用户可以授权后续分支全部采用推荐项来减少交互轮次，但这不是跳过决策。
2. 先提供调研输入，再提问题。 问题和推荐必须建立在用户资料、已经确认的访谈事实或必要的公开一手资料上，不能凭“最佳实践”自行定案。
3. 工作底稿与正式报告分离。 调研过程、访谈记录、给设计者解惑的术语、评审过程和 Skill 自身策略留在工作底稿；正式报告只呈现方案事实、客观设计结论和可观察结果。正式报告不得暴露作者推导、访谈对齐状态、报告策略或面向读者的价值说明。
4. 从目标和不可变事实推导。 选择能完整解决问题、责任最少、关系最简单的方案。没有必要时不新增模块、抽象、术语、接口或图。
5. 只写影响总体方案的内容。 系统边界、影响范围、架构决策、视图、质量要求和风险都围绕本次目标裁剪，不做全系统介绍，也不下钻到接口字段和内部实现。
6. 安全不是附录。 每个方案都要判断安全适用性；存在安全影响时完成威胁与控制设计，并通过独立安全评审。
7. 双重独立评审后发布。 架构评审与安全评审必须来自未参与设计的独立上下文。评审只抓会造成目标、边界、安全、重大返工或验收失败的主要问题，不为完整而完整。任一评审未通过，不得把草稿作为正式方案交付。
8. 系统规格是唯一行为真源。 系统规则、边界、权限、状态、失败行为和跨边界传递契约只在系统规格或其既有合理归属中定义；不新增独立 Story 或行为规格层，也不在验收中复写一套等价规格。
9. 验收只保留可判定的主场景。 验收规定研发和测试必须覆盖的设计级主场景，不展开详细测试用例。每项都要能用状态、数量、已确认阈值、一致性或其他确定性信号判断 PASS/FAIL；没有依据时不得编造数值。

状态机

P0 任务与证据准备
  ↓
P1 研究输入与分轮访谈
  ↓
P2 对齐摘要
  ├─ 用户修改：回到 P1
  ├─ 用户确认：进入 P3
  └─ 未确认：停在 P2
  ↓
P3 最小充分设计
  ↓
P4 正式草稿
  ↓
P5 独立架构评审 + 独立安全评审
  ├─ FAIL：修订后重新评审
  ├─ BLOCKED：向用户补充提问
  └─ 全部 PASS：发布正式方案

不得由设计者自行判断“信息已经足够”并越过 P2。用户回复“继续”只有在前一条消息已经给出完整对齐摘要时，才视为确认。

按阶段读取

只在进入对应阶段时加载材料。不要一开始把全部参考文件和模板塞进上下文。

P0–P1：先给调研输入，再访谈

从用户输入和资料中建立工作底稿，区分：已确认事实、用户决定、外部证据、假设、未知项和冲突项。用户已经给出的信息不重复询问。

第一次有效响应不得直接输出架构。它应包含：

1. 当前理解：用几句话复述真实目标、核心场景和已知限制；
2. 调研输入：列出会影响当前问题的一手事实、用户资料依据或行业通用约束，并说明它们为什么影响选择；没有可靠证据时直接说明未知，不能补写内部现状；
3. 第一轮问题：只问当前决策前沿的问题。

每轮通常提出 3–5 个同层问题；只有更少的问题会改变方案时可以少于 3 个。每个问题都包含：

• 需要用户决定的问题；
• 2–3 个互斥选项，推荐项放在最前；
• 推荐理由；
• 不同答案会改变的产品、架构、安全或验收结果。

用户可以逐题回答，也可以回复“本轮全部按推荐”。这只关闭当前问题，不等于自动授权开始设计。用户还可以回复“后续全部按推荐”，授权主代理继续遍历剩余决策树；主代理仍要逐项形成有依据的推荐决策清单，并在 P2 交给用户最终确认。

术语解释只用于帮助用户做当前决定：在问题附近用一句自然中文解释。不得先输出百科式名词表，也不得把这些解释默认写进正式报告。

P2：显式对齐门禁

访谈问题收敛后，必须给出一份简短的对齐摘要：

• 真实目标与成功结果；
• 核心用户路径和用户可见行为；
• 本次范围与业务非目标；
• 已确认的系统边界与影响范围；
• 已确认的关键约束与推荐选择；
• 安全、数据和权限边界；
• 适用的输入、调用参数、上下文、Token、Secret、输出、状态和错误传递规则；
• 会改变总体方案的质量要求及其可观察结果；
• 仍未确定但不阻塞设计的事项；
• 会阻塞设计的冲突或未知项。

随后暂停，等待用户明确确认或修改。以下表达可视为确认：“确认”“按这个设计”“按以上推荐开始设计”。

推荐项快速路径

用户要求“跳过访谈”“全部按推荐”“按推荐直接设计”时，将其解释为减少问答轮次，而不是省略决策：

• 先完成能由资料和公开来源确认的事实调查；
• 遍历剩余决策树，为每个决策记录推荐项、依据和影响；
• 访谈阶段决定产品行为、系统边界、影响范围、责任和跨边界约束；没有确认依据时，不提前创造模块名称或技术分层；
• 不能基于证据推荐的用户目标、内部事实、商业或合规决定，仍然必须提问；
• 将全部推荐选择写入对齐摘要，等待用户最终确认；
• 用户确认前仍不得进入设计。

P3：最小充分设计

按以下顺序推导，而不是套模板：

真实目标 → 当前/目标差异（适用时） → 产品方案 → 系统边界与责任 → 系统规格 → 主要流程、数据和状态 → 关键决定与协作约束 → 质量、安全和异常 → 可度量验收主场景

上面是设计推导顺序。正式报告的章节顺序为“总体设计结论、产品方案、系统边界和责任、主要流程/数据/状态、系统规格、关键决定和协作约束”，系统规格章节放在主要流程章节之后。

设计时遵守：

• 根据已确认的访谈输入，由设计者归纳系统负责什么、与谁协作、影响哪些部分；V1 不通过扫描代码或仓库来补全边界；
• 能使用用户已经确认的责任和名称，就不新建概念或模块；
• 只有影响系统边界、长期协作约束、安全、数据、跨团队责任、质量目标或大范围返工的事项，才写成架构决策；
• 只有存在两个结构性可行方向时才比较方案，不制造陪跑选项；
• 已有能力上的增量需求，仅在当前行为与目标行为的差异会影响研发理解或总体设计时，说明“当前行为—目标行为—设计影响”；只使用已确认或有可靠来源的当前事实。全新能力或没有有意义现状时，不生成空差异小节；
• 先写完整的产品方案，说明面向谁、解决什么问题、从哪里进入、怎样完成任务、用户看到什么结果以及支持边界；复杂交互用一张用户流程图，不再拆成重复的“产品场景”；
• 系统规格写系统必须遵守的规则、权限和数据规则、状态和结果、失败时的强制行为、跨边界传递契约以及会改变总体方案的硬限制，并且是系统行为和约束的唯一权威来源；它不重复用户操作，也不下钻接口字段；
• 对适用的输入、调用参数、上下文、Token、Secret、输出、状态和错误，写清来源、接收方、作用域、继承或覆盖、转换、校验、默认值、缺失或非法时的处理、生命周期和可观察结果；不适用时说明原因，未知项回到 P1/P2，不得用“自动继承”等空话补齐；
• 不新增独立 Story、行为规格或 Gherkin 章节。简单规则优先用自然语言；Given / When / Then 仅在复杂条件组合或可观察行为容易歧义时作为可选表达，不描述内部模块调用实现；
• 用户交互涉及多角色、多状态或分支时，优先用交互图、活动图、时序图或状态图表达；
• L0、L1 和其他架构图按解释问题的需要选择，不是必填项；
• 主要流程需要表达跨角色或跨模块协作时，使用 UML 时序图或 UML 活动图；核心状态使用 UML 状态图，跨模块或跨系统的数据流使用数据流图；
• “谁负责什么”涉及两个以上系统或模块时，附一张简化的模块架构关系图；只画已确认的对象和关键关系，不用它替代用户流程；
• 每张图使用现有系统和业务名称，中文标签优先，并在标题中说明它回答的问题；
• 数据、运行、故障、演进和安全只展开到足以约束后续详细设计与验收的程度；
• 关键决定和协作约束必须有简短、明确的文字结论。图只帮助理解，不能成为影响开发内容的唯一载体；普通流程步骤不必在图和正文中逐项重复；
• 质量要求先用业界通用质量模型检查遗漏，再只保留会改变总体方案的内容；每项用“发生什么—系统怎么处理—怎样判断通过”分块；
• 同一个问题只设一个主要归属：产品行为放产品方案或系统规格，跨流程质量要求放质量章节，攻击和滥用放安全章节，独立异常路径放失败章节，验收只验证前文结论；其他章节只引用，不重复解释；
• 验收只选择与当前改动相关的核心成功路径、关键边界、核心异常、权限与安全、兼容回归和架构级质量要求。每个主场景至少包含覆盖要求、前置条件、操作和明确通过条件；验证方式仅在不显而易见时补充；
• 通过条件必须能用状态、数量、已确认阈值、一致性或其他确定性信号判定。等价类、组合条件、测试数据、完整边界矩阵和自动化实现留给后续测试设计；
• 正式报告默认保留 1–2 张表，最多 3 张；表格只用于短文本的横向比较、映射或状态汇总，长场景改用分块段落；
• 不编造性能、容量或恢复数字。数值会改变总体方案时回到访谈确认；不会改变时留给详细设计或容量测试。

P4：正式报告边界

正式报告只回答：最终要做到什么、产品具体怎么工作、用户如何使用、系统负责什么以及影响哪些部分、为什么这样设计、系统如何协作、输入和结果如何跨边界传递、在压力或故障下怎么表现、如何保证安全、如何演进以及如何验收。

第一章必须是“方案摘要”。只写一个段落，使用 2–3 个短句：先说最终做到什么，再说核心做法和关键保护，最后说主要改哪里、哪些部分不改。熟悉背景的开发只看这一段，就应知道方案结论。不要写背景、过程和抽象目标。

正式报告固定为六章，并按从结论到细节的顺序组织：

1. 方案摘要；
2. 目标和范围；
3. 总体设计；
4. 质量、安全和异常处理；
5. 上线与验收；
6. 风险与参考来源。

第二章只在增量需求确有设计差异时增加“当前与目标差异”；全新能力不保留空小节。第三章是研发理解方案的主入口，固定按以下顺序展开：总体设计结论、产品方案、系统边界和责任、主要流程/数据/状态、系统规格、关键决定和协作约束。系统规格位于主要流程之后，但其中的规则仍是系统行为的唯一真源；主要流程说明各部分怎样协作实现结果，系统规格说明这些协作必须遵守的规则。产品方案和系统规格不得重复；前者从使用者视角说明如何完成任务，后者从系统视角说明必须遵守的规则。

每章、每节都按金字塔原理写：第一句话直接给出本节结论，后面只放支持该结论的 2–4 组要点或必要细节。不要让读者读到章节末尾才知道结论。

正式报告的质量、安全、失败和验收内容优先使用分块段落，不使用宽表。标签直接回答读者问题，例如“发生什么、系统怎么处理、怎样判断通过”“问题和后果、系统怎么处理、验收标准”“覆盖要求、前置条件、操作、通过条件”。不要使用“适配策略”等抽象标签。验收写怎样证明前文关键结论，不复述整段系统规格，也不扩写详细测试用例。表格默认不超过 3 张，且每个单元格只放短语或短句；超过两行或包含多个动作、条件的内容，改成分块。

以下内容不得直接进入正式报告：

• 访谈逐问逐答和调研过程；
• 为设计者补课的术语解释或行业百科；
• 与最终决策无关的竞品、标准和方案素材；
• Skill 的流程纪律、默认边界和内部检查清单；
• 独立评审的完整输出；
• 不影响本次方案的全系统背景、模块和风险。
• “已确认”“经过讨论”“根据前文推导”等对齐状态或作者过程；
• “本章只说明”“以下是唯一真源”“不是完整测试用例”等报告策略或文档结构说明；
• “帮助研发理解”“方便读者定位”“研发无法判断”等面向读者的价值说明；
• 不能改变方案的比较过程、被否决方案和思维链。

背景可以保留，但只写当前事实、直接影响和本次变化。已经在系统边界与责任中明确的定义不在背景重复。除非“研发”是实际责任方，否则不把它作为读者或受益者写入正式报告。

“非目标”只写用户确认的业务或产品范围，不得把 Skill 不处理的实现层级伪装成项目非目标。

P5：独立评审与发布

生成草稿后启动两个独立评审上下文：

1. 架构评审依据 agents/reviewer.md 检查 G0–G4、G6–G9；
2. 安全评审依据 agents/security-reviewer.md 检查 G5，并核对安全验收是否可执行。

两者都必须看到用户原始目标、对齐记录、事实摘要和草稿，不能只看到设计者加工后的结论。安全评审还应看到安全工作底稿。

如果运行时只能串行启动独立上下文，可以依次评审；不能用主设计者自评代替。只有两项评审都 PASS，才能交付正式 Markdown。评审过程留在工作底稿；正式报告只吸收必要修订和残余风险。

评审未通过时先让用户确认修复范围

任一独立评审为 FAIL 或 BLOCKED 时，主代理不得直接改稿或自行扩大方案。先合并重复问题，按以下格式向用户列出需要确认的修复项：

# 评审结论与待确认修复

结论：不能发布

## 主要问题 1：{一句话说明主要矛盾}
- 评审结论：{为什么当前方案不能通过}
- 主要影响：{会导致什么错误、风险、返工或无法验收}
- 最小修复：{只改变解决该问题所需的内容}
- 不修复后果：{继续按当前方案会发生什么}
- 推荐选择：修复 / 缩小范围 / 暂不继续

只列会改变用户结果、系统边界、关键责任、安全控制、总体结构、重大返工或验收结论的问题。拼写、格式偏好、可留给详细设计的细节和低收益的边缘适配不进入修复清单。用户确认修复项或修改范围后，主代理只处理已确认项目，并重新启动受影响的独立评审；用户拒绝阻断修复时，不得标记为 PASS 或发布正式方案。

最终语言与可读性

正式报告使用普通开发能直接理解的中文。产品名、协议名、标准名、接口名、命令和必要缩写可保留原文，首次出现时用中文说明。禁止无意义中英混杂。正式报告只写方案事实和客观设计结论，不写作者推导、报告策略或面向读者的价值。

优先写“谁做什么、什么时候做、失败后怎么办”。少用“边界、语义、属性、可逆性、适用性”等抽象词；必须使用时，当场解释。不得为了显得专业而创造新词。一个句子只表达一个主要判断。句子出现两个以上逗号时，优先拆开。正式报告少用表格；表格只放短语或短句，不塞整段文字。长场景使用直接、具体的标签，例如“发生什么—系统怎么处理—怎样判断通过”。评审意见也用短分块，只保留需要用户判断的主要问题。