documentation-criteria

name	documentation-criteria
description	判断某项变更需要哪些 PRD、ADR、UI 规范（UI Spec）、设计文档（Design Doc）和工作计划，以及每种文档的存放位置。用于决定文档范围，或创建/评审技术文档时使用。

文档创建标准

本技能负责文档路由：即变更需要记录哪些会对后续工作产生长期影响的决策，以及每种文档存放在何处。“存放位置”中链接的每个模板负责该文档的内容与结构要求。

每种文档固定的内容

• PRD — 固定业务成果、当前需求、排除项以及后续工作所追溯的验收标准。其 AC ID 是设计与验证的稳定追溯键。实现设计属于设计文档，技术方案选型属于 ADR，任务顺序属于工作计划
• ADR — 固定一项会对后续工作产生长期影响的技术选择，以及在决策中败选的实质性不同备选方案，使后续工作能够区分已接受的决策与偶发的实现细节。完整的实现设计属于设计文档
• UI 规范 — 在实现之前固定界面结构、界面跳转、组件与状态契约、交互以及视觉验收标准。仅在这些决策尚未确定时创建；若具有代表性的仓库依据已经确定了这些内容，则复用已批准的 UI 规范，或直接进入设计文档
• 设计文档 — 记录已确认范围的完整实现设计：职责、流程、契约、变更影响以及验证边界。实现阶段将其视为主要技术基线，因此实现阶段不会擅自臆造缺失的“如何做”。当仓库依据推翻了技术上的“如何做”，而已确认的成果、目标状态需求和非目标仍然成立时，通过其所属工作流修正实现及受影响的技术产物，而无需重新打开产品需求
• 工作计划 — 固定依赖顺序、任务边界、可执行的验证方式以及最早可用的证明点。它引用设计细节，而非重复这些细节
• 任务文件 — 将一个可执行的工作计划成果、其约束来源、调查起点、写入职责以及可观测的验证方式带入实现阶段

创建决策矩阵

结构规模	基础文档	创建顺序
Small（小型）	无	直接实现
Medium（中型）	设计文档、工作计划	设计文档 -> 工作计划
Large（大型）	PRD、设计文档、工作计划	PRD -> 设计文档 -> 工作计划

对于前端/全栈工作，若相关决策尚未确定，应在设计文档之前新增 UI 规范。在设计文档之前完成任何符合条件的 ADR 批次。符合条件的 ADR 会将规模至少提升到中型。

对于 Large（大型）变更，可通过创建新 PRD、更新相关 PRD，或在没有现行产品文档时创建逆向工程 PRD 来满足 PRD 要求。无论规模如何，当产品范围发生变化时都应更新现有 PRD。

结构规模

按决策负担而非仓库层级来分类。文件数量仅作为辅助依据。

规模	决策负担
Small（小型）	单一连贯成果，在单一职责边界内有明显的、有仓库依据支持的实现方式，且不存在会对后续工作产生长期影响的未决选择
Medium（中型）	单一连贯成果，涉及跨边界协调或包含可能对后续工作产生长期影响的选择
Large（大型）	多个各自独立产生价值的成果，需要各自独立的设计决策

跨层实现如果服务于单一连贯成果，仍可归为 Medium（中型）。

ADR 决策过滤器

对已确认实现范围内的每个技术主题，依次应用“选择必要性（Choice）”和“长期影响（Durability）”这两个过滤条件。创建新记录前先检查已接受的 ADR。

1. 选择必要性（Choice） — 已确认的需求、已采纳的决策以及具有代表性的仓库依据，至少留下两个可信且实质性不同的备选方案。
2. 长期影响（Durability） — 在这些方案中做出选择，会实质性地改变职责、依赖方向、共享契约、持久化方式、技术选型、可逆性，或未来工作必须维持或理解的生命周期成本。

对通过这两个过滤器的每个主题创建一份 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-{NN}.md（仅含 backend 的计划）；{plan-name}-backend-task-{NN}.md（混合层计划中的 backend）；{plan-name}-frontend-task-{NN}.md（frontend）	task-template.md

生成路径中的变量必须使用小写 ASCII kebab-case slug。非 ASCII 输入应在构造路径前转换为该格式。

工作计划已在 .gitignore 中排除。

参考资料

每个模板定义了其文档的内容、状态规则、所需依据、可选图表以及完成检查项。仅加载正在创建或评审的文档所对应的模板。