Back to Details

documentation-criteria

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Creation Criteria

文档创建规范

Creation Decision Matrix

创建决策矩阵

ConditionRequired DocumentsCreation Order
New Feature AdditionPRD -> [ADR] -> Design Doc -> Work PlanAfter PRD approval
ADR Conditions Met (see below)ADR -> Design Doc -> Work PlanStart immediately
6+ FilesADR -> Design Doc -> Work Plan (Required)Start immediately
3-5 FilesDesign Doc -> Work Plan (Recommended)Start immediately
1-2 FilesNoneDirect implementation
条件所需文档创建顺序
新增功能PRD -> [ADR] -> 设计文档 -> 工作计划PRD审批通过后
满足ADR创建条件（见下文）ADR -> 设计文档 -> 工作计划立即启动
涉及6个及以上文件ADR -> 设计文档 -> 工作计划（必填）立即启动
涉及3-5个文件设计文档 -> 工作计划（推荐）立即启动
涉及1-2个文件无直接实现

ADR Creation Conditions (Required if Any Apply)

ADR创建条件（满足任意一项则必填）

1. Type System Changes

1. 类型系统变更

  • Adding nested types with 3+ levels: 
    type A = { b: { c: { d: T } } }
    • Rationale: Deep nesting has high complexity and wide impact scope
  • Changing/deleting types used in 3+ locations
    • Rationale: Multiple location impacts require careful consideration
  • Type responsibility changes (e.g., DTO->Entity)
    • Rationale: Conceptual model changes affect design philosophy
  • 添加3层及以上嵌套类型：
    type A = { b: { c: { d: T } } }
    • 理由：深层嵌套复杂度高，影响范围广
  • 修改/删除在3个及以上位置使用的类型
    • 理由：多位置影响需谨慎考量
  • 类型职责变更（例如：DTO->Entity）
    • 理由：概念模型变更会影响设计理念

2. Data Flow Changes

2. 数据流变更

  • Storage location changes (DB->File, Memory->Cache)
  • Processing order changes with 3+ steps
    • Example: "Input->Validation->Save" to "Input->Save->Async Validation"
  • Data passing method changes (props->Context, direct reference->events)
  • 存储位置变更（数据库->文件、内存->缓存）
  • 包含3个及以上步骤的处理顺序变更
    • 示例："输入->验证->保存" 改为 "输入->保存->异步验证"
  • 数据传递方式变更（props->Context、直接引用->事件）

3. Architecture Changes

3. 架构变更

  • Layer addition, responsibility changes, component relocation
  • 新增层级、职责变更、组件迁移

4. External Dependency Changes

4. 外部依赖变更

  • Library/framework/external API introduction or replacement
  • 引入或替换库/框架/外部API

5. Complex Implementation Logic (Regardless of Scale)

5. 复杂实现逻辑（无论规模）

  • Managing 3+ states
  • Coordinating 5+ asynchronous processes
  • 管理3个及以上状态
  • 协调5个及以上异步流程

Detailed Document Definitions

详细文档定义

PRD (Product Requirements Document)

PRD（产品需求文档）

Purpose: Define business requirements and user value
Includes:
  • Business requirements and user value
  • Success metrics and KPIs (measurable format)
  • User stories and use cases
  • MoSCoW prioritization (Must/Should/Could/Won't)
  • MVP and Future phase separation
  • User journey diagram (required)
  • Scope boundary diagram (required)
Excludes:
  • Technical implementation details (->Design Doc)
  • Technical selection rationale (->ADR)
  • Implementation phases (->Work Plan)
  • Task breakdown (->Work Plan)
目的：定义业务需求和用户价值
包含内容：
  • 业务需求与用户价值
  • 成功指标与KPI（可量化格式）
  • 用户故事与用例
  • MoSCoW优先级划分（Must/Should/Could/Won't）
  • MVP与未来阶段划分
  • 用户旅程图（必填）
  • 范围边界图（必填）
不包含内容：
  • 技术实现细节（→设计文档）
  • 技术选型理由（→ADR）
  • 实施阶段（→工作计划）
  • 任务拆分（→工作计划）

ADR (Architecture Decision Record)

ADR（架构决策记录）

Purpose: Record technical decision rationale and background
Includes:
  • Decision (what was selected)
  • Rationale (why that selection was made)
  • Option comparison (minimum 3 options) and trade-offs
  • Architecture impact
  • Principled implementation guidelines (e.g., "Use dependency injection")
Excludes:
  • Implementation schedule, duration (->Work Plan)
  • Detailed implementation procedures (->Design Doc)
  • Specific code examples (->Design Doc)
  • Resource assignments (->Work Plan)
目的：记录技术决策的理由与背景
包含内容：
  • 决策内容（选择了什么）
  • 决策理由（为何做出该选择）
  • 方案对比（至少3种方案）与权衡
  • 架构影响
  • 原则性实施指南（例如："使用依赖注入"）
不包含内容：
  • 实施时间、时长（→工作计划）
  • 详细实施步骤（→设计文档）
  • 具体代码示例（→设计文档）
  • 资源分配（→工作计划）

Design Document

设计文档

Purpose: Define technical implementation methods in detail
Includes:
  • Existing codebase analysis (required)
    • Implementation path mapping (both existing and new)
    • Integration point clarification (connection points with existing code even for new implementations)
  • Technical implementation approach (vertical/horizontal/hybrid)
  • Technical dependencies and implementation constraints (required implementation order)
  • Interface and type definitions
  • Data flow and component design
  • E2E verification procedures at integration points
  • Acceptance criteria (EARS format: When/While/If-then/none)
  • Change impact map (clearly specify direct impact/indirect impact/no ripple effect)
  • Complete enumeration of integration points
  • Data contract clarification
  • Agreement checklist (agreements with stakeholders)
  • Code inspection evidence (inspected files/functions during investigation)
  • Field propagation map (when fields cross component boundaries)
  • Data representation decision (when introducing new structures)
  • Applicable standards (explicit/implicit classification)
  • Prerequisite ADRs (including common ADRs)
Excludes:
  • Why that technology was chosen (->Reference ADR)
  • When to implement, duration (->Work Plan)
  • Who will implement (->Work Plan)
目的：详细定义技术实现方式
包含内容：
  • 现有代码库分析（必填）
    • 实现路径映射（现有与新增）
    • 集成点说明（即使是新实现，也要明确与现有代码的连接点）
  • 技术实现方案（纵向/横向/混合）
  • 技术依赖与实施约束（必填实施顺序）
  • 接口与类型定义
  • 数据流与组件设计
  • 集成点端到端验证流程
  • 验收标准（EARS格式：When/While/If-then/none）
  • 变更影响图（明确标注直接影响/间接影响/无连锁反应）
  • 集成点完整枚举
  • 数据契约说明
  • 共识检查清单（与利益相关者达成的共识）
  • 代码检查证据（调研期间检查的文件/函数）
  • 字段传播映射（字段跨组件边界时）
  • 数据表示决策（引入新结构时）
  • 适用标准（显式/隐式分类）
  • 前置ADR（包括通用ADR）
不包含内容：
  • 技术选型理由（→参考ADR）
  • 实施时间、时长（→工作计划）
  • 实施人员（→工作计划）

Work Plan

工作计划

Purpose: Implementation task management and progress tracking
Includes:
  • Task breakdown and dependencies (maximum 2 levels)
  • Schedule and duration estimates
  • Copy E2E verification procedures from Design Doc (cannot delete, can add)
  • Phase 4 Quality Assurance Phase (required)
  • Progress records (checkbox format)
Excludes:
  • Technical rationale (->ADR)
  • Design details (->Design Doc)
Phase Division Criteria:
  1. Phase 1: Foundation Implementation - Type definitions, interfaces, test preparation
  2. Phase 2: Core Feature Implementation - Business logic, unit tests
  3. Phase 3: Integration Implementation - External connections, presentation layer
  4. Phase 4: Quality Assurance (Required) - Acceptance criteria achievement, all tests passing, quality checks
Three Elements of Task Completion Definition:
  1. Implementation Complete: Code is functional
  2. Quality Complete: Tests, type checks, linting pass
  3. Integration Complete: Verified connection with other components
目的：实施任务管理与进度跟踪
包含内容：
  • 任务拆分与依赖关系（最多2级）
  • 时间安排与时长估算
  • 从设计文档复制端到端验证流程（不可删除，可补充）
  • 第4阶段：质量保障阶段（必填）
  • 进度记录（复选框格式）
不包含内容：
  • 技术决策理由（→ADR）
  • 设计细节（→设计文档）
阶段划分标准:
  1. 第1阶段：基础实现 - 类型定义、接口、测试准备
  2. 第2阶段：核心功能实现 - 业务逻辑、单元测试
  3. 第3阶段：集成实现 - 外部连接、展示层
  4. 第4阶段：质量保障（必填） - 达成验收标准、所有测试通过、质量检查
任务完成定义三要素:
  1. 实现完成：代码可正常运行
  2. 质量完成：测试、类型检查、代码规范检查通过
  3. 集成完成：已验证与其他组件的连接

Creation Process

创建流程

  1. Problem Analysis: Change scale assessment, ADR condition check
    • Identify explicit and implicit project standards before investigation
  2. ADR Option Consideration (ADR only): Compare 3+ options, specify trade-offs
  3. Creation: Use templates, include measurable conditions
  4. Approval: "Accepted" after review enables implementation
  1. 问题分析：评估变更规模，检查ADR条件
    • 调研前明确显性与隐性项目标准
  2. ADR方案考量（仅ADR）：对比3种及以上方案，明确权衡点
  3. 文档创建：使用模板，包含可量化条件
  4. 审批：审核通过标记为“Accepted”后方可启动实施

Storage Locations

存储位置

DocumentPathNaming ConventionTemplate
PRD
docs/prd/
[feature-name]-prd.md
See prd-template.md
ADR
docs/adr/
ADR-[4-digits]-[title].md
See adr-template.md
Design Doc
docs/design/
[feature-name]-design.md
See design-template.md
Work Plan
docs/plans/
YYYYMMDD-{type}-{description}.md
See plan-template.md
Task File
docs/plans/tasks/
{plan-name}-task-{number}.md
See task-template.md
*Note: Work plans are excluded by 
.gitignore
文档路径命名规范模板
PRD
docs/prd/
[feature-name]-prd.md
参考prd-template.md
ADR
docs/adr/
ADR-[4-digits]-[title].md
参考adr-template.md
设计文档
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
排除

ADR Status

ADR状态

Proposed
-> 
Accepted
-> 
Deprecated
/
Superseded
/
Rejected
Proposed
-> 
Accepted
-> 
Deprecated
/
Superseded
/
Rejected

AI Automation Rules

AI自动化规则

  • 5+ files: Suggest ADR creation
  • Type/data flow change detected: ADR mandatory
  • Check existing ADRs before implementation
  • 涉及5个及以上文件：建议创建ADR
  • 检测到类型/数据流变更：强制要求创建ADR
  • 实施前检查现有ADR

Diagram Requirements

图表要求

Required diagrams for each document (using mermaid notation):
DocumentRequired DiagramsPurpose
PRDUser journey diagram, Scope boundary diagramClarify user experience and scope
ADROption comparison diagram (when needed)Visualize trade-offs
Design DocArchitecture diagram, Data flow diagramUnderstand technical structure
Work PlanPhase structure diagram, Task dependency diagramClarify implementation order
各文档必填图表（使用mermaid语法）：
文档必填图表目的
PRD用户旅程图、范围边界图明确用户体验与范围
ADR方案对比图（必要时）可视化权衡点
设计文档架构图、数据流图理解技术结构
工作计划阶段结构图、任务依赖图明确实施顺序

Common ADR Relationships

通用ADR关联

  1. At creation: Identify common technical areas (logging, error handling, async processing, etc.), reference existing common ADRs
  2. When missing: Consider creating necessary common ADRs
  3. Design Doc: Specify common ADRs in "Prerequisite ADRs" section
  4. Compliance check: Verify design aligns with common ADR decisions
  1. 创建时：识别通用技术领域（日志、错误处理、异步处理等），参考现有通用ADR
  2. 缺失时：考虑创建必要的通用ADR
  3. 设计文档：在“前置ADR”部分指定通用ADR
  4. 合规性检查：验证设计是否符合通用ADR决策

Templates

模板

Templates are available in the 
references/
directory:
  • Design Document template
  • Product Requirements Document template
  • Work Plan template
  • Architecture Decision Record template
  • Task File template
模板存放在
references/
目录下：
  • 设计文档模板
  • 产品需求文档模板
  • 工作计划模板
  • 架构决策记录模板
  • 任务文件模板