文档创建标准(Documentation Creation Criteria)
该技能负责“文档路由”:判断一项变更需要记录哪些持久性决策,以及每份文档存放于何处。从“存储位置”部分链接的各个模板,负责各自文档的内容与结构要求。
各文档固定的内容
PRD — 固定业务成果、当前需求、排除项,以及后续工作可追溯的验收标准。其 AC ID 是用于设计与验证的稳定可追溯键。实现设计属于 Design Doc,技术选型属于 ADR,任务顺序属于 Work Plan。
ADR — 固定一项持久性技术选择,以及它胜过哪些实质不同的选项,使后续工作能区分“已接受的决策”与“偶然的实现细节”。完整的实现设计属于 Design Doc。
UI Spec — 在实现之前固定界面结构、转场、组件与状态契约、交互,以及视觉验收标准。仅在这些决策仍处于开放状态时才创建;若已有获批的 UI Spec,或具有代表性的仓库证据已确定这些决策,则复用现有 UI Spec 或直接进入 Design Doc。
Design Doc — 为已确认的范围固定完整的实现设计:职责、流程、契约、变更影响与验证边界。实现阶段将已批准的设计决策视为只读权威。
Work Plan — 固定依赖顺序、任务边界、可执行验证,以及最早有用的验证点。它引用设计细节,而非复制设计细节。
Task File — 将一项可执行的 Work Plan 成果、其依据来源、调查起点、写入职责与可观察的验证带入实现阶段。
创建决策矩阵
结构性规模 | 基础文档 | 创建顺序
Small | 无 | 直接实现
Medium | Design Doc、Work Plan | Design Doc -> Work Plan
Large | PRD、Design Doc、Work Plan | PRD -> Design Doc -> Work Plan
对于前端/全栈工作,当相关决策仍处于开放状态时,在 Design Doc 之前增加一份 UI Spec。在 Design Doc 之前完成所有符合条件的 ADR 批次。一个符合条件的 ADR 至少会将规模提升至 Medium。
对于 Large 变更,通过创建新 PRD、更新相关 PRD,或在尚无当前产品文档时创建反向 PRD,来满足 PRD 要求。在任何规模下,当产品范围发生变化时,更新现有 PRD。
结构性规模
分类依据是决策负担,而不是仓库布局。文件数量仅为辅助证据。
规模 | 决策负担
Small | 一个连贯成果,一个由仓库证据支持、位于单一职责边界内的明显实现,且没有未解决的持久性选择
Medium | 一个连贯成果,需要协调某个边界,或包含一个可能持久性的选择
Large | 多个各自独立有价值的成果,需要分别进行设计决策
当跨层实现服务于一个连贯成果时,仍可保持为 Medium。
ADR 决策过滤器
对已确认实现范围内的每个技术主题,依次应用 Choice 过滤器与 Durability 过滤器。在创建新记录之前,先检查已接受的 ADR。
Choice 需要判断 — 已确认的需求、已接受的决策,以及具有代表性的仓库证据,仍留下至少两个可信且实质不同的选项。
Choice 是持久性的 — 在这些选项之间进行选择,会实质性改变职责、依赖方向、共享契约、持久化、技术、可逆性,或未来工作必须保留或理解的生命周期成本。
为每个同时通过两个过滤器的主题创建一份 ADR,并将完整批次放在一起评审。将必须一起选择或重新考虑的选择归为一组;将可独立重新审视的决策分开。本地实现细节与其他可低成本逆转的选择属于 Design Doc。
存储位置
文档 | 路径 | 命名规范 | 模板
PRD | docs/prd/ | [feature-name]-prd.md | prd-template.md
ADR | docs/adr/ | ADR-[4-digits]-[title].md | adr-template.md
UI Spec | docs/ui-spec/ | [feature-name]-ui-spec.md | ui-spec-template.md
UI Spec 资产 | docs/ui-spec/assets/{feature-name}/ | 原型代码文件 | -
Design Doc | docs/design/ | [feature-name]-design.md | design-template.md
Work Plan | docs/plans/ | YYYYMMDD-{type}-{description}.md | plan-template.md
Task File | docs/plans/tasks/ | 参见 task-decomposer 文件名表 | task-template.md
Work Plan 被 .gitignore 排除。
参考
每个模板定义其文档的内容、状态规则、所需证据、可选图表与完成检查。仅加载正在创建或评审的那份文档所对应的模板。