Back to Details

doc-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-spec

doc-spec

Purpose

目的

Create Technical Specifications (SPEC) - Layer 10 artifact in the SDD workflow that defines implementation-ready specifications in YAML format, providing complete technical details for code generation.
Layer: 10
Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6), REQ (Layer 7), IMPL (Layer 8), CTR (Layer 9)
Downstream Artifacts: TASKS (Layer 11), Code (Layer 12)
创建技术规格说明书（SPEC）——SDD流程中的第10层工件，采用YAML格式定义可直接用于实现的规格说明，为代码生成提供完整的技术细节。
层级：10
上游工件：BRD（第1层）、PRD（第2层）、EARS（第3层）、BDD（第4层）、ADR（第5层）、SYS（第6层）、REQ（第7层）、IMPL（第8层）、CTR（第9层）
下游工件：TASKS（第11层）、代码（第12层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ docs/IMPL/ docs/CTR/ 2>/dev/null
  2. Reference only existing documents in traceability tags
  3. Use 
    null
     only when upstream artifact type genuinely doesn't exist
  4. NEVER use placeholders like 
    BRD-XXX
    or 
    TBD
  5. Do NOT create missing upstream artifacts - skip functionality instead
Before creating SPEC, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream REQ: Read atomic requirements (PRIMARY SOURCE)
  3. Upstream CTR: Read contracts if Layer 9 created
  4. Template: 
    ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
  5. Creation Rules: 
    ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md
  6. Validation Rules: 
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  7. Validation Script: 
    ./ai_dev_flow/scripts/validate_spec_template.sh
    (under development - use template for manual validation until available)
在创建本文档之前，您必须：
  1. 列出已有的上游工件：
    bash
    ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ docs/IMPL/ docs/CTR/ 2>/dev/null
  2. 仅在追溯标签中引用已存在的文档
  3. 仅当上游工件类型确实不存在时，才使用
    null
  4. 绝不要使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——而是跳过相关功能
在创建SPEC之前，请阅读：
  1. 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游REQ：阅读原子需求（主要来源）
  3. 上游CTR：如果已创建第9层工件，请阅读合同文档
  4. 模板：
    ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
  5. 创建规则：
    ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md
  6. 验证规则：
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  7. 验证脚本：
    ./ai_dev_flow/scripts/validate_spec_template.sh
    （开发中 - 在可用之前，使用模板进行手动验证）

Reserved ID Exemption (SPEC-00_*)

保留ID豁免（SPEC-00_*）

Scope: Documents with reserved ID 
000
are FULLY EXEMPT from validation.
Pattern: 
SPEC-00_*.md
, 
SPEC-00_*.yaml
Document Types:
  • Index documents (
    SPEC-00_index.md
    )
  • Traceability matrix templates (
    SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
    )
  • Glossaries, registries, checklists
Rationale: Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.
Validation Behavior: Skip all checks when filename matches 
SPEC-00_*
pattern.
范围：ID为
000
的文档完全豁免验证。
模式：
SPEC-00_*.md
、
SPEC-00_*.yaml
文档类型：
  • 索引文档（
    SPEC-00_index.md
    ）
  • 追溯矩阵模板（
    SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
    ）
  • 术语表、注册表、检查清单
理由：ID为000的文档属于框架基础设施（索引、模板、参考资料），而非需要追溯或质量门控的项目工件。
验证行为：当文件名匹配
SPEC-00_*
模式时，跳过所有检查。

When to Use This Skill

何时使用此技能

Use 
doc-spec
when:
  • Have completed BRD through REQ (Layers 1-7)
  • Ready to create implementation-ready specifications
  • Preparing for code generation or implementation
  • Need complete technical details in structured format
  • You are at Layer 10 of the SDD workflow
当满足以下条件时，使用
doc-spec
：
  • 已完成BRD到REQ（第1-7层）的所有工件
  • 准备创建可直接用于实现的规格说明
  • 为代码生成或实施做准备
  • 需要以结构化格式呈现完整的技术细节
  • 处于SDD流程的第10层

SPEC-Specific Guidance

SPEC专属指导

1. YAML Format (MANDATORY)

1. YAML格式（强制要求）

Format: Pure YAML (not markdown)
Structure:
yaml
undefined
格式：纯YAML（非Markdown）
结构：
yaml
undefined

SPEC-NN: [Specification Title]

SPEC-NN: [Specification Title]

metadata: spec_id: SPEC-01 title: "Order Validation Service Specification" version: "1.0.0" created_date: "2025-01-15" updated_date: "2025-01-15" status: "approved" owner: "team-backend" task_ready_score: "✅ 95% (Target: ≥90%)"
cumulative_tags: brd: ["BRD.01.01.03"] prd: ["PRD.01.07.02"] ears: ["EARS.01.25.01"] bdd: ["BDD.01.14.01"] adr: ["ADR-033", "ADR-045"] sys: ["SYS.01.26.01"] req: ["REQ.01.27.01"] impl: ["IMPL.01.29.01"] # optional contracts: ["CTR-01"] # optional
overview: purpose: "Define trade order validation service implementation" scope: "Validate trade orders against position limits and business rules" requirements: - "REQ-risk-limits-01" - "REQ-risk-limits-02"
architecture: pattern: "layered" layers: - name: "controller" technology: "FastAPI" description: "REST API endpoint handlers" - name: "service" technology: "Python" description: "Business logic and validation" - name: "repository" technology: "SQLAlchemy" description: "Database access layer"
interfaces: api_endpoints: - endpoint: "/api/v1/trades/validate" method: "POST" contract_ref: "CTR-01" authentication: "Bearer token" rate_limit: "@threshold: PRD.NN.limit.api.requests_per_second" rate_limit_window: "1min"
data_models: - model: "TradeOrderRequest" schema_ref: "CTR-01#/components/schemas/TradeOrderRequest" - model: "ValidationResponse" schema_ref: "CTR-01#/components/schemas/ValidationResponse"
implementation: modules: - name: "controllers/trade_validation_controller.py" purpose: "API endpoint handlers" dependencies: ["services/trade_validator.py"]
- name: "services/trade_validator.py"
  purpose: "Business logic and validation"
  dependencies:
    - "repositories/position_repository.py"
    - "models/trade_order.py"

- name: "repositories/position_repository.py"
  purpose: "Database access for positions"
  dependencies: ["database/connection.py"]
functions: - name: "validate_trade_order" module: "services/trade_validator.py" signature: "async def validate_trade_order(order: TradeOrderRequest) -> ValidationResponse" purpose: "Validate trade order against all rules" algorithm: - "1. Validate symbol exists" - "2. Check quantity is positive" - "3. Validate price within range" - "4. Check position limits" - "5. Return validation result"
error_handling: error_codes: - code: "INVALID_SYMBOL" http_status: 400 message: "Symbol not found in approved list" recovery: "user_correction"
- code: "LIMIT_EXCEEDED"
  http_status: 403
  message: "Position limit exceeded"
  recovery: "reduce_position"
configuration: environment_variables: - name: "MAX_POSITION_DELTA" type: "float" default: "0.50" required: true
feature_flags: - name: "enable_strict_validation" default: false description: "Enable enhanced validation rules"
testing: unit_tests: - test: "test_validate_valid_order" module: "tests/unit/test_trade_validator.py" coverage_target: 95
integration_tests: - test: "test_validation_endpoint" module: "tests/integration/test_trade_api.py"
performance_tests: - test: "test_validation_latency" target: "P95 < 50ms"
deployment: container: image: "trade-validator:1.0.0" base: "python:3.11-slim"
resources: cpu: "1000m" memory: "512Mi"
scaling: min_replicas: 2 max_replicas: 10 target_cpu: 70
monitoring: metrics: - name: "validation_latency_ms" type: "histogram" labels: ["endpoint", "status"]
- name: "validation_errors_total"
  type: "counter"
  labels: ["error_code"]
alerts: - alert: "HighValidationLatency" condition: "P95 > 100ms" severity: "warning"
traceability: upstream_sources: - artifact: "BRD-01" sections: ["section-3"] - artifact: "PRD-01" sections: ["feature-2"] - artifact: "REQ-risk-limits-01" sections: ["all"]
downstream_artifacts: - "TASKS-01" - "Code: src/services/trade_validator.py"
undefined
metadata: spec_id: SPEC-01 title: "Order Validation Service Specification" version: "1.0.0" created_date: "2025-01-15" updated_date: "2025-01-15" status: "approved" owner: "team-backend" task_ready_score: "✅ 95% (Target: ≥90%)"
cumulative_tags: brd: ["BRD.01.01.03"] prd: ["PRD.01.07.02"] ears: ["EARS.01.25.01"] bdd: ["BDD.01.14.01"] adr: ["ADR-033", "ADR-045"] sys: ["SYS.01.26.01"] req: ["REQ.01.27.01"] impl: ["IMPL.01.29.01"] # optional contracts: ["CTR-01"] # optional
overview: purpose: "Define trade order validation service implementation" scope: "Validate trade orders against position limits and business rules" requirements: - "REQ-risk-limits-01" - "REQ-risk-limits-02"
architecture: pattern: "layered" layers: - name: "controller" technology: "FastAPI" description: "REST API endpoint handlers" - name: "service" technology: "Python" description: "Business logic and validation" - name: "repository" technology: "SQLAlchemy" description: "Database access layer"
interfaces: api_endpoints: - endpoint: "/api/v1/trades/validate" method: "POST" contract_ref: "CTR-01" authentication: "Bearer token" rate_limit: "@threshold: PRD.NN.limit.api.requests_per_second" rate_limit_window: "1min"
data_models: - model: "TradeOrderRequest" schema_ref: "CTR-01#/components/schemas/TradeOrderRequest" - model: "ValidationResponse" schema_ref: "CTR-01#/components/schemas/ValidationResponse"
implementation: modules: - name: "controllers/trade_validation_controller.py" purpose: "API endpoint handlers" dependencies: ["services/trade_validator.py"]
- name: "services/trade_validator.py"
  purpose: "Business logic and validation"
  dependencies:
    - "repositories/position_repository.py"
    - "models/trade_order.py"

- name: "repositories/position_repository.py"
  purpose: "Database access for positions"
  dependencies: ["database/connection.py"]
functions: - name: "validate_trade_order" module: "services/trade_validator.py" signature: "async def validate_trade_order(order: TradeOrderRequest) -> ValidationResponse" purpose: "Validate trade order against all rules" algorithm: - "1. Validate symbol exists" - "2. Check quantity is positive" - "3. Validate price within range" - "4. Check position limits" - "5. Return validation result"
error_handling: error_codes: - code: "INVALID_SYMBOL" http_status: 400 message: "Symbol not found in approved list" recovery: "user_correction"
- code: "LIMIT_EXCEEDED"
  http_status: 403
  message: "Position limit exceeded"
  recovery: "reduce_position"
configuration: environment_variables: - name: "MAX_POSITION_DELTA" type: "float" default: "0.50" required: true
feature_flags: - name: "enable_strict_validation" default: false description: "Enable enhanced validation rules"
testing: unit_tests: - test: "test_validate_valid_order" module: "tests/unit/test_trade_validator.py" coverage_target: 95
integration_tests: - test: "test_validation_endpoint" module: "tests/integration/test_trade_api.py"
performance_tests: - test: "test_validation_latency" target: "P95 < 50ms"
deployment: container: image: "trade-validator:1.0.0" base: "python:3.11-slim"
resources: cpu: "1000m" memory: "512Mi"
scaling: min_replicas: 2 max_replicas: 10 target_cpu: 70
monitoring: metrics: - name: "validation_latency_ms" type: "histogram" labels: ["endpoint", "status"]
- name: "validation_errors_total"
  type: "counter"
  labels: ["error_code"]
alerts: - alert: "HighValidationLatency" condition: "P95 > 100ms" severity: "warning"
traceability: upstream_sources: - artifact: "BRD-01" sections: ["section-3"] - artifact: "PRD-01" sections: ["feature-2"] - artifact: "REQ-risk-limits-01" sections: ["all"]
downstream_artifacts: - "TASKS-01" - "Code: src/services/trade_validator.py"
undefined

2. Element ID Format (MANDATORY)

2. 元素ID格式（强制要求）

Pattern: 
SPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeExample
Step15SPEC.02.15.01
Interface16SPEC.02.16.01
Data Model17SPEC.02.17.01
Validation Rule21SPEC.02.21.01
Specification Element28SPEC.02.28.01
REMOVED PATTERNS - Do NOT use legacy formats:
  • STEP-XXX
    - Use 
    SPEC.NN.15.SS
    instead
  • IF-XXX
    or 
    INT-XXX
    - Use 
    SPEC.NN.16.SS
    instead
  • DM-XXX
    or 
    MODEL-XXX
    - Use 
    SPEC.NN.17.SS
    instead
  • VR-XXX
    - Use 
    SPEC.NN.21.SS
    instead
Reference: ID_NAMING_STANDARDS.md - Cross-Reference Link Format
模式：
SPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，点分隔）
元素类型代码示例
步骤15SPEC.02.15.01
接口16SPEC.02.16.01
数据模型17SPEC.02.17.01
验证规则21SPEC.02.21.01
规格元素28SPEC.02.28.01
已移除的模式 - 不要使用旧格式：
  • STEP-XXX
    - 改用
    SPEC.NN.15.SS
  • IF-XXX
    或
    INT-XXX
    - 改用
    SPEC.NN.16.SS
  • DM-XXX
    或
    MODEL-XXX
    - 改用
    SPEC.NN.17.SS
  • VR-XXX
    - 改用
    SPEC.NN.21.SS
参考：ID_NAMING_STANDARDS.md - 交叉引用链接格式

3. Required Top-Level Sections

3. 必需的顶级章节

MANDATORY Sections:
  1. metadata: Spec ID, title, version, dates, status, owner, task_ready_score
  2. cumulative_tags: All upstream tags (7-9 tags depending on layers)
  3. overview: Purpose, scope, requirements
  4. architecture: Pattern, layers, technologies
  5. interfaces: API endpoints, data models
  6. implementation: Modules, functions, algorithms
  7. error_handling: Error codes, HTTP status, recovery
  8. configuration: Environment variables, feature flags
  9. testing: Unit, integration, performance tests
  10. deployment: Container, resources, scaling
  11. monitoring: Metrics, alerts, logging
  12. traceability: Upstream sources, downstream artifacts
强制章节：
  1. metadata：SPEC ID、标题、版本、日期、状态、所有者、任务就绪评分
  2. cumulative_tags：所有上游标签（根据层级不同为7-9个标签）
  3. overview：目的、范围、需求
  4. architecture：模式、层级、技术选型
  5. interfaces：API端点、数据模型
  6. implementation：模块、函数、算法
  7. error_handling：错误代码、HTTP状态码、恢复策略
  8. configuration：环境变量、功能开关
  9. testing：单元测试、集成测试、性能测试
  10. deployment：容器、资源配置、伸缩策略
  11. monitoring：指标、告警、日志
  12. traceability：上游来源、下游工件

4. TASKS-Ready Scoring System

4. 任务就绪评分系统

Purpose: Measures SPEC maturity and readiness for progression to TASKS implementation planning.
Format in Metadata:
yaml
metadata:
  task_ready_score: "✅ 95% (Target: ≥90%)"
Status and TASKS-Ready Score Mapping:
TASKS-Ready ScoreRequired Status
≥90%approved
70-89%in_review
<70%draft
Scoring Criteria:
  • YAML Completeness (25%): All metadata fields, traceability chain, all sections populated
  • Interface Definitions (25%): External APIs with CTR contracts, internal interfaces, data schemas
  • Implementation Specifications (25%): Behavior enables code generation, performance/security quantifiable
  • Code Generation Readiness (25%): Machine-readable fields, TASKS-ready metadata
Quality Gate: Score <90% prevents TASKS artifact creation.
目的：衡量SPEC的成熟度以及推进到TASKS实施规划的就绪程度。
元数据中的格式：
yaml
metadata:
  task_ready_score: "✅ 95% (Target: ≥90%)"
状态与任务就绪评分映射：
任务就绪评分所需状态
≥90%approved（已批准）
70-89%in_review（审核中）
<70%draft（草稿）
评分标准：
  • YAML完整性（25%）：所有元数据字段、追溯链、所有章节均已填充
  • 接口定义（25%）：带有CTR合同的外部API、内部接口、数据 schema
  • 实现规格（25%）：行为定义支持代码生成，性能/安全指标可量化
  • 代码生成就绪度（25%）：机器可读字段、任务就绪元数据
质量门控：评分<90%时，无法创建TASKS工件。

5. Threshold Registry Integration

5. 阈值注册表集成

Purpose: Prevent magic numbers by referencing centralized threshold registry.
When @threshold Tag is Required: Use for ALL quantitative values that are:
  • Performance configurations (latencies, throughput, IOPS)
  • Timeout configurations (connection, read, write timeouts)
  • Rate limiting values (requests per second, burst limits)
  • Resource limits (memory, CPU, storage)
  • Circuit breaker configurations
@threshold Tag Format in YAML:
yaml
undefined
目的：通过引用集中式阈值注册表，避免硬编码数值。
何时需要使用@threshold标签：所有以下类型的量化值都必须使用：
  • 性能配置（延迟、吞吐量、IOPS）
  • 超时配置（连接、读取、写入超时）
  • 限流值（每秒请求数、突发限制）
  • 资源限制（内存、CPU、存储）
  • 熔断器配置
YAML中的@threshold标签格式：
yaml
undefined

String value format

字符串值格式

performance: p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"
performance: p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"

Comment format for documentation

文档注释格式

timeout: request_ms: 5000 # @threshold: PRD.NN.timeout.request.sync

**Invalid (hardcoded values)**:
```yaml
performance:
  p95_latency_ms: 200
timeout:
  request_ms: 5000
rate_limit:
  requests_per_second: 100
Valid (registry references):
yaml
performance:
  p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"
timeout:
  request_ms: "@threshold: PRD.NN.timeout.request.sync"
rate_limit:
  requests_per_second: "@threshold: PRD.NN.limit.api.requests_per_second"
timeout: request_ms: 5000 # @threshold: PRD.NN.timeout.request.sync

**无效示例（硬编码值）**：
```yaml
performance:
  p95_latency_ms: 200
timeout:
  request_ms: 5000
rate_limit:
  requests_per_second: 100
有效示例（注册表引用）：
yaml
performance:
  p95_latency_ms: "@threshold: PRD.NN.perf.api.p95_latency"
timeout:
  request_ms: "@threshold: PRD.NN.timeout.request.sync"
rate_limit:
  requests_per_second: "@threshold: PRD.NN.limit.api.requests_per_second"

6. cumulative_tags Field (CRITICAL)

6. cumulative_tags字段（关键）

CRITICAL: SPEC must include cumulative_tags section with ALL upstream tags
Element Type Codes for Cumulative Tags:
TagArtifactElement TypeCode
brdBRDBusiness Requirement01
prdPRDProduct Feature07
earsEARSEARS Statement25
bddBDDScenario14
adrADRDocument reference(dash notation)
sysSYSSystem Requirement26
reqREQAtomic Requirement27
implIMPLImplementation Phase29
contractsCTRDocument reference(dash notation)
Format (maximum - IMPL and CTR included):
yaml
cumulative_tags:
  brd: ["BRD.01.01.03", "BRD.01.01.05"]
  prd: ["PRD.01.07.02", "PRD.01.07.15"]
  ears: ["EARS.01.25.01", "EARS.01.25.02"]
  bdd: ["BDD.01.14.01"]
  adr: ["ADR-033", "ADR-045"]
  sys: ["SYS.01.26.01", "SYS.01.26.07"]
  req: ["REQ.01.27.01"]
  impl: ["IMPL.01.29.01"]
  contracts: ["CTR-01"]
Format (minimum - IMPL and CTR skipped):
yaml
cumulative_tags:
  brd: ["BRD.01.01.03"]
  prd: ["PRD.01.07.02"]
  ears: ["EARS.01.25.01"]
  bdd: ["BDD.01.14.01"]
  adr: ["ADR-033", "ADR-045"]
  sys: ["SYS.01.26.01"]
  req: ["REQ.01.27.01"]
Tag Count: 7-9 tags (minimum 7, maximum 9)
关键要求：SPEC必须包含cumulative_tags章节，且需包含所有上游标签
累积标签的元素类型代码：
标签工件元素类型代码
brdBRD业务需求01
prdPRD产品功能07
earsEARSEARS语句25
bddBDD场景14
adrADR文档引用（短横线格式）
sysSYS系统需求26
reqREQ原子需求27
implIMPL实现阶段29
contractsCTR文档引用（短横线格式）
完整格式（包含IMPL和CTR）：
yaml
cumulative_tags:
  brd: ["BRD.01.01.03", "BRD.01.01.05"]
  prd: ["PRD.01.07.02", "PRD.01.07.15"]
  ears: ["EARS.01.25.01", "EARS.01.25.02"]
  bdd: ["BDD.01.14.01"]
  adr: ["ADR-033", "ADR-045"]
  sys: ["SYS.01.26.01", "SYS.01.26.07"]
  req: ["REQ.01.27.01"]
  impl: ["IMPL.01.29.01"]
  contracts: ["CTR-01"]
最简格式（跳过IMPL和CTR）：
yaml
cumulative_tags:
  brd: ["BRD.01.01.03"]
  prd: ["PRD.01.07.02"]
  ears: ["EARS.01.25.01"]
  bdd: ["BDD.01.14.01"]
  adr: ["ADR-033", "ADR-045"]
  sys: ["SYS.01.26.01"]
  req: ["REQ.01.27.01"]
标签数量：7-9个（最少7个，最多9个）

7. contract_ref Field

7. contract_ref字段

Purpose: Link SPEC to CTR (if Layer 9 created)
Format:
yaml
interfaces:
  api_endpoints:
    - endpoint: "/api/v1/trades/validate"
      method: "POST"
      contract_ref: "CTR-01"  # Link to contract
      contract_path: "#/paths/~1api~1v1~1trades~1validate/post"  # JSON Pointer

  data_models:
    - model: "TradeOrderRequest"
      schema_ref: "CTR-01#/components/schemas/TradeOrderRequest"
目的：将SPEC与CTR关联（如果已创建第9层工件）
格式：
yaml
interfaces:
  api_endpoints:
    - endpoint: "/api/v1/trades/validate"
      method: "POST"
      contract_ref: "CTR-01"  # 关联到合同
      contract_path: "#/paths/~1api~1v1~1trades~1validate/post"  # JSON指针

  data_models:
    - model: "TradeOrderRequest"
      schema_ref: "CTR-01#/components/schemas/TradeOrderRequest"

8. Implementation Readiness

8. 实现就绪度

100% Implementation-Ready: SPEC must contain ALL information needed to write code
Checklist:
  • All modules identified with file paths
  • All functions identified with signatures
  • All algorithms documented step-by-step
  • All data models linked to schemas
  • All error codes defined
  • All configuration specified
  • All tests specified
  • Deployment requirements complete
100%实现就绪：SPEC必须包含编写代码所需的所有信息
检查清单：
  • 已识别所有模块并指定文件路径
  • 已识别所有函数并指定签名
  • 所有算法均已按步骤记录
  • 所有数据模型均已关联到schema
  • 所有错误代码均已定义
  • 所有配置均已指定
  • 所有测试均已指定
  • 部署需求完整

Tag Format Convention (By Design)

标签格式约定（设计如此）

The SDD framework uses two distinct notation systems for cross-references:
NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - references to files/documents
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKSHierarchical artifacts - references to elements inside documents
Key Distinction:
  • @adr: ADR-033
    → Points to the document 
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    → Points to element 01.01 inside document 
    BRD-017.md
SDD框架使用两种不同的符号系统进行交叉引用：
符号格式工件目的
短横线TYPE-NNADR、SPEC、CTR技术工件 - 指向文件/文档的引用
点TYPE.NN.TT.SSBRD、PRD、EARS、BDD、SYS、REQ、IMPL、TASKS分层工件 - 指向文档内部元素的引用
关键区别：
  • @adr: ADR-033
    → 指向文档
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    → 指向文档
    BRD-017.md
    中的元素01.01

Unified Element ID Format (MANDATORY)

统一元素ID格式（强制要求）

For hierarchical requirements (BRD, PRD, EARS, BDD, SYS, REQ, IMPL):
  • Always use: 
    TYPE.NN.TT.SS
    (dot separator, 4-segment unified format)
  • Never use: 
    TYPE-NN:NNN
    (colon separator - DEPRECATED)
  • Never use: 
    TYPE.NN.TT
    (3-segment format - DEPRECATED)
Examples:
  • @brd: BRD.17.01.01
    ✅
  • @brd: BRD.017.001
    ❌ (old 3-segment format)
对于分层需求（BRD、PRD、EARS、BDD、SYS、REQ、IMPL）：
  • 必须使用：
    TYPE.NN.TT.SS
    （点分隔，4段统一格式）
  • 绝不要使用：
    TYPE-NN:NNN
    （冒号分隔 - 已废弃）
  • 绝不要使用：
    TYPE.NN.TT
    （3段格式 - 已废弃）
示例：
  • @brd: BRD.17.01.01
    ✅
  • @brd: BRD.017.001
    ❌（旧的3段格式）

Validation Checks

验证检查

Tier 1: Errors (Blocking)

第1层：错误（阻塞）

CheckDescription
CHECK 1YAML Syntax Validation (parseable)
CHECK 2Required Metadata Fields (version, status, task_ready_score)
CHECK 3TASKS-Ready Score format (✅ emoji + percentage + target)
CHECK 4Complete Traceability Chain (cumulative_tags section)
CHECK 5Element ID Format (
SPEC.NN.TT.SS
)
检查项描述
检查1YAML语法验证（可解析）
检查2必需的元数据字段（版本、状态、task_ready_score）
检查3任务就绪评分格式（✅表情符号 + 百分比 + 目标值）
检查4完整的追溯链（cumulative_tags章节）
检查5元素ID格式（
SPEC.NN.TT.SS
）

Tier 2: Warnings (Recommended)

第2层：警告（推荐）

CheckDescription
CHECK 6Interface Specifications (CTR contract references)
CHECK 7Implementation Readiness (code generation enabling)
CHECK 8Code Generation Compatibility (TASKS creation)
检查项描述
检查6接口规格（CTR合同引用）
检查7实现就绪度（支持代码生成）
检查8代码生成兼容性（支持TASKS创建）

Tier 3: Info

第3层：信息

CheckDescription
CHECK 9Threshold Registry Integration (@threshold references)
CHECK 10Performance benchmarks defined
检查项描述
检查9阈值注册表集成（@threshold引用）
检查10性能基准已定义

Upstream/Downstream Artifacts

上游/下游工件

Upstream Sources:
  • BRD (Layer 1) - Business requirements
  • PRD (Layer 2) - Product features
  • EARS (Layer 3) - Formal requirements
  • BDD (Layer 4) - Test scenarios
  • ADR (Layer 5) - Architecture decisions
  • SYS (Layer 6) - System requirements
  • REQ (Layer 7) - Atomic requirements (PRIMARY SOURCE)
  • IMPL (Layer 8) - Implementation approach (optional)
  • CTR (Layer 9) - Data contracts (optional)
Downstream Artifacts:
  • TASKS (Layer 11) - Task breakdown
  • Code (Layer 12) - Implementation code
  • Tests (Layer 13) - Test suites
Same-Type Document Relationships (conditional):
  • @related-spec: SPEC-NN
    - SPECs sharing implementation context
  • @depends-spec: SPEC-NN
    - SPEC that must be implemented first
上游来源：
  • BRD（第1层）- 业务需求
  • PRD（第2层）- 产品功能
  • EARS（第3层）- 正式需求
  • BDD（第4层）- 测试场景
  • ADR（第5层）- 架构决策
  • SYS（第6层）- 系统需求
  • REQ（第7层）- 原子需求（主要来源）
  • IMPL（第8层）- 实现方案（可选）
  • CTR（第9层）- 数据合同（可选）
下游工件：
  • TASKS（第11层）- 任务分解
  • 代码（第12层）- 实现代码
  • 测试（第13层）- 测试套件
同类型文档关系（可选）：
  • @related-spec: SPEC-NN
    - 共享实现上下文的SPEC
  • @depends-spec: SPEC-NN
    - 必须先实现的SPEC

Creation Process

创建流程

Step 1: Read Upstream Artifacts

步骤1：阅读上游工件

Focus on REQ (Layer 7) and optionally CTR (Layer 9).
重点关注REQ（第7层），可选关注CTR（第9层）。

Step 2: Reserve ID Number

步骤2：预留ID编号

Check 
docs/SPEC/
for next available ID number (or create 
docs/SPEC/
directory if first SPEC).
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • ✅ Correct: SPEC-01, SPEC-99, SPEC-102
  • ❌ Incorrect: SPEC-001, SPEC-009 (extra leading zero not required)
检查
docs/SPEC/
目录，获取下一个可用的ID编号（如果是第一个SPEC，创建
docs/SPEC/
目录）。
ID编号约定：从2位数字开始，仅在需要时扩展。
  • ✅ 正确：SPEC-01、SPEC-99、SPEC-102
  • ❌ 错误：SPEC-001、SPEC-009（不需要额外的前导零）

Step 3: Create SPEC File

步骤3：创建SPEC文件

File naming: 
docs/SPEC/SPEC-NN_{slug}.yaml
Example: 
docs/SPEC/SPEC-01_trade_validation.yaml
IMPORTANT: Pure YAML format (NOT markdown)
Note: Templates and examples are in 
ai_dev_flow/09_SPEC/
while project-specific SPECs go in 
docs/SPEC/
.
文件命名：
docs/SPEC/SPEC-NN_{slug}.yaml
示例：
docs/SPEC/SPEC-01_trade_validation.yaml
重要提示：纯YAML格式（非Markdown）
注意：模板和示例位于
ai_dev_flow/09_SPEC/
，而项目专属的SPEC需放在
docs/SPEC/
目录下。

Step 4: Fill Metadata Section

步骤4：填充元数据章节

Complete spec_id, title, version, dates, status, owner, task_ready_score.
完成spec_id、标题、版本、日期、状态、所有者、任务就绪评分。

Step 5: Add Cumulative Tags

步骤5：添加累积标签

Include all 7-9 upstream tags (brd through req/impl/contracts).
包含所有7-9个上游标签（从brd到req/impl/contracts）。

Step 6: Define Overview

步骤6：定义概述

Purpose, scope, and requirements list.
目的、范围和需求列表。

Step 7: Specify Architecture

步骤7：指定架构

Pattern, layers, and technologies (reference ADR decisions).
模式、层级和技术选型（参考ADR决策）。

Step 8: Define Interfaces

步骤8：定义接口

API endpoints (with contract_ref), data models (with schema_ref).
API端点（带有contract_ref）、数据模型（带有schema_ref）。

Step 9: Document Implementation

步骤9：记录实现细节

Modules (file paths), functions (signatures), algorithms (step-by-step).
模块（文件路径）、函数（签名）、算法（按步骤）。

Step 10: Specify Error Handling

步骤10：指定错误处理

Error codes, HTTP status, messages, recovery procedures.
错误代码、HTTP状态码、消息、恢复流程。

Step 11: Define Configuration

步骤11：定义配置

Environment variables, feature flags, defaults. Use @threshold for quantitative values.
环境变量、功能开关、默认值。对量化值使用@threshold。

Step 12: Specify Testing

步骤12：指定测试

Unit tests, integration tests, performance tests with targets.
单元测试、集成测试、带有目标值的性能测试。

Step 13: Define Deployment

步骤13：定义部署

Container, resources, scaling, environment.
容器、资源配置、伸缩策略、环境。

Step 14: Add Monitoring

步骤14：添加监控

Metrics, alerts, logging requirements.
指标、告警、日志需求。

Step 15: Add Traceability

步骤15：添加追溯

Upstream sources and downstream artifacts.
上游来源和下游工件。

Step 16: Create/Update Traceability Matrix

步骤16：创建/更新追溯矩阵

MANDATORY: Create or update 
docs/SPEC/SPEC-00_TRACEABILITY_MATRIX.md
(use template from 
ai_dev_flow/09_SPEC/SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
)
强制要求：创建或更新
docs/SPEC/SPEC-00_TRACEABILITY_MATRIX.md
（使用
ai_dev_flow/09_SPEC/SPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
中的模板）

Step 17: Validate SPEC

步骤17：验证SPEC

bash
undefined
bash
undefined

YAML validation

YAML验证

yamllint docs/SPEC/SPEC-01_*.yaml
yamllint docs/SPEC/SPEC-01_*.yaml

Schema validation (use SPEC_SCHEMA.yaml as reference)

Schema验证（参考SPEC_SCHEMA.yaml）

Manual: Compare against ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml structure

手动：与ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml结构对比

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact SPEC-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts --strict
python ai_dev_flow/scripts/validate_tags_against_docs.py --artifact SPEC-01 --expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts --strict

Cross-document validation

跨文档验证

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml
undefined
python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml
undefined

Step 18: Commit Changes

步骤18：提交变更

Commit SPEC file and traceability matrix.
提交SPEC文件和追溯矩阵。

Validation

验证

Automated Validation

自动化验证

bash
undefined
bash
undefined

YAML validation

YAML验证

yamllint docs/SPEC/SPEC-01_*.yaml
yamllint docs/SPEC/SPEC-01_*.yaml

Schema validation (use SPEC_SCHEMA.yaml as reference)

Schema验证（参考SPEC_SCHEMA.yaml）

Manual: Compare against ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml structure

手动：与ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml结构对比

Cumulative tagging validation

累积标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact SPEC-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts
--strict
python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact SPEC-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,impl,contracts
--strict

Cross-document validation

跨文档验证

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml
undefined
python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-01_*.yaml
undefined

Manual Checklist

手动检查清单

  • Pure YAML format (not markdown)
  • Metadata section complete with task_ready_score
  • cumulative_tags section with 7-9 upstream tags
  • Overview defines purpose and scope
  • Architecture references ADR decisions
  • Interfaces link to CTR (if Layer 9 created)
  • Implementation specifies modules with file paths
  • Functions have signatures and algorithms
  • Error handling complete
  • Configuration uses @threshold for quantitative values
  • Testing requirements defined
  • Deployment requirements complete
  • Monitoring specified
  • Traceability links to upstream/downstream
  • 100% implementation-ready
  • Element IDs use 
    SPEC.NN.TT.SS
    format
  • 纯YAML格式（非Markdown）
  • 元数据章节完整，包含task_ready_score
  • cumulative_tags章节包含7-9个上游标签
  • 概述定义了目的和范围
  • 架构参考了ADR决策
  • 接口已关联到CTR（如果已创建第9层工件）
  • 实现细节指定了模块和文件路径
  • 函数包含签名和算法
  • 错误处理完整
  • 配置对量化值使用了@threshold
  • 测试需求已定义
  • 部署需求完整
  • 监控已指定
  • 追溯已关联到上游/下游工件
  • 100%实现就绪
  • 元素ID使用
    SPEC.NN.TT.SS
    格式

Diagram Standards

图表标准

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: 
ai_dev_flow/DIAGRAM_STANDARDS.md
and 
mermaid-gen
skill.
所有图表必须使用Mermaid语法。禁止使用基于文本的图表（ASCII艺术、框线图）。 参考：
ai_dev_flow/DIAGRAM_STANDARDS.md
和
mermaid-gen
技能。

Common Pitfalls

常见陷阱

  1. Markdown format: SPEC must be pure YAML, not markdown
  2. Missing cumulative_tags: Must include all 7-9 upstream tags
  3. No contract_ref: Must link to CTR if Layer 9 created
  4. Vague implementation: Must specify exact file paths and signatures
  5. Missing algorithms: Functions need step-by-step algorithms
  6. Incomplete: Must be 100% implementation-ready
  7. Hardcoded values: Use @threshold for performance/timeout/rate limits
  8. Wrong element IDs: Use 
    SPEC.NN.TT.SS
    , not legacy 
    STEP-XXX
    , 
    IF-XXX
    , 
    DM-XXX
  9. Wrong cumulative tag codes: Use correct element type codes (EARS=25, BDD=14, SYS=26, REQ=27, IMPL=29)
  1. Markdown格式：SPEC必须是纯YAML，而非Markdown
  2. 缺失cumulative_tags：必须包含所有7-9个上游标签
  3. 无contract_ref：如果已创建第9层工件，必须关联到CTR
  4. 模糊的实现细节：必须指定确切的文件路径和签名
  5. 缺失算法：函数需要按步骤记录算法
  6. 内容不完整：必须100%实现就绪
  7. 硬编码值：对性能/超时/限流值使用@threshold
  8. 错误的元素ID：使用
    SPEC.NN.TT.SS
    ，而非旧格式
    STEP-XXX
    、
    IF-XXX
    、
    DM-XXX
  9. 错误的累积标签代码：使用正确的元素类型代码（EARS=25、BDD=14、SYS=26、REQ=27、IMPL=29）

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（强制要求 - 无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.
关键：文档创建完成后立即执行此验证循环。在验证通过之前，不要继续创建下一个文档。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python ai_dev_flow/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
LOOP:
  1. 运行：python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复：回到LOOP（重新验证）
  3. 如果警告已修复：回到LOOP（重新验证）
  4. 如果存在无法修复的问题：记录以便手动审核，继续
  5. 如果验证通过：标记为VALIDATED（已验证），继续

Validation Command

验证命令

bash
undefined
bash
undefined

Per-document validation (Phase 1)

单文档验证（阶段1）

python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-NN_slug.yaml --auto-fix
python ai_dev_flow/scripts/validate_cross_document.py --document docs/SPEC/SPEC-NN_slug.yaml --auto-fix

Layer validation (Phase 2) - run when all SPEC documents complete

层级验证（阶段2）- 所有SPEC文档完成后运行

python ai_dev_flow/scripts/validate_cross_document.py --layer SPEC --auto-fix
undefined
python ai_dev_flow/scripts/validate_cross_document.py --layer SPEC --auto-fix
undefined

Layer-Specific Upstream Requirements

层级专属上游需求

This LayerRequired Upstream TagsCount
SPEC (Layer 10)@brd, @prd, @ears, @bdd, @adr, @sys, @req (+ @impl, @ctr if created)7-9 tags
当前层级必需的上游标签数量
SPEC（第10层）@brd、@prd、@ears、@bdd、@adr、@sys、@req（+ @impl、@ctr如果已创建）7-9个标签

Auto-Fix Actions (No Confirmation Required)

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

IssueFix Action
Missing upstream 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-006Tag format invalidERROR
XDOC-007Gap in cumulative tag chainERROR
XDOC-009Missing traceability sectionERROR
代码描述严重程度
XDOC-001引用的需求ID未找到错误
XDOC-002缺失累积标签错误
XDOC-003上游文档未找到错误
XDOC-006标签格式无效错误
XDOC-007累积标签链存在缺口错误
XDOC-009缺失追溯章节错误

Quality Gate

质量门控

Blocking: YES - Cannot proceed to next document until Phase 1 validation passes with 0 errors.
阻塞：是 - 阶段1验证必须无错误通过，才能继续创建下一个文档。

Next Skill

下一个技能

After creating SPEC, use:
doc-tasks
 - Create Task Breakdown (Layer 11)
The TASKS will:
  • Reference this SPEC as upstream source
  • Include all 8-10 upstream tags
  • Break SPEC into actionable tasks
  • Provide AI-structured TODO format
创建完SPEC后，使用：
doc-tasks
 - 创建任务分解（第11层）
TASKS将：
  • 引用此SPEC作为上游来源
  • 包含所有8-10个上游标签
  • 将SPEC分解为可执行任务
  • 提供AI结构化的TODO格式

Reference Documents

参考文档

SPEC artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.
For supplementary documentation needs, create:
  • BRD-REF: Business context documentation
  • ADR-REF: Technical reference guides (API quick references, implementation guides)
SPEC工件不支持REF文档。根据SDD框架，参考文档仅限于BRD和ADR类型。
如需补充文档，可创建：
  • BRD-REF：业务上下文文档
  • ADR-REF：技术参考指南（API快速参考、实现指南）

Related Resources

相关资源

  • Template: 
    ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
    (primary authority)
  • SPEC Creation Rules: 
    ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md
  • SPEC Validation Rules: 
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  • SPEC Schema: 
    ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml
  • SPEC README: 
    ai_dev_flow/09_SPEC/README.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • 模板：
    ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
    （主要权威来源）
  • SPEC创建规则：
    ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md
  • SPEC验证规则：
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  • SPEC Schema：
    ai_dev_flow/09_SPEC/SPEC_SCHEMA.yaml
  • SPEC README：
    ai_dev_flow/09_SPEC/README.md
  • 共享标准：
    .claude/skills/doc-flow/SHARED_CONTENT.md

Quick Reference

快速参考

SPEC Purpose: Implementation-ready technical specifications
Layer: 10
Element ID Format: 
SPEC.NN.TT.SS
  • Step = 15
  • Interface = 16
  • Data Model = 17
  • Validation Rule = 21
  • Specification Element = 28
Removed Patterns: STEP-XXX, IF-XXX, INT-XXX, DM-XXX, MODEL-XXX, VR-XXX
Tags Required: @brd through @req/impl/contracts (7-9 tags)
Format: Pure YAML (not markdown)
Key Features:
  • cumulative_tags section (CRITICAL)
  • contract_ref field (links to CTR)
  • schema_ref field (links to data models)
  • @threshold references for quantitative values
  • 100% implementation-ready
  • All modules, functions, algorithms specified
TASKS-Ready Score: ≥90% required for "approved" status
Quality Gate: Must be 100% implementation-ready
Next: doc-tasks
SPEC目的：可直接用于实现的技术规格说明
层级：10
元素ID格式：
SPEC.NN.TT.SS
  • 步骤 = 15
  • 接口 = 16
  • 数据模型 = 17
  • 验证规则 = 21
  • 规格元素 = 28
已移除的模式：STEP-XXX、IF-XXX、INT-XXX、DM-XXX、MODEL-XXX、VR-XXX
必需标签：@brd到@req/impl/contracts（7-9个标签）
格式：纯YAML（非Markdown）
关键特性：
  • cumulative_tags章节（关键）
  • contract_ref字段（关联到CTR）
  • schema_ref字段（关联到数据模型）
  • 对量化值使用@threshold引用
  • 100%实现就绪
  • 所有模块、函数、算法均已指定
任务就绪评分：“approved”状态需要≥90%
质量门控：必须100%实现就绪
下一步：doc-tasks