ACDL研发流程附录C：设计要求与验证追踪

Posted on 2026-08-17 Views:

ACDL研发流程系列第15篇，共15篇。

上一篇：ACDL研发流程附录B：登记表、状态和常用命令

这套追踪解决什么问题

项目规模扩大以后，仅仅知道“有测试”还不够。Director和Agent需要继续回答：一条长期规则在哪里定义，为什么存在，哪些验证能够直接判断它，哪些测试只是提供相关支持。

当前项目的设计要求追踪只保存设计要求与来源、产生原因和验证之间的长期关系，不把需求、设计、代码、测试结果和版本状态复制到一张大表中。

已经确认的设计正文
  →定义稳定设计要求的完整含义

design-requirements.json
  →登记要求来源、产生原因、主题和验证关系

测试或其它验证入口
  →提供实际判断方式

当前设计要求与验证追踪.md
  →生成供人查阅的关系视图

测试是否真正通过，继续写在ACL、DFL、ERL或版本记录中；REQ、ISSUE和Loop状态也继续由各自登记表负责。追踪账本不是第二份状态台账，更不是测试报告。

什么样的规则需要稳定编号

不是每个带有“必须”或“不得”的句子都需要编号。新增或实质修改的规则满足以下任一条件时，才分配稳定设计要求编号：

决定用户可以观察和验收的结果；
构成权限、安全或数据边界；
形成跨模块、跨进程、接口、迁移、部署或恢复的长期约束；
需要跨版本持续回归或进入正式验收。

普通私有函数怎样拆分、局部变量怎样命名、单个测试怎样组织，不为便于引用而分配稳定编号。一个编号也不能包住几条彼此无关的规则，否则测试无法判断它究竟证明了什么。

前缀	用于
`PRD-`	平台级产品范围、用户承诺、核心规则和结果指标
`DOM-`	领域行为、用户流程、对象状态和验收结果
`ARCH-`	跨进程、数据、接口、部署、迁移和恢复要求
`SEC-`	身份、凭据、隔离、网络、审计和数据安全要求

每类使用三位数字，一经使用不修改、回收或复用。CAP-005是整份能力设计文档，DOM-005是文档中的一条领域行为要求，两者不要混用。

六个组成部分各自负责什么

组成部分	路径或标记	职责
设计正文	`docs/02-设计/`中的系统、能力或横切设计	保存要求完整含义，完整内容只在这里定义
追踪账本	`tests/traceability/design-requirements.json`	保存当前主题、每项要求的来源和验证关系
账本JSON结构规则（Schema）	`tests/traceability/design-requirements.schema.json`	规定JSON字段、编号格式和验证方法
测试标记	`TRACE-REQ`或`TRACE-TOPIC`	让检查器确认测试声明的直接或支持性关系
生成视图	`docs/02-设计/00-索引与追踪/IDX-002-设计要求与验证追踪.md`	按主题和要求生成人类可读入口
检查与生成脚本	`pnpm trace:check`、`pnpm trace:render`、`pnpm trace:refresh -- --reviewed`	检查关系、重建视图；设计定义经过人工复核后，受控刷新定义来源和摘要

普通设计变化只修改设计正文、账本和必要测试，不修改Schema。只有追踪系统的数据结构本身改变时，才调整Schema和相应工具。

账本字段怎样理解

逐要求记录使用以下字段：

字段	表达的事实	维护要求
`id`	稳定设计要求编号	与设计正文完全一致
`source`	完整定义所在的仓库路径	只指向当前设计，不指向计划和实施记录
`definitionDigest`	该项要求定义块的SHA-256摘要	正文变化或移动后，在人工复核关系后刷新
`origin`	要求为什么产生	新要求填写对应`REQ-六位编号`；旧基线使用`pre-req-process`
`topics`	按问题查找要求时使用的主题	优先复用已有主题
`directVerification`	能够直接判断该项要求的验证	不能完整判断时保持空数组
`issues`	当前与该要求直接相关的问题	可选，只引用已登记ISSUE，不复制状态

主题记录只保存id、title和supportingVerification。同一批代表性测试在主题上登记一次，不复制到几十条要求中。

每项验证使用：

字段	含义
`method`	`test`、`inspection`、`analysis`或`demonstration`之一
`references`	真实存在的测试、检查、分析或实机记录路径
`note`	可选，说明这项证据能证明什么、不能证明什么

test表示自动化测试；inspection表示人工或工具检查；analysis表示通过设计、代码、数据或模型分析作出判断；demonstration表示实机操作或运行记录。没有自动化测试不等于不能验证，但必须选择真实发生的方法和证据入口。

直接验证和支持性验证有什么区别

直接验证（direct）表示一个引用能够直接判断某项具体要求是否满足。假设一条要求同时规定“员工只能读取自己的文件”“跨员工请求必须拒绝”“不得泄露目标文件是否存在”，直接测试需要对这三部分都作出明确判断。

直接测试文件使用要求编号标记：

1	// TRACE-REQ: SEC-999

并把这个文件登记到该要求的directVerification。SEC-999在这里只是教学编号，不是仓库中的真实要求。

支持性验证（supporting）表示测试与一个主题相关，却不能单独证明其中每条要求。测试文件使用主题标记：

1	// TRACE-TOPIC: workspace-runtime

并登记到主题的supportingVerification。支持性测试不能描述成“逐项覆盖全部要求”。如果没有一项测试能够完整判断某条要求，directVerification保持空数组，比夸大覆盖更准确。

新增一条稳定设计要求

下面继续使用虚构的SEC-999说明完整操作。实际工作先从对应REQ和设计评审开始，不能直接复制这个编号。

第一步，在受影响的设计正文中写出一条完整、可以判断的规则：

1	SEC-999：员工只能通过工作空间文件接口读取自己的文件；请求其它员工的路径时必须拒绝，且不得返回文件是否存在。

第二步，在design-requirements.json增加记录。此时重点先把人工维护的关系写准确：source指向定义正文，origin指向产生这项变化的REQ，topics和验证关系按实际情况填写。definitionDigest可以先保留一个符合格式的临时值，最终由受控刷新命令根据正文统一生成。

{
  "id": "SEC-999",
  "source": "docs/02-设计/03-横切设计/CRS-001-安全与信任边界.md",
  "definitionDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
  "origin": "REQ-替换为真实六位编号",
  "topics": ["workspace-runtime"],
  "directVerification": []
}

第三步，根据实际证明能力选择直接或支持性验证。只有测试能够判断整条要求时才添加TRACE-REQ并登记到directVerification；一般相关测试使用TRACE-TOPIC并登记到主题。

第四步，人工复核设计要求的身份、产生原因、主题、直接/支持性验证和Issue关系。确认这些关系准确后，运行：

1
2
3

pnpm trace:refresh -- --reviewed
pnpm docs:check
git diff --check

trace:refresh会先要求当前设计定义集合和追踪账本一一对应，然后只刷新每项要求的source和definitionDigest，保留origin、topics、directVerification和issues。随后它会重建追踪Markdown生成区。出现新增、缺失或重复ID时直接拒绝，不会为了生成摘要自动猜测关系。

trace:render只用于账本关系和定义摘要都已经正确、只是Markdown生成视图过期的情况：

1	pnpm trace:render

它只更新生成视图中的自动生成区域，不修改设计正文和账本。生成区域不接受手工编辑。

修改、移动或替代旧要求

只改善表达且含义不变时，保留原编号。正文变化会让trace:check报告摘要不一致，这是提醒人工复核，不是要求把文字改回旧写法。确认要求含义、产生原因、主题、验证关系和Issue关系仍然正确后，运行：

1	pnpm trace:refresh -- --reviewed

要求移动到另一份设计但含义不变时，同样保留编号。受控刷新会把source更新到当前唯一的定义位置，并重新计算摘要；如果同一编号在多处定义或账本和正文集合不一致，会直接失败。

要求含义发生实质变化时，先判断修改后的规则是否仍与原规则表达同一件事。如果新规则替代了旧要求，保留旧要求的替代说明，并为新规则取得新编号；不要继续使用旧编号表达不同含义。变化来自现行产品需求时，新的origin填写对应REQ。

测试移动、删除或覆盖范围变化时，同步更新验证入口和标记。一个测试不再能直接判断整项要求时，把它降为支持性验证或移除关系，不为了让覆盖数量看起来不下降继续登记为direct。

ISSUE关闭后，复核要求记录中的可选issues是否仍有保留关系的必要。这里不复制ISSUE状态和结论，问题的当前状态和结论始终从ISSUE台账读取。

常见检查失败怎样处理

检查结果	实际含义	正确处理
当前稳定设计要求没有进入账本	正文新增了编号，账本没有对应记录	补充来源、摘要、产生原因、主题和验证关系，复核后运行`trace:refresh`
账本引用未定义稳定要求	编号或路径错误，或者正文已经删除	恢复定义或按替代关系更新账本
要求正文已经变化	`definitionDigest`与当前定义不一致	先复核产生原因和验证关系；确认语义没有错误漂移后运行`pnpm trace:refresh -- --reviewed`
验证引用不存在	测试或证据文件移动、删除或拼写错误	更新为真实入口，不创建空文件绕过
缺少`TRACE-REQ`	测试被登记为直接验证，但文件没有要求标记	确认是否真的直接验证，再补标记或降低关系
缺少`TRACE-TOPIC`	测试被登记为主题支持性验证，但文件没有主题标记	补充准确主题标记或移除关系
Markdown与账本不一致	生成视图已经过期	运行`pnpm trace:render`，不手工修改生成区

检查通过只证明编号、来源、关系和生成结果彼此一致。它不能证明设计决定合理，也不能证明测试最近一次运行成功。设计合理性由设计评审确认，实际验证结果由Loop和版本记录保存，Director仍然对最终结论负责。