# Ni Design With Docs > 通过定向调研、产品与总体架构访谈、显式对齐和独立评审，把新的或增量变化的产品、平台需求收敛为中文 Markdown 产品与总体架构方案。适用于需要明确用户方案、当前与目标差异、系统边界与影响范围、全局架构决策、质量、安全和验收的复杂设计；输出用于产品确认、总体架构评审，并作为后续详细设计与任务拆分的输入，不用于分析现有代码、设计具体接口或直接编码。 - Skill: `ttttstc/ni-design-with-docs` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add ttttstc/ni-design-with-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/ttttstc/ni-design-with-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: ttttstc (https://skillmd.com/u/ttttstc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ttttstc/ni-design-with-docs --- # 访谈驱动的产品架构设计 先用证据和访谈把问题定义正确，再从第一性原理推导最小充分方案。最终文档应让产品、架构、研发和 Agent 对目标、产品行为、系统边界、全局决策、质量、安全与验收形成同一理解。 ## 不可破坏的规则 1. **先决策对齐，后设计。** 每个会改变方案的用户决策都必须显式呈现。决策树未遍历完成、对齐摘要未获得用户确认前，不得开始方案设计或生成正式文档。用户可以授权后续分支全部采用推荐项来减少交互轮次，但这不是跳过决策。 2. **先提供调研输入，再提问题。** 问题和推荐必须建立在用户资料、已经确认的访谈事实或必要的公开一手资料上，不能凭“最佳实践”自行定案。 3. **工作底稿与正式报告分离。** 调研过程、访谈记录、给设计者解惑的术语、评审过程和 Skill 自身策略留在工作底稿；正式报告只呈现方案事实、客观设计结论和可观察结果。正式报告不得暴露作者推导、访谈对齐状态、报告策略或面向读者的价值说明。 4. **从目标和不可变事实推导。** 选择能完整解决问题、责任最少、关系最简单的方案。没有必要时不新增模块、抽象、术语、接口或图。 5. **只写影响总体方案的内容。** 系统边界、影响范围、架构决策、视图、质量要求和风险都围绕本次目标裁剪，不做全系统介绍，也不下钻到接口字段和内部实现。 6. **安全不是附录。** 每个方案都要判断安全适用性；存在安全影响时完成威胁与控制设计，并通过独立安全评审。 7. **双重独立评审后发布。** 架构评审与安全评审必须来自未参与设计的独立上下文。评审只抓会造成目标、边界、安全、重大返工或验收失败的主要问题，不为完整而完整。任一评审未通过，不得把草稿作为正式方案交付。 8. **系统规格是唯一行为真源。** 系统规则、边界、权限、状态、失败行为和跨边界传递契约只在系统规格或其既有合理归属中定义；不新增独立 Story 或行为规格层，也不在验收中复写一套等价规格。 9. **验收只保留可判定的主场景。** 验收规定研发和测试必须覆盖的设计级主场景，不展开详细测试用例。每项都要能用状态、数量、已确认阈值、一致性或其他确定性信号判断 PASS/FAIL；没有依据时不得编造数值。 ## 状态机 ```text P0 任务与证据准备 ↓ P1 研究输入与分轮访谈 ↓ P2 对齐摘要 ├─ 用户修改：回到 P1 ├─ 用户确认：进入 P3 └─ 未确认：停在 P2 ↓ P3 最小充分设计 ↓ P4 正式草稿 ↓ P5 独立架构评审 + 独立安全评审 ├─ FAIL：修订后重新评审 ├─ BLOCKED：向用户补充提问 └─ 全部 PASS：发布正式方案 ``` 不得由设计者自行判断“信息已经足够”并越过 P2。用户回复“继续”只有在前一条消息已经给出完整对齐摘要时，才视为确认。 ## 按阶段读取 | 阶段 | 必读材料 | |---|---| | P0–P2 | `references/01-workflow.md`、`references/02-concepts-and-interview.md` | | 需要公开取证或整理边界输入 | `references/03-current-state-and-research.md`；委派取证时再读 `agents/researcher.md` | | P3 | `references/04-architecture-design.md`、`references/05-views-interfaces-constraints.md`、`references/08-security-review.md` | | P4 | `references/06-testing-and-output.md`、`references/07-writing-style.md`、`templates/architecture-baseline.md` | | P5 | `eval/gates.md`、`agents/reviewer.md`、`agents/security-reviewer.md` | 只在进入对应阶段时加载材料。不要一开始把全部参考文件和模板塞进上下文。 ## P0–P1：先给调研输入，再访谈 从用户输入和资料中建立工作底稿，区分：已确认事实、用户决定、外部证据、假设、未知项和冲突项。用户已经给出的信息不重复询问。 第一次有效响应不得直接输出架构。它应包含： 1. **当前理解**：用几句话复述真实目标、核心场景和已知限制； 2. **调研输入**：列出会影响当前问题的一手事实、用户资料依据或行业通用约束，并说明它们为什么影响选择；没有可靠证据时直接说明未知，不能补写内部现状； 3. **第一轮问题**：只问当前决策前沿的问题。 每轮通常提出 3–5 个同层问题；只有更少的问题会改变方案时可以少于 3 个。每个问题都包含： - 需要用户决定的问题； - 2–3 个互斥选项，推荐项放在最前； - 推荐理由； - 不同答案会改变的产品、架构、安全或验收结果。 用户可以逐题回答，也可以回复“本轮全部按推荐”。这只关闭当前问题，不等于自动授权开始设计。用户还可以回复“后续全部按推荐”，授权主代理继续遍历剩余决策树；主代理仍要逐项形成有依据的推荐决策清单，并在 P2 交给用户最终确认。 术语解释只用于帮助用户做当前决定：在问题附近用一句自然中文解释。不得先输出百科式名词表，也不得把这些解释默认写进正式报告。 ## P2：显式对齐门禁 访谈问题收敛后，必须给出一份简短的对齐摘要： - 真实目标与成功结果； - 核心用户路径和用户可见行为； - 本次范围与业务非目标； - 已确认的系统边界与影响范围； - 已确认的关键约束与推荐选择； - 安全、数据和权限边界； - 适用的输入、调用参数、上下文、Token、Secret、输出、状态和错误传递规则； - 会改变总体方案的质量要求及其可观察结果； - 仍未确定但不阻塞设计的事项； - 会阻塞设计的冲突或未知项。 随后暂停，等待用户明确确认或修改。以下表达可视为确认：“确认”“按这个设计”“按以上推荐开始设计”。 ### 推荐项快速路径 用户要求“跳过访谈”“全部按推荐”“按推荐直接设计”时，将其解释为减少问答轮次，而不是省略决策： - 先完成能由资料和公开来源确认的事实调查； - 遍历剩余决策树，为每个决策记录推荐项、依据和影响； - 访谈阶段决定产品行为、系统边界、影响范围、责任和跨边界约束；没有确认依据时，不提前创造模块名称或技术分层； - 不能基于证据推荐的用户目标、内部事实、商业或合规决定，仍然必须提问； - 将全部推荐选择写入对齐摘要，等待用户最终确认； - 用户确认前仍不得进入设计。 ## P3：最小充分设计 按以下顺序推导，而不是套模板： ```text 真实目标 → 当前/目标差异（适用时） → 产品方案 → 系统边界与责任 → 系统规格 → 主要流程、数据和状态 → 关键决定与协作约束 → 质量、安全和异常 → 可度量验收主场景 ``` 上面是设计推导顺序。正式报告的章节顺序为“总体设计结论、产品方案、系统边界和责任、主要流程/数据/状态、系统规格、关键决定和协作约束”，系统规格章节放在主要流程章节之后。 设计时遵守： - 根据已确认的访谈输入，由设计者归纳系统负责什么、与谁协作、影响哪些部分；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` 时，主代理不得直接改稿或自行扩大方案。先合并重复问题，按以下格式向用户列出需要确认的修复项： ```markdown # 评审结论与待确认修复 结论：不能发布 ## 主要问题 1：{一句话说明主要矛盾} - 评审结论：{为什么当前方案不能通过} - 主要影响：{会导致什么错误、风险、返工或无法验收} - 最小修复：{只改变解决该问题所需的内容} - 不修复后果：{继续按当前方案会发生什么} - 推荐选择：修复 / 缩小范围 / 暂不继续 ``` 只列会改变用户结果、系统边界、关键责任、安全控制、总体结构、重大返工或验收结论的问题。拼写、格式偏好、可留给详细设计的细节和低收益的边缘适配不进入修复清单。用户确认修复项或修改范围后，主代理只处理已确认项目，并重新启动受影响的独立评审；用户拒绝阻断修复时，不得标记为 `PASS` 或发布正式方案。 ## 最终语言与可读性 正式报告使用普通开发能直接理解的中文。产品名、协议名、标准名、接口名、命令和必要缩写可保留原文，首次出现时用中文说明。禁止无意义中英混杂。正式报告只写方案事实和客观设计结论，不写作者推导、报告策略或面向读者的价值。 优先写“谁做什么、什么时候做、失败后怎么办”。少用“边界、语义、属性、可逆性、适用性”等抽象词；必须使用时，当场解释。不得为了显得专业而创造新词。一个句子只表达一个主要判断。句子出现两个以上逗号时，优先拆开。正式报告少用表格；表格只放短语或短句，不塞整段文字。长场景使用直接、具体的标签，例如“发生什么—系统怎么处理—怎样判断通过”。评审意见也用短分块，只保留需要用户判断的主要问题。