documentation-criteria

文档创建标准

此文件用于确定路由：哪些变更需要哪些文档，以及这些文档存放在哪里。文档的具体内容由其模板定义，模板链接见存储位置。

各文档解决的问题

每种文档都解决一类仅凭代码仓库无法确定的决策。未填写的部分会变成下文所列使用者日后的猜测，而且不会留下假设记录。

• PRD — 明确业务成果和验收标准，后续工作会据此追踪。其 AC ID 是 Design Doc、UI Spec 和测试选择共同使用的可追溯性标识；没有这些标识，各使用者都要从描述性文字中重新推导需求，测试与其所保障价值之间的关联也会丢失。实现细节属于 Design Doc，选择依据属于 ADR，阶段划分和任务拆解属于 Work Plan。

• ADR — 记录一项持久的技术选择及其胜过的其他方案，让后续工作能区分有意做出的决策与意外结果。没有它，未来的变更要么会重复进行同样的比较，要么会悄然推翻原有选择。Accepted 记录的是当前选定的手段，而不是必须保留该手段的义务：如果后续证据支持改用更小且足够的方案，就应更新或取代该决策，同时确保已确认的成果、期望的未来需求和非目标仍然成立。端到端实现设计属于 Design Doc，进度安排和代码仓库任务属于 Work Plan。

• UI Spec — 在组件尚未创建前，记录屏幕结构、转换、组件／状态契约和视觉验收标准，以便在实现前确定拆解方式，而不是在实现过程中逐个组件决定。当这些决策尚未确定时，创建 UI Spec；如果已有获批的 UI Spec 可供复用，或代码仓库中已有一种明显适用的模式足以确定这些决策，则直接进入 Design Doc。技术实现和 API 契约属于 Design Doc。

• Design Doc — 记录已确认范围的完整实现设计：流程、契约、变更影响和验证策略。任务执行以此为主要技术基准，避免实现时悄然臆造缺失的实现方式。如果代码仓库中的证据表明技术实现方式无效，而已确认的成果、期望的未来需求和非目标仍然成立，则应通过各自所属的工作流程修正实现及受影响的技术文档，而无需重新审议产品需求。技术选型依据属于 ADR，进度安排和任务分配属于 Work Plan。

• Work Plan — 明确任务顺序、依赖关系、可执行的验证方式和最早的纵向验证节点。没有它，任务顺序就会依据文件布局而非依赖关系来安排，集成风险也会留到工作末尾。设计细节应引用 Design Doc，而非重复描述。

创建决策矩阵

结构规模	基础文档	创建顺序
小	无	直接实现
中	Design Doc → Work Plan	从 Design Doc 开始
大	PRD → Design Doc → Work Plan	PRD 获批后继续

按以下顺序构建一条路径：

1. 根据结构规模选择基础路径。
2. 如果适用，在 Design Doc 之前立即插入 UI Spec。
3. 一个或多个符合条件的 ADR 决策点会在 Design Doc 之前立即插入一批 ADR。符合条件的决策点会将规模下限设为中。

结构规模

应根据决策负担分类，而非仓库布局。文件数量仅作为辅助证据。

规模	结构条件
小	一个连贯的结果在一个职责边界内，有一种明确且受仓库证据支持的实现方式，且不存在尚未解决的持久性选择
中	一个连贯的结果需要跨越边界进行协调，或需要调查可能具有持久影响的选择
大	多个各自有价值的结果需要分别做出设计决策

符合条件的 ADR 决策点会将规模下限设为中，因为它会产生持久决策。一个连贯的结果即使跨越多个层，也仍属中；只有当多个各自有价值的结果需要分别做出设计决策时，才属大。

ADR 决策筛选条件

对已确认的实现范围内的每个技术主题，先应用「选择」筛选条件，再应用「持久性」筛选条件。独立于结构规模进行筛选，并首先检查现有 ADR。

1. 选择需要判断——当前需求、已接受的决策以及有代表性的仓库证据表明，至少存在两个可信且实质不同的选项，必须通过比较才能做出选择。
2. 决策具有持久性——在这些选项中做出选择，会实质改变职责、依赖方向、共享契约、持久化方式、技术依赖、可逆性或生命周期成本，而未来工作必须保留或理解这些变化。

为同时通过两个筛选条件的每个主题创建一份 ADR，并一并审查完整的一批 ADR。如果多个选择必须同时做出或重新考虑，应将其视为一个决策点；可独立重新审视的选择则应分别处理。

符合条件的持久性选择包括：

• 引入或替换某项技术、库、平台、存储模型或外部依赖；
• 在存在可信替代方案时，改变所有权、依赖方向、信任边界或共享公共契约；
• 用通过两个筛选条件的另一项持久性选择，替换已接受的架构决策；
• 选择不可逆或逆转成本高的数据或兼容性策略。

如果局部契约、数据流、状态或组件变更遵循已接受的设计，有一种明确且受仓库证据支持的实现方式，或仍可低成本逆转，则应纳入设计文档。文件数量、使用方数量、嵌套层级、状态数量、步骤数量及异步操作数量都只是辅助证据，不是 ADR 的判断标准。只有上述符合条件的决策才会生成 ADR；通用技术关注点、运维上的可能性和被拒绝的活动只能作为支持判断的依据。

存储位置

文档	路径	命名约定	模板
PRD	docs/prd/	[feature-name]-prd.md	prd-template.md
ADR	docs/adr/	ADR-[4-digits]-[title].md	adr-template.md
UI 规范	docs/ui-spec/	[feature-name]-ui-spec.md	ui-spec-template.md
UI 规范资源	docs/ui-spec/assets/{feature-name}/	原型代码文件	-
设计文档	docs/design/	[feature-name]-design.md	design-template.md
工作计划	docs/plans/	YYYYMMDD-{type}-{description}.md	plan-template.md
任务文件	docs/plans/tasks/	{plan-name}-task-{number}.md	task-template.md

*注：工作计划被 .gitignore 排除。

参考资料

每个模板都定义了相应文档的内容、结构元素和图表标准：prd-template.md、adr-template.md、ui-spec-template.md、design-template.md、plan-template.md、task-template.md