Documentation Criteria

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

# 文档创建标准

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

## 每种文档固定的内容

- **PRD** — 固定业务成果、当前需求、排除项以及后续工作所追溯的验收标准。其 AC ID 是设计与验证的稳定追溯键。实现设计属于设计文档，技术方案选型属于 ADR，任务顺序属于工作计划
- **ADR** — 记录一项会对后续工作产生长期影响的技术选择，以及在决策中败选的实质性不同备选方案，使后续工作能够区分已接受的决策与偶发的实现细节。`Accepted` 记录的是当前选定的手段，而不是必须保留它的义务：当后续依据表明存在更小且足够的选择时，在已确认成果、目标状态需求和非目标保持成立的前提下，更新或取代该 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](references/prd-template.md) |
| ADR | `docs/adr/` | `ADR-[4-digits]-[title].md` | [adr-template.md](references/adr-template.md) |
| UI 规范 | `docs/ui-spec/` | `[feature-name]-ui-spec.md` | [ui-spec-template.md](references/ui-spec-template.md) |
| UI 规范附件 | `docs/ui-spec/assets/{feature-name}/` | 原型代码文件 | - |
| 设计文档 | `docs/design/` | `[feature-name]-design.md` | [design-template.md](references/design-template.md) |
| 工作计划 | `docs/plans/` | `YYYYMMDD-{type}-{description}.md` | [plan-template.md](references/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](references/task-template.md) |

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

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

## 参考资料

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