Back to Details

doc-flow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-flow (Orchestrator)

doc-flow（编排器）

Purpose

用途

This skill serves as the orchestrator for the AI-Driven Specification-Driven Development (SDD) workflow. It provides:
  1. Skill Selection Guidance: Helps determine which artifact-specific skill to use
  2. Workflow Overview: Complete 15-layer SDD architecture
  3. General SDD Principles: Specification-driven methodology fundamentals
  4. Integration Guidance: How skills work together
For Artifact Creation: Use the specific artifact skill (doc-brd, doc-prd, doc-ears, doc-bdd, doc-adr, doc-sys, doc-req, doc-impl, doc-ctr, doc-spec, doc-tasks, doc-ref, doc-naming).
Authoritative Reference: ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
本skill作为AI驱动的规范驱动开发（SDD）工作流的编排器。它提供以下功能：
  1. 技能选择指导：帮助确定应使用哪个特定工件的skill
  2. 工作流概览：完整的15层SDD架构
  3. 通用SDD原则：规范驱动方法论基础
  4. 集成指导：各skill如何协同工作
工件创建说明：请使用特定工件skill（doc-brd、doc-prd、doc-ears、doc-bdd、doc-adr、doc-sys、doc-req、doc-impl、doc-ctr、doc-spec、doc-tasks、doc-ref、doc-naming）。
权威参考文档：ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md

Prerequisites

前置条件

⚠️ For New Projects (Greenfield): If starting a brand new project with no existing folder structure, use the 
project-init
 skill FIRST to initialize project structure, select domain, create folders, and configure setup. Then return here to begin workflow execution.
For Existing Projects: If project is already initialized (docs/ folders exist, domain configured), proceed directly with this skill.
⚠️ 新项目（全新项目）：如果启动一个没有现有文件夹结构的全新项目，请首先使用
project-init
skill初始化项目结构、选择领域、创建文件夹并配置设置。之后再回到这里开始执行工作流。
现有项目：如果项目已完成初始化（存在docs/文件夹，领域已配置），可直接使用本skill。

Skill Selection Decision Tree

技能选择决策树

"Which Skill Do I Need?"

"我需要使用哪个Skill？"

Answer these questions to find the right skill:
Q1: What stage are you at in the workflow?
  • Starting new project with business requirements → Use 
    doc-brd
    skill
  • Have BRD, need product requirements → Use 
    doc-prd
    skill
  • Have PRD, need formal requirements → Use 
    doc-ears
    skill
  • Have EARS, need test scenarios → Use 
    doc-bdd
    skill
  • Have BDD, need architecture decisions → Use 
    doc-adr
    skill
  • Have ADR, need system requirements → Use 
    doc-sys
    skill
  • Have SYS, need atomic requirements → Use 
    doc-req
    skill
  • Have REQ, need implementation planning → Use 
    doc-impl
    skill (if complex) or skip to 
    doc-spec
  • Have REQ/IMPL, need API contracts → Use 
    doc-ctr
    skill (if interface requirement)
  • Have REQ/CTR, need technical specifications → Use 
    doc-spec
    skill
  • Have SPEC, need task breakdown → Use 
    doc-tasks
    skill
  • Have TASKS, need implementation contracts → Add Section 8 to TASKS (see 
    doc-tasks
    skill)
  • Have TASKS, ready to code → Implement code per TASKS
  • Need supplementary documentation (overview, glossary, guides) → Use 
    doc-ref
    skill
Q2: What are you trying to do?
  • Define business needs and objectives → 
    doc-brd
  • Define product features and KPIs → 
    doc-prd
  • Write formal WHEN-THE-SHALL-WITHIN requirements → 
    doc-ears
  • Create Gherkin test scenarios → 
    doc-bdd
  • Document architecture decisions → 
    doc-adr
  • Define system requirements → 
    doc-sys
  • Define atomic requirements → 
    doc-req
  • Plan project implementation (WHO/WHEN/WHAT) → 
    doc-impl
  • Define API contracts → 
    doc-ctr
  • Write technical specifications → 
    doc-spec
  • Break down into AI tasks → 
    doc-tasks
  • Define implementation contracts for parallel dev → Add Section 8 to TASKS (see 
    doc-tasks
    skill)
  • Create supplementary documentation (project overview, glossary, guides) → 
    doc-ref
  • General guidance or unsure → Stay with 
    doc-flow
    (this skill)
回答以下问题以找到合适的skill：
问题1：你处于工作流的哪个阶段？
  • 启动新项目并具备业务需求 → 使用
    doc-brd
    skill
  • 已有BRD，需要产品需求 → 使用
    doc-prd
    skill
  • 已有PRD，需要正式需求 → 使用
    doc-ears
    skill
  • 已有EARS，需要测试场景 → 使用
    doc-bdd
    skill
  • 已有BDD，需要架构决策文档 → 使用
    doc-adr
    skill
  • 已有ADR，需要系统需求 → 使用
    doc-sys
    skill
  • 已有SYS，需要原子需求 → 使用
    doc-req
    skill
  • 已有REQ，需要实施规划 → 使用
    doc-impl
    skill（如果项目复杂）或直接跳至
    doc-spec
  • 已有REQ/IMPL，需要API契约 → 使用
    doc-ctr
    skill（如果有接口需求）
  • 已有REQ/CTR，需要技术规范 → 使用
    doc-spec
    skill
  • 已有SPEC，需要任务拆分 → 使用
    doc-tasks
    skill
  • 已有TASKS，需要实施契约 → 在TASKS中添加第8节（参考
    doc-tasks
    skill）
  • 已有TASKS，准备编码 → 根据TASKS实现代码
  • 需要补充文档（概览、术语表、指南） → 使用
    doc-ref
    skill
问题2：你想要完成什么工作？
  • 定义业务需求与目标 → 
    doc-brd
  • 定义产品功能与KPI → 
    doc-prd
  • 编写正式的WHEN-THE-SHALL-WITHIN需求 → 
    doc-ears
  • 创建Gherkin测试场景 → 
    doc-bdd
  • 记录架构决策 → 
    doc-adr
  • 定义系统需求 → 
    doc-sys
  • 定义原子需求 → 
    doc-req
  • 规划项目实施（谁/何时/做什么） → 
    doc-impl
  • 定义API契约 → 
    doc-ctr
  • 编写技术规范 → 
    doc-spec
  • 拆分为AI任务 → 
    doc-tasks
  • 定义并行开发的实施契约 → 在TASKS中添加第8节（参考
    doc-tasks
    skill）
  • 创建补充文档（项目概览、术语表、指南） → 
    doc-ref
  • 需要通用指导或不确定 → 继续使用
    doc-flow
    （本skill）

Complete SDD Workflow (15 Layers)

完整SDD工作流（15层）

Authoritative Reference: ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md
权威参考文档：ai_dev_flow/SPEC_DRIVEN_DEVELOPMENT_GUIDE.md

Workflow Sequence

工作流顺序

Strategy (Layer 0)
  ↓
BRD (Layer 1) → doc-brd skill
  ↓
PRD (Layer 2) → doc-prd skill
  ↓
EARS (Layer 3) → doc-ears skill
  ↓
BDD (Layer 4) → doc-bdd skill
  ↓
ADR (Layer 5) → doc-adr skill
  ↓
SYS (Layer 6) → doc-sys skill
  ↓
REQ (Layer 7) → doc-req skill
  ↓
IMPL (Layer 8) [OPTIONAL] → doc-impl skill
  ↓
CTR (Layer 9) [OPTIONAL - IF INTERFACE] → doc-ctr skill
  ↓
SPEC (Layer 10) → doc-spec skill
  ↓
TASKS (Layer 11) → doc-tasks skill
  ↓
Code (Layer 12)
  ↓
Tests (Layer 13)
  ↓
Validation (Layer 14)
Strategy (Layer 0)
  ↓
BRD (Layer 1) → doc-brd skill
  ↓
PRD (Layer 2) → doc-prd skill
  ↓
EARS (Layer 3) → doc-ears skill
  ↓
BDD (Layer 4) → doc-bdd skill
  ↓
ADR (Layer 5) → doc-adr skill
  ↓
SYS (Layer 6) → doc-sys skill
  ↓
REQ (Layer 7) → doc-req skill
  ↓
IMPL (Layer 8) [可选] → doc-impl skill
  ↓
CTR (Layer 9) [可选 - 如有接口需求] → doc-ctr skill
  ↓
SPEC (Layer 10) → doc-spec skill
  ↓
TASKS (Layer 11) → doc-tasks skill
  ↓
Code (Layer 12)
  ↓
Tests (Layer 13)
  ↓
Validation (Layer 14)

Layer Descriptions

各层说明

LayerArtifactPurposeSkill
0StrategyBusiness owner documentsExternal (strategy/)
1BRDBusiness requirements
doc-brd
2PRDProduct requirements
doc-prd
3EARSFormal requirements (WHEN-THE-SHALL)
doc-ears
4BDDGherkin test scenarios
doc-bdd
5ADRArchitecture decisions
doc-adr
6SYSSystem requirements
doc-sys
7REQAtomic requirements
doc-req
8IMPLImplementation plans (WHO/WHEN) [OPTIONAL]
doc-impl
9CTRAPI contracts [OPTIONAL - IF INTERFACE]
doc-ctr
10SPECTechnical specifications (HOW)
doc-spec
11TASKSTask breakdown for implementation
doc-tasks
11+ICONImplementation Contracts (Section 8 of TASKS)
doc-tasks
12CodePython implementationImplementation
13TestsTest suitesImplementation
14ValidationBDD + contract + traceabilityValidation
层级工件用途Skill
0Strategy业务所有者文档外部（strategy/）
1BRD业务需求
doc-brd
2PRD产品需求
doc-prd
3EARS正式需求（WHEN-THE-SHALL格式）
doc-ears
4BDDGherkin测试场景
doc-bdd
5ADR架构决策
doc-adr
6SYS系统需求
doc-sys
7REQ原子需求
doc-req
8IMPL实施计划（谁/何时）[可选]
doc-impl
9CTRAPI契约 [可选 - 如有接口需求]
doc-ctr
10SPEC技术规范（如何实现）
doc-spec
11TASKS实施任务拆分
doc-tasks
11+ICON实施契约（TASKS第8节）
doc-tasks
12CodePython实现开发人员实施
13Tests测试套件开发人员实施
14ValidationBDD + 契约 + 可追溯性验证验证环节

Optional Layers Decision Logic

可选层级决策逻辑

When to Create IMPL (Layer 8):
  • Create IMPL When: Duration ≥2 weeks, teams ≥3, components ≥5, critical budget/timeline, external dependencies
  • Skip IMPL When: Single component, duration <2 weeks, single developer, low risk
  • Reference: ai_dev_flow/WHEN_TO_CREATE_IMPL.md
When to Create CTR (Layer 9):
  • Create CTR When: Public APIs, event schemas, data models, version compatibility requirements, interface between components
  • Skip CTR When: Internal logic only, no external interface, no serialization
  • Reference: ai_dev_flow/WHEN_TO_CREATE_IMPL.md#when-to-create-ctr-after-impl
何时创建IMPL（第8层）:
  • 应创建IMPL的场景: 项目周期≥2周、团队规模≥3人、组件数量≥5、预算/时间线关键、存在外部依赖
  • 可跳过IMPL的场景: 单一组件、周期<2周、单人开发、低风险项目
  • 参考文档: ai_dev_flow/WHEN_TO_CREATE_IMPL.md
何时创建CTR（第9层）:
  • 应创建CTR的场景: 公共API、事件 schema、数据模型、版本兼容性要求、组件间接口
  • 可跳过CTR的场景: 仅内部逻辑、无外部接口、无需序列化
  • 参考文档: ai_dev_flow/WHEN_TO_CREATE_IMPL.md#when-to-create-ctr-after-impl

General SDD Principles

通用SDD原则

1. Specification-Driven Development Philosophy

1. 规范驱动开发理念

Core Principle: Formalize before implementing
  • Traditional Approach: Code first, document later (or never)
  • SDD Approach: Document first, generate code from specifications
Why SDD Works:
  • Clarity: Requirements are explicit before coding begins
  • Traceability: Every line of code traces to business requirements
  • Validation: Tests defined before implementation
  • Consistency: Templates ensure uniform structure
  • Speed: Code generation from YAML specifications (48x faster)
核心原则: 先规范化，再实施
  • 传统方式: 先编码，后文档（或从不文档）
  • SDD方式: 先文档，再从规范生成代码
SDD的优势:
  • 清晰性: 编码前需求已明确
  • 可追溯性: 每一行代码都可追溯到业务需求
  • 可验证性: 测试在实施前已定义
  • 一致性: 模板确保统一结构
  • 高效性: 从YAML规范生成代码（速度提升48倍）

2. Information Flow Hierarchy

2. 信息流层级

Changes flow DOWN (never UP):
strategy/ (WHAT - Product Owner Voice)
    ├── Strategy business logic
    └── Performance targets
              ↓
              ↓ Referenced by
              ↓
📚 docs/ (WHY + HOW - Project Documentation)
    ├── Requirements (WHY)
    ├── Architecture (HOW)
    └── Specifications (IMPLEMENTATION)
              ↓
              ↓ Generates
              ↓
💻 Source Code (Python/Infrastructure)

📝 ai_dev_flow/ feeds into 📚 docs/ for consistency
Golden Rules:
  • Strategy → Documentation → Code (one-way flow)
  • Code cannot change strategy
  • Always use templates from 
    ai_dev_flow/
    when creating docs in 
    docs/
  • All business logic must reference 
    strategy/
    sections
变更仅向下流动（绝不向上）:
strategy/ (做什么 - 产品负责人视角)
    ├── 业务策略逻辑
    └── 绩效目标
              ↓
              ↓ 被引用
              ↓
📚 docs/ (为什么 + 怎么做 - 项目文档)
    ├── 需求（为什么）
    ├── 架构（怎么做）
    └── 规范（实施细节）
              ↓
              ↓ 生成
              ↓
💻 源代码（Python/基础设施）

📝 ai_dev_flow/ 为 📚 docs/ 提供内容以保持一致性
黄金规则:
  • 策略 → 文档 → 代码（单向流动）
  • 代码不能改变策略
  • 在docs/中创建文档时，必须使用ai_dev_flow/中的模板
  • 所有业务逻辑必须引用strategy/中的章节

3. Directory Structure and Roles

3. 目录结构与角色

Critical Context: This project has three key directories with distinct roles:
关键背景: 本项目有三个核心目录，各有明确角色:

strategy/
- WHAT (Product Owner Voice)

strategy/
- 做什么（产品负责人视角）

Primary Authority: Authoritative business strategy and domain logic
  • core_algorithm.md
    - Primary algorithm specifications
  • strategy_overview.md
    - Strategic framework and operating modes
  • risk_management.md
    - Risk management policies
  • business_rules.md
    - Domain-specific business rules
  • selection_criteria/
    - Entry criteria and scoring algorithms
  • Performance targets, state machines, resource budgets
Golden Rule: All business logic must trace back to these strategy documents.
主要权威: 权威业务策略与领域逻辑
  • core_algorithm.md
    - 核心算法规范
  • strategy_overview.md
    - 战略框架与运营模式
  • risk_management.md
    - 风险管理政策
  • business_rules.md
    - 领域特定业务规则
  • selection_criteria/
    - 准入标准与评分算法
  • 绩效目标、状态机、资源预算
黄金规则: 所有业务逻辑必须可追溯到这些策略文档。

📚 
docs/
- PROJECT DOCUMENTATION

📚 
docs/
- 项目文档

Implementation Documentation: Requirements, architecture, specifications
  • docs/BRD/
    - Business Requirements Documents
    • Nested folder structure: 
      docs/BRD/BRD-NN/BRD-NN.S_slug.md
  • docs/PRD/
    - Product Requirements Documents
    • Nested folder structure: 
      docs/PRD/PRD-NN/PRD-NN.S_slug.md
  • docs/ADR/
    - Architecture Decision Records (HOW)
    • Nested folder structure: 
      docs/ADR/ADR-NN/ADR-NN.S_slug.md
  • docs/BDD/
    - BDD acceptance tests (Behavior-Driven Development)
  • docs/CTR/
    - API Contracts (dual-file format: .md + .yaml)
  • docs/IMPL/
    - Implementation Plans (Project Management: WHO/WHEN)
  • docs/SPEC/
    - YAML technical specifications
  • docs/TASKS/
    - Code Generation Plans (AI-structured implementation tasks)
Note: BRD, PRD, ADR use section-based nested folders by default. Other types use flat structure.
Purpose: Document how strategy is implemented through architecture and code.
实施文档: 需求、架构、规范
  • docs/BRD/
    - 业务需求文档
    • 嵌套文件夹结构: 
      docs/BRD/BRD-NN/BRD-NN.S_slug.md
  • docs/PRD/
    - 产品需求文档
    • 嵌套文件夹结构: 
      docs/PRD/PRD-NN/PRD-NN.S_slug.md
  • docs/ADR/
    - 架构决策记录（怎么做）
    • 嵌套文件夹结构: 
      docs/ADR/ADR-NN/ADR-NN.S_slug.md
  • docs/BDD/
    - BDD验收测试（行为驱动开发）
  • docs/CTR/
    - API契约（双文件格式: .md + .yaml）
  • docs/IMPL/
    - 实施计划（项目管理: 谁/何时）
  • docs/SPEC/
    - YAML技术规范
  • docs/TASKS/
    - 代码生成计划（AI结构化实施任务）
注意: BRD、PRD、ADR默认使用基于章节的嵌套文件夹结构。其他类型使用扁平结构。
用途: 记录如何通过架构和代码实现策略。

📝 
ai_dev_flow/
- AUTHORITATIVE DEVELOPMENT STANDARD

📝 
ai_dev_flow/
- 权威开发标准

Development Standard and Templates: The single source of truth for SDD workflow
  • Status: Authoritative development standard for this project
  • Contents: Complete SDD workflow (BRD → PRD → EARS → BDD → ADR → SYS → REQ → IMPL → CTR → SPEC → TASKS → Code)
  • Templates: 
    {TYPE}-TEMPLATE.{ext}
    for each artifact type (BRD, PRD, EARS, BDD, ADR, SYS, REQ, IMPL, CTR, SPEC, TASKS, REF)
  • Indices: 
    {TYPE}-00_index.{ext}
    listing all documents of each type
  • READMEs: Detailed usage guides and best practices for each artifact type
  • Standards: ID naming, traceability format, cross-referencing rules
  • Examples: Reference implementations with full traceability chains
Purpose: Define the complete development methodology with templates, standards, and examples for creating all artifacts.
开发标准与模板: SDD工作流的唯一事实来源
  • 状态: 本项目的权威开发标准
  • 内容: 完整SDD工作流（BRD → PRD → EARS → BDD → ADR → SYS → REQ → IMPL → CTR → SPEC → TASKS → 代码）
  • 模板: 每种工件类型的
    {TYPE}-TEMPLATE.{ext}
    （BRD、PRD、EARS、BDD、ADR、SYS、REQ、IMPL、CTR、SPEC、TASKS、REF）
  • 索引: 
    {TYPE}-00_index.{ext}
    列出每种类型的所有文档
  • READMEs: 每种工件类型的详细使用指南与最佳实践
  • 标准: ID命名、可追溯性格式、交叉引用规则
  • 示例: 具有完整可追溯链的参考实现
用途: 通过模板、标准和示例定义完整开发方法论，用于创建所有工件。

⚠️ CRITICAL: Archived Documents Restriction

⚠️ 关键：归档文档限制

STRICTLY PROHIBITED: DO NOT access, reference, link to, or use ANY files or directories containing the word "archived" in their path.
Automatic Filtering Rules:
  • ❌ Skip any path containing 
    archived
    , 
    Archived
    , 
    ARCHIVED
    , or 
    archive
  • ❌ Ignore files in directories with "archived" in the name
  • ❌ Do not read, suggest, or reference archived content
  • ❌ Do not use archived documents even if they appear in search results
Active Documentation Only:
  • strategy/
    (current strategy - excludes archived subdirs)
  • docs/
    (active project documentation)
  • ai_dev_flow/
    (authoritative templates and standards)
If archived content is needed:
  • Stop immediately
  • Inform user that content is in archived location
  • Request explicit permission before proceeding
严格禁止：请勿访问、引用、链接或使用任何路径中包含"archived"字样的文件或目录。
自动过滤规则:
  • ❌ 跳过任何包含
    archived
    、
    Archived
    、
    ARCHIVED
    或
    archive
    的路径
  • ❌ 忽略名称中包含"archived"的目录中的文件
  • ❌ 不要读取、建议或引用归档内容
  • ❌ 即使归档内容出现在搜索结果中，也不要使用
仅使用活跃文档:
  • strategy/
    （当前策略 - 排除归档子目录）
  • docs/
    （活跃项目文档）
  • ai_dev_flow/
    （权威模板与标准）
如果需要归档内容:
  • 立即停止
  • 告知用户内容位于归档位置
  • 在继续前请求明确许可

4. Traceability Importance

4. 可追溯性的重要性

Complete Audit Trail: Every artifact must trace back to original business requirements
Benefits:
  • Impact Analysis: Know what breaks when requirements change
  • Regulatory Compliance: Industry-specific audit requirements (ISO, SOC2, etc.)
  • Change Management: Track all changes through artifact chain
  • Coverage Metrics: Measure implementation completeness
  • Quality Assurance: Automated validation prevents gaps
Implementation:
  • Cumulative tagging hierarchy (see SHARED_CONTENT.md)
  • Traceability section in every document
  • Bidirectional traceability matrices
  • Automated validation scripts
完整审计跟踪: 每个工件必须可追溯到原始业务需求
优势:
  • 影响分析: 了解需求变更时哪些部分会受影响
  • 合规性: 满足行业特定审计要求（ISO、SOC2等）
  • 变更管理: 跟踪所有变更的工件链
  • 覆盖指标: 衡量实施完整性
  • 质量保证: 自动化验证防止遗漏
实现方式:
  • 累积标签层级（参考SHARED_CONTENT.md）
  • 每个文档中的可追溯性章节
  • 双向可追溯性矩阵
  • 自动化验证脚本

5. Upstream Artifact Policy (CRITICAL)

5. 上游工件政策（关键）

⚠️ MANDATORY RULE: Do NOT create missing upstream artifacts. Skip functionality instead.
Policy Statement: If a required upstream artifact is missing, the downstream functionality MUST NOT be implemented. This enforces the SDD document hierarchy where every implementation must have proper business/product justification through the complete artifact chain.
Decision Rules:
SituationAction
Upstream existsReference with exact document ID
Upstream required but missingSkip that functionality - do NOT implement
Upstream optional and missingUse 
null
in traceability tag
Upstream not applicableOmit tag entirely
Rationale:
  • Prevents orphaned code: No implementation without business justification
  • Enforces governance: Changes must flow through proper channels
  • Maintains audit trail: Every feature traces to business need
  • Reduces technical debt: No undocumented "nice-to-have" features
When Upstream is Missing:
  1. Stop - Do not proceed with implementation
  2. Report - Inform user which upstream artifact is missing
  3. Advise - Recommend creating upstream artifacts first through proper channels
  4. Skip - Move on to functionality that has complete upstream chain
Reference: ai_dev_flow/TRACEABILITY.md - Section "Step 3: Decision Rules"
⚠️ 强制规则: 不要创建缺失的上游工件。应跳过相关功能。
政策声明: 如果所需上游工件缺失，下游功能不得实施。这强制执行SDD文档层级，即每个实施必须通过完整工件链具备适当的业务/产品依据。
决策规则:
场景操作
上游工件存在使用精确文档ID引用
上游工件必需但缺失跳过该功能 - 不得实施
上游工件可选且缺失在可追溯性标签中使用
null
上游工件不适用完全省略标签
原理:
  • 防止孤立代码: 没有业务依据的实施不得存在
  • 强制执行治理: 变更必须通过适当渠道流转
  • 保持审计跟踪: 每个功能都可追溯到业务需求
  • 减少技术债务: 没有无文档的"锦上添花"功能
当上游工件缺失时:
  1. 停止 - 不要继续实施
  2. 报告 - 告知用户缺失的上游工件
  3. 建议 - 建议首先通过适当渠道创建上游工件
  4. 跳过 - 转向具备完整上游链的功能
参考文档: ai_dev_flow/TRACEABILITY.md - "步骤3：决策规则"章节

Integration with Other Skills

与其他Skill的集成

Core Workflow Skills

核心工作流Skill

project-init
 - Initialize new project structure
  • Use BEFORE doc-flow for greenfield projects
  • Creates folder structure, domain setup, baseline files
  • Reference: 
    .claude/skills/project-init/SKILL.md
trace-check
 - Validate traceability after artifact creation
  • Use AFTER doc-flow to verify bidirectional links
  • Validates cumulative tagging, ID formats, link resolution
  • Detects orphaned artifacts and traceability gaps
  • Reference: 
    .claude/skills/trace-check/SKILL.md
doc-naming
 - Unified ID naming standards enforcement
  • Use for ID format validation across all artifact types
  • Validates 4-segment element IDs (TYPE.NN.TT.SS)
  • Enforces variable-length DOC_NUM (2+ digits)
  • Reference: 
    .claude/skills/doc-naming/SKILL.md
doc-validator
 - Cross-document validation orchestrator
  • Validates traceability across all layers
  • Detects gaps, broken links, and format violations
  • Runs auto-fix actions for common issues
  • Reference: 
    .claude/skills/doc-validator/SKILL.md
project-init
 - 初始化新项目结构
  • 对于全新项目，在doc-flow之前使用
  • 创建文件夹结构、领域设置、基线文件
  • 参考: 
    .claude/skills/project-init/SKILL.md
trace-check
 - 工件创建后验证可追溯性
  • 在doc-flow之后使用，验证双向链接
  • 验证累积标签、ID格式、链接解析
  • 检测孤立工件和可追溯性缺口
  • 参考: 
    .claude/skills/trace-check/SKILL.md
doc-naming
 - 统一ID命名标准强制执行
  • 用于验证所有工件类型的ID格式
  • 验证4段元素ID（TYPE.NN.TT.SS）
  • 强制执行可变长度DOC_NUM（2位以上）
  • 参考: 
    .claude/skills/doc-naming/SKILL.md
doc-validator
 - 跨文档验证编排器
  • 验证所有层级的可追溯性
  • 检测缺口、断链和格式违规
  • 对常见问题运行自动修复操作
  • 参考: 
    .claude/skills/doc-validator/SKILL.md

Planning & Architecture

规划与架构

adr-roadmap
 - Generate implementation roadmaps from ADRs
  • Use AFTER creating ADR artifacts
  • Creates timeline, risk assessment, dependency mapping
  • Reference: 
    .claude/skills/adr-roadmap/SKILL.md
project-mngt
 - MVP/MMP/MMR planning
  • Use for strategic release planning
  • Integrates with IMPL artifacts
  • Reference: 
    .claude/skills/project-mngt/SKILL.md
adr-roadmap
 - 从ADR生成实施路线图
  • 创建ADR工件后使用
  • 创建时间线、风险评估、依赖映射
  • 参考: 
    .claude/skills/adr-roadmap/SKILL.md
project-mngt
 - MVP/MMP/MMR规划
  • 用于战略发布规划
  • 与IMPL工件集成
  • 参考: 
    .claude/skills/project-mngt/SKILL.md

Typical Workflow Integration

典型工作流集成

text
1. project-init    → Initialize project (greenfield only)
2. doc-brd         → Create BRD
3. doc-prd         → Create PRD
4. doc-ears        → Create EARS
5. doc-bdd         → Create BDD
6. doc-adr         → Create ADR
7. doc-sys         → Create SYS
8. doc-req         → Create REQ
9. doc-impl        → Create IMPL (if complex)
10. doc-ctr        → Create CTR (if interface)
11. doc-spec       → Create SPEC
12. doc-tasks      → Create TASKS
13. Implementation → Execute based on TASKS
14. trace-check    → Validate traceability
text
1. project-init    → 初始化项目（仅全新项目）
2. doc-brd         → 创建BRD
3. doc-prd         → 创建PRD
4. doc-ears        → 创建EARS
5. doc-bdd         → 创建BDD
6. doc-adr         → 创建ADR
7. doc-sys         → 创建SYS
8. doc-req         → 创建REQ
9. doc-impl        → 创建IMPL（如果项目复杂）
10. doc-ctr        → 创建CTR（如果有接口需求）
11. doc-spec       → 创建SPEC
12. doc-tasks      → 创建TASKS
13. Implementation → 根据TASKS执行
14. trace-check    → 验证可追溯性

Shared Standards

共享标准

CRITICAL: All artifact-specific skills share common standards defined in:
.claude/skills/doc-flow/SHARED_CONTENT.md
This document contains:
  1. Document ID Naming Standards
  2. Traceability Section Format
  3. Cumulative Tagging Hierarchy
  4. Quality Gates & Validation
  5. Traceability Matrix Enforcement
  6. Documentation Standards
  7. Document Control Section Requirements
All artifact skills (doc-brd through doc-tasks, plus doc-ref, doc-naming) import these shared standards.
关键: 所有特定工件skill共享以下位置定义的通用标准：
.claude/skills/doc-flow/SHARED_CONTENT.md
该文档包含:
  1. 文档ID命名标准
  2. 可追溯性章节格式
  3. 累积标签层级
  4. 质量门与验证
  5. 可追溯性矩阵强制执行
  6. 文档标准
  7. 文档控制章节要求
所有工件skill（doc-brd至doc-tasks，以及doc-ref、doc-naming）均导入这些共享标准。

Diagram Standards (Global Requirement)

图表标准（全局要求）

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited.
  • Authority Document: 
    ai_dev_flow/DIAGRAM_STANDARDS.md
  • Syntax Generation: 
    mermaid-gen
    skill
  • File Management: 
    charts-flow
    skill (SVG conversion, embedding)
Allowed Exception: Directory tree structures (using 
├── └── │
) are permitted as they represent file structure, not diagrams.
所有图表必须使用Mermaid语法。禁止使用基于文本的图表（ASCII艺术、框式绘图）。
  • 权威文档: 
    ai_dev_flow/DIAGRAM_STANDARDS.md
  • 语法生成: 
    mermaid-gen
    skill
  • 文件管理: 
    charts-flow
    skill（SVG转换、嵌入）
允许的例外: 目录树结构（使用
├── └── │
）是允许的，因为它们代表文件结构，而非图表。

Validation Overview

验证概览

Automated Validation Tools

自动化验证工具

Quality Gates Validation:
bash
undefined
质量门验证:
bash
undefined

Validate artifact meets layer transition requirements (≥90%)

验证工件是否满足层级转换要求（≥90%）

./scripts/validate_quality_gates.sh docs/REQ/risk/lim/REQ-03.md
./scripts/validate_quality_gates.sh docs/REQ/risk/lim/REQ-03.md

Artifact-specific validation

特定工件验证

./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01.md ./ai_dev_flow/scripts/validate_req_template.sh docs/REQ/api/ib/REQ-02.md
./ai_dev_flow/scripts/validate_brd_template.sh docs/BRD/BRD-01.md ./ai_dev_flow/scripts/validate_req_template.sh docs/REQ/api/ib/REQ-02.md

Link integrity validation

链接完整性验证

./ai_dev_flow/scripts/validate_links.py --path docs/ --check-anchors

**Tag-Based Traceability Validation:**
```bash
./ai_dev_flow/scripts/validate_links.py --path docs/ --check-anchors

**基于标签的可追溯性验证:**
```bash

Complete workflow (extract → validate → generate)

完整工作流（提取 → 验证 → 生成）

python ai_dev_flow/scripts/generate_traceability_matrices.py --auto
python ai_dev_flow/scripts/generate_traceability_matrices.py --auto

Individual steps

单独步骤

python ai_dev_flow/scripts/extract_tags.py --source src/ docs/ tests/ python ai_dev_flow/scripts/validate_tags_against_docs.py --strict python ai_dev_flow/scripts/generate_traceability_matrices.py --output docs/generated/matrices/

---
python ai_dev_flow/scripts/extract_tags.py --source src/ docs/ tests/ python ai_dev_flow/scripts/validate_tags_against_docs.py --strict python ai_dev_flow/scripts/generate_traceability_matrices.py --output docs/generated/matrices/

---

Cross-Document Validation (MANDATORY)

跨文档验证（强制）

CRITICAL: After creating each artifact, execute cross-document validation before proceeding to the next layer.
关键: 创建每个工件后，在进入下一层级前必须执行跨文档验证。

Validation Phases

验证阶段

PhaseTriggerCommand
Phase 1Per-document
python scripts/validate_cross_document.py --document {doc_path} --auto-fix
Phase 2Per-layer complete
python scripts/validate_cross_document.py --layer {LAYER} --auto-fix
Phase 3Final (all layers)
python scripts/validate_cross_document.py --full --auto-fix
阶段触发条件命令
阶段1单文档验证
python scripts/validate_cross_document.py --document {doc_path} --auto-fix
阶段2整层完成验证
python scripts/validate_cross_document.py --layer {LAYER} --auto-fix
阶段3最终验证（所有层级）
python scripts/validate_cross_document.py --full --auto-fix

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed to next layer
循环:
  1. 运行: python scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复: 回到循环（重新验证）
  3. 如果警告已修复: 回到循环（重新验证）
  4. 如果存在无法修复的问题: 记录以便人工审核，继续
  5. 如果验证通过: 标记为已验证，进入下一层级

Layer-Specific Upstream Requirements

各层级特定上游需求

LayerArtifactRequired Upstream TagsTag Count
1BRD(none - root)0
2PRD@brd1
3EARS@brd, @prd2
4BDD@brd, @prd, @ears3
5ADR@brd, @prd, @ears, @bdd4
6SYS@brd, @prd, @ears, @bdd, @adr5
7REQ@brd, @prd, @ears, @bdd, @adr, @sys6
8IMPL@brd, @prd, @ears, @bdd, @adr, @sys, @req7
9CTR@brd through @req (+ optional @impl)7-8
10SPEC@brd through @req (+ optional @impl, @ctr)7-9
11TASKS@brd through @spec (+ optional @impl, @ctr)8-10
层级工件必需上游标签标签数量
1BRD（无 - 根节点）0
2PRD@brd1
3EARS@brd, @prd2
4BDD@brd, @prd, @ears3
5ADR@brd, @prd, @ears, @bdd4
6SYS@brd, @prd, @ears, @bdd, @adr5
7REQ@brd, @prd, @ears, @bdd, @adr, @sys6
8IMPL@brd, @prd, @ears, @bdd, @adr, @sys, @req7
9CTR@brd至@req（+ 可选@impl）7-8
10SPEC@brd至@req（+ 可选@impl, @ctr）7-9
11TASKS@brd至@spec（+ 可选@impl, @ctr）8-10

Auto-Fix Actions (No Confirmation Required)

自动修复操作（无需确认）

IssueFix Action
Missing cumulative tagAdd with upstream document reference
Invalid tag formatCorrect to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken linkRecalculate path from current location
Missing traceability sectionInsert from template
问题修复操作
缺失累积标签添加并引用上游文档
无效标签格式修正为TYPE.NN.TT.SS（4段）或TYPE-NN格式
断链从当前位置重新计算路径
缺失可追溯性章节从模板插入

Validation Codes Reference

验证代码参考

CodeDescriptionSeverity
XDOC-001Referenced requirement ID not foundERROR
XDOC-002Missing cumulative tagERROR
XDOC-003Upstream document not foundERROR
XDOC-004Link target file missingWARNING
XDOC-005Anchor in link not foundWARNING
XDOC-006Tag format invalidERROR
XDOC-007Gap in cumulative tag chainERROR
XDOC-008Circular reference detectedERROR
XDOC-009Missing traceability sectionERROR
XDOC-010Orphaned document (no upstream refs)WARNING
代码描述严重程度
XDOC-001引用的需求ID未找到错误
XDOC-002缺失累积标签错误
XDOC-003上游文档未找到错误
XDOC-004链接目标文件缺失警告
XDOC-005链接中的锚点未找到警告
XDOC-006标签格式无效错误
XDOC-007累积标签链存在缺口错误
XDOC-008检测到循环引用错误
XDOC-009缺失可追溯性章节错误
XDOC-010孤立文档（无上游引用）警告

Quality Gate

质量门

Blocking: YES - Cannot proceed to next layer until Phase 1 validation passes with 0 errors for the current artifact.
阻塞: 是 - 当前工件的阶段1验证必须通过且无错误，才能进入下一层级。

Related Resources

相关资源

Core Standards (ai_dev_flow/)

核心标准（ai_dev_flow/）

Primary References - Authoritative Development Standard:
  • Main Guide: SPEC_DRIVEN_DEVELOPMENT_GUIDE.md - Complete 15-layer workflow
  • Workflow Diagram: index.md - Complete Mermaid diagram
  • ID Standards: ID_NAMING_STANDARDS.md - File naming, ID format rules
  • Traceability: TRACEABILITY.md - Cross-reference format, link standards
  • Quality Gates: TRACEABILITY_VALIDATION.md - Automated quality gates system
  • Platform BRD Guide: PLATFORM_VS_FEATURE_BRD.md - Platform vs Feature BRD decision guide
  • When to Create IMPL: WHEN_TO_CREATE_IMPL.md - IMPL vs direct REQ→SPEC decision guide
  • README: README.md - Getting started guide
主要参考 - 权威开发标准:
  • 主指南: SPEC_DRIVEN_DEVELOPMENT_GUIDE.md - 完整15层工作流
  • 工作流图表: index.md - 完整Mermaid图表
  • ID标准: ID_NAMING_STANDARDS.md - 文件命名、ID格式规则
  • 可追溯性: TRACEABILITY.md - 交叉引用格式、链接标准
  • 质量门: TRACEABILITY_VALIDATION.md - 自动化质量门系统
  • 平台BRD指南: PLATFORM_VS_FEATURE_BRD.md - 平台型与功能型BRD决策指南
  • 何时创建IMPL: WHEN_TO_CREATE_IMPL.md - IMPL与直接REQ→SPEC的决策指南
  • README: README.md - 入门指南

Templates Location

模板位置

All templates located in 
ai_dev_flow/{artifact_type}/
:
  • BRD (
    BRD/
    ): 3 templates available (comprehensive, simplified, domain-specific)
  • PRD (
    PRD/
    ): 
    PRD-TEMPLATE.md
  • EARS (
    EARS/
    ): 
    EARS-TEMPLATE.md
  • BDD (
    BDD/
    ): 
    BDD-TEMPLATE.feature
  • ADR (
    ADR/
    ): 
    ADR-TEMPLATE.md
    , Technology Stack reference (ADR-000)
  • SYS (
    SYS/
    ): 
    SYS-TEMPLATE.md
  • REQ (
    REQ/
    ): 
    REQ-TEMPLATE.md
    (v3.0 with 12 sections)
  • IMPL (
    IMPL/
    ): 
    IMPL-TEMPLATE.md
  • CTR (
    CTR/
    ): 
    CTR-TEMPLATE.md
    + 
    CTR-TEMPLATE.yaml
    (dual-file)
  • SPEC (
    10_SPEC/
    ): 
    SPEC-TEMPLATE.yaml
  • TASKS (
    TASKS/
    ): 
    TASKS-TEMPLATE.md
    (includes Section 8 for Implementation Contracts)
  • REF (root): 
    REF-TEMPLATE.md
    (Reference Documents)
Each artifact type directory also contains:
  • Index file: 
    {TYPE}-00_index.{ext}
  • README.md: Usage guide and best practices
  • Creation Rules: 
    {TYPE}_CREATION_RULES.md
  • Validation Rules: 
    {TYPE}_VALIDATION_RULES.md
所有模板位于
ai_dev_flow/{artifact_type}/
:
  • BRD (
    BRD/
    ): 提供3种模板（全面版、简化版、领域特定版）
  • PRD (
    PRD/
    ): 
    PRD-TEMPLATE.md
  • EARS (
    EARS/
    ): 
    EARS-TEMPLATE.md
  • BDD (
    BDD/
    ): 
    BDD-TEMPLATE.feature
  • ADR (
    ADR/
    ): 
    ADR-TEMPLATE.md
    、技术栈参考（ADR-000）
  • SYS (
    SYS/
    ): 
    SYS-TEMPLATE.md
  • REQ (
    REQ/
    ): 
    REQ-TEMPLATE.md
    （v3.0，包含12个章节）
  • IMPL (
    IMPL/
    ): 
    IMPL-TEMPLATE.md
  • CTR (
    CTR/
    ): 
    CTR-TEMPLATE.md
    + 
    CTR-TEMPLATE.yaml
    （双文件）
  • SPEC (
    10_SPEC/
    ): 
    SPEC-TEMPLATE.yaml
  • TASKS (
    TASKS/
    ): 
    TASKS-TEMPLATE.md
    （包含实施契约的第8节）
  • REF（根目录）: 
    REF-TEMPLATE.md
    （参考文档）
每种工件类型的目录还包含:
  • 索引文件: 
    {TYPE}-00_index.{ext}
  • README.md: 使用指南与最佳实践
  • 创建规则: 
    {TYPE}_CREATION_RULES.md
  • 验证规则: 
    {TYPE}_VALIDATION_RULES.md

Quick Reference Card

快速参考卡

Decision Matrix

决策矩阵

You HaveYou NeedUse This Skill
NothingBusiness requirements
doc-brd
BRDProduct requirements
doc-prd
PRDFormal requirements
doc-ears
EARSTest scenarios
doc-bdd
BDDArchitecture decisions
doc-adr
ADRSystem requirements
doc-sys
SYSAtomic requirements
doc-req
REQ (complex)Implementation plan
doc-impl
REQ (simple)Technical specs
doc-spec
REQ/IMPL (interface)API contracts
doc-ctr
REQ/CTRTechnical specs
doc-spec
SPECTask breakdown
doc-tasks
TASKSCodeImplement!
Any stageSupplementary documentation
doc-ref
已有工件需要创建使用该Skill
无业务需求
doc-brd
BRD产品需求
doc-prd
PRD正式需求
doc-ears
EARS测试场景
doc-bdd
BDD架构决策
doc-adr
ADR系统需求
doc-sys
SYS原子需求
doc-req
REQ（复杂项目）实施计划
doc-impl
REQ（简单项目）技术规范
doc-spec
REQ/IMPL（有接口）API契约
doc-ctr
REQ/CTR技术规范
doc-spec
SPEC任务拆分
doc-tasks
TASKS代码开始实施！
任意阶段补充文档
doc-ref

Development ROI

开发投资回报率

  • Traditional: 70 hours/component
  • SDD: 1.5 hours/component
  • Speed increase: 48x faster
  • Consistency: 100% (template-based)
  • Traceability: Automatic, bidirectional
  • 传统方式: 70小时/组件
  • SDD方式: 1.5小时/组件
  • 速度提升: 48倍
  • 一致性: 100%（基于模板）
  • 可追溯性: 自动双向追溯

Usage Example

使用示例

User: "I need to implement position risk limit validation"
Assistant: "I'll guide you through the SDD workflow. Let me check what artifacts you have:
Current Status Check:
  • Do you have a BRD documenting business requirements? [If no → SKIP this functionality]
  • Do you have a PRD with product requirements? [If no → SKIP this functionality]
  • Do you have EARS formal requirements? [If no → SKIP this functionality]
  • Do you have BDD test scenarios? [If no → SKIP this functionality]
  • Do you have ADR architecture decisions? [If no → SKIP this functionality]
  • Do you have SYS system requirements? [If no → SKIP this functionality]
  • Do you have REQ atomic requirements? [If no → SKIP this functionality]
⚠️ CRITICAL: Upstream Artifact Policy: If ANY required upstream artifact is missing, do NOT create it and do NOT implement the downstream functionality. The SDD workflow enforces strict document hierarchy - functionality without proper business/product justification should not exist.
Next Steps: Based on your current progress, I'll recommend the appropriate skill to use next. Each skill will guide you through creating that specific artifact type with proper templates, traceability, and validation."
For detailed artifact creation guidance, use the specific artifact skill (doc-brd, doc-prd, doc-ears, doc-bdd, doc-adr, doc-sys, doc-req, doc-impl, doc-ctr, doc-spec, doc-tasks, doc-ref, doc-naming).
用户: "我需要实现头寸风险限额验证"
助理: "我将引导您完成SDD工作流。让我先检查您已有的工件：
当前状态检查:
  • 您是否有记录业务需求的BRD？[如果没有 → 跳过此功能]
  • 您是否有包含产品需求的PRD？[如果没有 → 跳过此功能]
  • 您是否有EARS正式需求？[如果没有 → 跳过此功能]
  • 您是否有BDD测试场景？[如果没有 → 跳过此功能]
  • 您是否有ADR架构决策文档？[如果没有 → 跳过此功能]
  • 您是否有SYS系统需求？[如果没有 → 跳过此功能]
  • 您是否有REQ原子需求？[如果没有 → 跳过此功能]
⚠️ 关键：上游工件政策: 如果任何必需的上游工件缺失，请勿创建它，也请勿实现下游功能。SDD工作流强制执行严格的文档层级——没有适当业务/产品依据的功能不应存在。
下一步: 根据您当前的进度，我将推荐下一步应使用的skill。每个skill将引导您使用正确的模板、可追溯性和验证来创建特定工件。"
如需详细的工件创建指导，请使用特定工件skill（doc-brd、doc-prd、doc-ears、doc-bdd、doc-adr、doc-sys、doc-req、doc-impl、doc-ctr、doc-spec、doc-tasks、doc-ref、doc-naming）。

Version History

版本历史

VersionDateChanges
1.32026-01-17Updated to 15-layer architecture (Layers 0-14)
1.22025-12-29Fixed workflow sequence; Added doc-naming and doc-validator to Integration section
1.12025-11-30Added REF documents, ICON section
1.02025-11-01Initial skill creation
版本日期变更
1.32026-01-17更新为15层架构（层级0-14）
1.22025-12-29修复工作流顺序；在集成部分添加doc-naming和doc-validator
1.12025-11-30添加REF文档、ICON章节
1.02025-11-01初始skill创建