需求讨论总返工？15 步工作流让规格一次冻结

需求开发工作流程

CodeNarrator v2.3 · 需求开发工作流教程 · 最后更新 2026-08-03

一、这篇教程解决什么问题

一句话定位：一套从"模糊想法"到"规格冻结"的需求开发流程，用真实项目（CodeNarrator v2.3）的完整过程做全程案例。

需求开发最常见的失败不是"想不到"，而是想乱了：

本教程的方法不是发明出来的，是 CodeNarrator 从 v1 失败到 v2 规格冻结的真实过程中长出来的——每一步都有实际案例，包括一次真实的事故教学。

跳读指南：

• 只想跑流程 → 十一、速查卡（15 步检查清单 + 模板）
• 想理解原理 → 二、原理速览
• 只想看坑 → 十、常见失败模式
• 想按步骤复刻 → 从 三、第 1 步 顺序读

阅读前提：无硬性前置。案例引用的规格文档在<项目根>/docs/下（参考文献），不读原文也能跟上，读了收获更大。

读完能得到什么：

1. 四层规格模型（意图 / 行为 / 状态 / 交互）——防止 UI 驱动架构
2. 讨论协议（提案 → 确认 → 冻结）——让讨论收敛
3. 变更治理（登记表 + 一致性审计）——防止文档漂移
4. 一套可复用的模板（速查卡）

二、原理速览：需求是可逼近的

三句核心信念，全部来自实战：

1. 需求不是一次想清楚的，是靠"提案 → 确认 → 重做"循环逼近的。

这条循环不仅适用于产品内容，也适用于需求本身——与精益开发的Build-Measure-Learn循环同构（The Lean Startup, Eric Ries）：先验证最小假设，再谈扩展。CodeNarrator 的 v1 死因之一就是"全自动一次生成"——把自动化当成质量来源。v2 把同样逻辑用在需求上：定位方案从"全自动编译器"反复收敛到"人机协作创作 IDE"，中间经过十几轮辩论（第 3 步）。

2. 问题先行。

每个新概念先问"它解决哪个具体问题"，答不上来就删。从问题出发的讨论会收敛，从名词出发会膨胀——这是全程最值钱的一条原则。

3. 分层是防失控的关键。

把"为什么做 / 发生什么 / 如何记录 / 如何展示"分成四层，单向依赖：

方案书（产品意图：为什么做） ↓ UserWorkflow（用户行为：发生什么） ↓ Runtime-State（系统契约：如何记录） ↓ UI-Interaction（交互映射：如何操作观察）

依赖方向单向，UI 不得反向修改上层。四层的完整定义与越权信号见 四、第 2 步。

为什么分层能救需求失控：CodeNarrator v1 的失败归因里有一条——约 70% 代码投入在"怎么跑"（状态机 / GUI / API / workspace 管理），只有约 20% 在"产出什么"。分层让每个问题在正确的层里被讨论，v1 的"工程抢戏"本质上就是"分层缺失"。

三、第 1 步：需求剖析与问题定义

做什么：

1. 竞争研究：有没有人做过、做对了什么、缺什么（CodeNarrator 研究了 50+ 竞品，覆盖 7 个类别）
2. 失败归因：重构项目必须回答"旧版本为什么失败"，且要有证据（v1 归因出 5 条根因，每条带证据）
3. 定位一句话：为谁解决什么问题（“面向技术创作者的内容创作 IDE——Cursor 是代码 IDE，CodeNarrator 是技术表达 IDE”）
4. 明确不做清单：至少 5 项（v2 的"不做无人值守全自动 / 不做多平台量产 / 不做 API 服务化 / 不做多用户 / 不做真人配音"）

需求开发（启发 → 分析 → 规格化 → 验证）本身就是需求工程的标准流程（IEEE/ISO/IEC 29148:2018）——上面的 4 项是它的轻量版：启发（竞争研究）→ 分析（失败归因）→ 规格化（定位 + 不做清单）→ 验证（后文的检查点）。

检查点（做到什么程度可以进入下一步）：

• 能一句话说清"为谁解决什么问题"
• 不做清单 ≥ 5 项
• 每个"要做"都能指向一个具体问题

案例：竞争研究结论"技术内容代码级准确 × 专业观感 × 人机协作精修，三者兼备的产品目前为零"——差异化定位不是拍脑袋，是排除了 50 个对手后剩下的空位。

警示信号：

• 讨论从名词开始（"我们做一个 XXX 系统"而没有要解决的问题）→ 后续必膨胀
• 无法回答"谁会用、解决什么"→ 需求还没成型，继续剖析而不是开始设计

练习：给下一个项目写"一句话定位 + 不做清单"，各不超过 50 字。

四、第 2 步：分层规格模型

四层定义：

关键洞察：先行为后状态。

先定义"用户做什么"（UserWorkflow），再定义"系统记录什么"（Runtime-State），最后才定义"界面怎么展示"（UI-Interaction）。顺序一旦颠倒，UI 就会反过来逼迫系统造状态——这就是"UI 驱动架构"的成因。四层单向依赖是 Clean Architecture依赖规则（The Clean Architecture, Robert C. Martin）的规格化实践——源代码依赖只能向内，越靠外越容易变；规格文档同理，越靠下的层越稳定。

配套规则（从实战提炼）：

• 状态三类分离：资产生命周期状态（draft/approved）≠ 派生状态（stale，计算视图）≠ 执行状态（任务级/系统级）。任何"新状态"先归类，归不进这三类就是 UI 展示状态，不进系统
• 展示状态 ≠ 系统状态：UI 可以显示"正在生成 / 需要确认"，但"审核中 / 编辑中"不能成为系统状态
• 术语统一：每份文档配术语表；跨文档发现"同一词两个定义"或"同一概念两个名字"立即登记（第 5 步）

案例：三份文档（方案书 / UserWorkflow / Runtime）在同步轮前做一致性审计，抓到"系统状态"一词在方案书里指 stale、在 Runtime 里指 normal/error——同一词两个定义，靠术语修正（C-001）一次改掉。

练习：给你项目画四层草图，每层一行字。

五、第 3 步：讨论协议（把想法收敛）

三步协议：

提案（提出方案 + 理由） ↓ 确认或反驳（对方给判断：同意 / 反对 / 修改，必须附理由） ↓ 冻结（达成共识后记录成文，不再反复）

识别"征求判断 vs 授权修改"（最容易踩的雷）：

边界冻结仪式（写任何规格文档前必做）：

先确认三件事，再写正文：

1. 本文档装什么（只装行为？只装状态？只装交互？）
2. 本文档不装什么（明确排除清单）
3. 本文档在权威链的哪一层（依赖谁、被谁依赖）

边界不冻结就写正文，文档大概率写歪成"第二份方案书"。

案例：Patch 概念十几轮辩论。从"要不要"→"和撤销什么区别"→"存什么内容"→"和摘要有什么区别"→最终删除。收敛的标志不是"争赢了"，而是问题被问透了——每个追问都让概念更清晰，直到发现它不解决任何独立问题。

反例教学（真实事故）：一次未经讨论直接修改已冻结文档（对方问"你觉得以上建议怎么样？"后直接执行了 7 处编辑）→ 对方选择全部回滚。“你觉得怎么样"永远不等于"动手改”。代价是一整轮回滚。

警示信号：

• 同一概念被追问三轮还在模糊 → 概念没想清，继续问而不是继续写
• 讨论陷入"再讨论一轮"循环 → 缺冻结仪式，先把已共识的部分冻结

练习：模拟一次"提案-反驳-收敛"，要求反驳必须附理由。

六、第 4 步：文档生命周期

七个阶段：

边界冻结 → 正文 → 评审 → 修订 → 正式冻结 → 一致性审计 → 同步回填

关键规则：

1. 每阶段有明确出口：评审通过才授权；修订前先给修改计划清单（第 3 步）
2. 愿景标注：愿景级表述 vs 实施级子集显式区分。案例："改一句 → 全文重写保持语气统一"是产品愿景（M3 能力），M1 只做步级字段级修改——不标注，表面冲突会被反复追问（每个新人都会问一遍）
3. M 标记：每节标注"状态：M1 落地 | 范围：… | 延后：…“，防止"文档写了就必须做”（范围蔓延的核心解药）

案例：UserWorkflow 文档从讨论稿到正式冻结经历 6 项修订——包括"审批 → 确认"的术语统一（企业审批流的联想会诱导做出权限系统）、"NeedConfirmation 不能成为第 3 个权威状态"的边界裁定。每次修订都是先列清单、确认后落盘。

七、第 5 步：变更治理（防止漂移）

已冻结规则不得直接修改。任何变更先登记，格式固定：

Title: <变更标题> Original: <原文规则> Changed: <新规则> Reason: <为什么改——必须写清> Affected: <影响哪些文档>

两条通道分离（防止"改一个实现任务 = 修改产品规格"的维护爆炸）：

销账规则：每项落回对应文档后，状态改"已同步"并注明落回位置（“落回：方案书 7.438”）——决策永远可追溯：为什么改、改在哪、谁批准的。

警示信号：

• 实现开始"兼容旧契约"（旧数据结构 + 新数据结构并存）→ 需要对齐登记
• 两份文档对同一规则说法不同 → 找登记表，而不是猜哪个对

八、第 6 步：一致性审计（怎么查错）

审计清单（可复用检查项，交叉核对相邻层文档）：

做法：

1. 逐条核对相邻层对同一规则的表述（术语 / 链 / 粒度）
2. 发现项进 Change Log 编号登记（C-xxx）
3. 同步轮逐条销账（第 5 步 的销账规则）

案例：三文档一致性审计产出 15 条发现项——2 条实质修正（术语冲突、依赖遗漏）、3 条愿景标注、4 条小同步、6 条实现对齐。没有一条推翻设计——这正是审计的价值：它证明"主体一致"，并把边缘问题一次清光，而不是等到实现阶段才发现。

练习：拿任意两份相关文档，15 分钟内找出 3 处不一致。

九、第 7 步：验证——垂直切片

原则：

1. 切片目标 = 验证规格闭环能否跑通，不是验证单个技术点
2. 只做一个最小闭环，不铺全量——垂直切片是敏捷的成熟实践（Vertical Slicing – Smaller is Better, Agile Alliance）：每次交付一个跨层的可用薄片（用户界面 + 后端逻辑），而不是横向切层（先前端、后数据库）。规格验证同理：切片必须跨"层"（行为 / 状态 / 交互 / 循环），只验证单层不算闭环
3. 每个"层"在切片里都出现：状态契约 + 行为动作 + 交互投影 + 修订循环

案例：M1 Vertical Slice Spike（CodeNarrator 的单步最小闭环）：

建项目 → 导入素材 → 素材请求 → 生成一个 Step → 步审阅 → 发起修订 → 产生提案 → 确认 → 版本更新 → 预览刷新

只做一个 Step，不出视频、不出音频。它同时验证：版本化写入（带版本依赖边）、派生 stale 计算、提案-确认流程、UI 投影（素材请求卡 / 步卡片 / 提案卡 / 预览画布）、修订只影响单步下游。

执行结果（2026-08-03，落地于spike_m1/）：垂直切片已跑通——素材→单步生成→步审阅→修订→提案→确认→版本更新→预览刷新全链路通过。Revision Cost 验证：单步反馈只重生成该步下游（script/scene/preview 版本递增），material 等无关资产 mtime/version 不变；stale 单跳语义与 Runtime-State 3.0 契约一致（改 script 只立即失效 scene，preview 在 scene 重生成后才级联失效）。

诚实标注（流程的一部分）：本切片仍是最小验证——单步、单字段修改、模板渲染；多步脚本、真实 LLM 生成、UI 投影对接后端（FastAPI + SSE）均未覆盖，留待正式 M1 开发逐项验证。未验证的环节必须明说，不能因为"切片通过了"就当全部规格成立。

十、常见失败模式

十一、速查卡

卡 1：15 步全程检查清单

卡 2：越权信号速查

卡 3：修订登记表字段

Title / Original / Changed / Reason / Affected / 状态（待登记→已同步+落回位置）

卡 4：M 标记格式

状态：M1 落地 | 范围：… | 延后：…

卡 5：讨论协议速查

"你觉得怎么样" = 征求判断 → 回答立场，不改文档 "可以 / 确认 / 动手" = 授权修改 → 先给修改计划，再执行 提案 → 确认/反驳（附理由）→ 冻结

十二、参考文献

• The Lean Startup — Eric Ries — Build-Measure-Learn 循环（二、原理速览 引用）
• The Clean Architecture — Robert C. Martin — 依赖规则：依赖只能向内（四、第 2 步 引用）
• Vertical Slicing – Smaller is Better — Agile Alliance — 垂直切片：跨层交付（九、第 7 步 引用）
• IEEE/ISO/IEC 29148:2018 — Requirements Engineering — 需求工程标准流程（三、第 1 步 引用）

本教程全部内容来自上述文档对应的真实开发过程；外部来源均为正文实际引用的权威出处。