用途:根据变更的结构规模与决策性质,判断需要创建哪些文档(PRD、ADR、Design Doc、Work Plan),并给出创建顺序与边界,避免让下游消费者自行推断关键决策。
主要能力:提供创建决策矩阵——Small 无需文档,直接执行任务;Medium 先写 Design Doc 再写 Work Plan;Large 按 PRD → Design Doc → Work Plan 顺序,PRD 批准后继续。ADR 仅在当前范围决策同时通过两道过滤器时插入于 Design Doc 之前,且合格 ADR 会把规模下限抬到 Medium。
规模判定:依据决策负担而非仓库布局,文件数量仅作辅助证据。Small 指单一责任边界内、沿现有模式的一个连贯结果;Medium 指跨边界协调或需要持久设计决策的一个连贯结果;Large 指多个可独立评估的结果需要各自的设计决策。
ADR 条件:需同时满足“选择需要判断”(存在至少两个可信且实质不同的选项)与“决策持久”(实质改变责任、依赖方向、共享契约、持久化模型、技术依赖、可逆性或生命周期成本)。每个通过两道过滤器的技术主题各建一个 ADR;若仅有一种有仓库支撑的实现且可低成本回退,则留在设计文档中。
文档边界:PRD 含产品结果、当前需求、成功标准、用户可见范围、排除项与未决产品问题,不含技术实现选择;ADR 含持久选择、实质不同选项、权衡、决策、后果与回退条件;设计文档只含约束实现或验证的信息,如确认结果与非目标、相关现有代码与已接受决策、选定方案与契约、受影响责任边界与集成点、验收标准与最窄充分验证策略、风险与未决项;工作计划含最少实现单元,每个任务标明来源、预期结果、范围、依赖与验证。
创建流程:确认结果、当前需求与非目标;依据仓库证据确定结构规模;套用 ADR 的选择与持久性过滤器;按矩阵只创建被选中的文档;在产品需求与重大持久设计决策批准后方可授权实现。
存放位置:PRD 为 docs/prd/[feature-name]-prd.md;ADR 为 docs/adr/ADR-[4-digits]-[title].md;Design Doc 为 docs/design/[feature-name]-design.md;Work Plan 为 docs/plans/YYYYMMDD-{type}-{description}.md。工作计划属临时执行状态,默认被 .gitignore 排除,除非仓库明确选择纳入版本控制。
ADR 状态:Proposed → Accepted → Deprecated / Superseded / Rejected。新 ADR 取代已接受 ADR 时,保留旧 ADR 并标注 Superseded 及指向新 ADR 的引用,同时在新 ADR 中引用旧 ADR。
质量检查:每份文档服务一个具名下游消费者;每个保留章节改变决策、保护边界或提供必要证据;仓库观察、推断与未知需可区分;当证据支持时,复用或不创建文档同样有效。
限制:资料未提供具体平台、收费、价格或效果信息。