doc-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

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

Reference only existing documents in traceability tags
Use
null
only when upstream artifact type genuinely doesn't exist
NEVER use placeholders like
```
BRD-XXX
```
or
```
TBD
```
Do NOT create missing upstream artifacts - skip functionality instead

Before creating SPEC, read:

Shared Standards:

.claude/skills/doc-flow/SHARED_CONTENT.md

Upstream REQ: Read atomic requirements (PRIMARY SOURCE)
Upstream CTR: Read contracts if Layer 9 created
Template:
```
ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
```

Creation Rules:

ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md

Validation Rules:

ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md

Validation Script:
```
./ai_dev_flow/scripts/validate_spec_template.sh
```
(under development - use template for manual validation until available)

在创建本文档之前，您必须：

列出已有的上游工件：

bash

ls docs/BRD/ docs/PRD/ docs/EARS/ docs/BDD/ docs/ADR/ docs/SYS/ docs/REQ/ docs/IMPL/ docs/CTR/ 2>/dev/null

仅在追溯标签中引用已存在的文档
仅当上游工件类型确实不存在时，才使用
null
绝不要使用
```
BRD-XXX
```
或
```
TBD
```
这类占位符
不要创建缺失的上游工件——而是跳过相关功能

在创建SPEC之前，请阅读：

共享标准：

.claude/skills/doc-flow/SHARED_CONTENT.md

上游REQ：阅读原子需求（主要来源）
上游CTR：如果已创建第9层工件，请阅读合同文档
模板：
```
ai_dev_flow/09_SPEC/SPEC-TEMPLATE.yaml
```

创建规则：

ai_dev_flow/09_SPEC/SPEC_CREATION_RULES.md

验证规则：

ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md

验证脚本：
```
./ai_dev_flow/scripts/validate_spec_template.sh
```
（开发中 - 在可用之前，使用模板进行手动验证）

Reserved ID Exemption (SPEC-00_*)

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

Scope: Documents with reserved ID

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为

的文档完全豁免验证。

模式：

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]

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

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"]

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 Type	Code	Example
Step	15	SPEC.02.15.01
Interface	16	SPEC.02.16.01
Data Model	17	SPEC.02.17.01
Validation Rule	21	SPEC.02.21.01
Specification Element	28	SPEC.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个段，点分隔）

元素类型	代码	示例
步骤	15	SPEC.02.15.01
接口	16	SPEC.02.16.01
数据模型	17	SPEC.02.17.01
验证规则	21	SPEC.02.21.01
规格元素	28	SPEC.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:

metadata: Spec ID, title, version, dates, status, owner, task_ready_score
cumulative_tags: All upstream tags (7-9 tags depending on layers)
overview: Purpose, scope, requirements
architecture: Pattern, layers, technologies
interfaces: API endpoints, data models
implementation: Modules, functions, algorithms
error_handling: Error codes, HTTP status, recovery
configuration: Environment variables, feature flags
testing: Unit, integration, performance tests
deployment: Container, resources, scaling
monitoring: Metrics, alerts, logging
traceability: Upstream sources, downstream artifacts

强制章节：

metadata：SPEC ID、标题、版本、日期、状态、所有者、任务就绪评分
cumulative_tags：所有上游标签（根据层级不同为7-9个标签）
overview：目的、范围、需求
architecture：模式、层级、技术选型
interfaces：API端点、数据模型
implementation：模块、函数、算法
error_handling：错误代码、HTTP状态码、恢复策略
configuration：环境变量、功能开关
testing：单元测试、集成测试、性能测试
deployment：容器、资源配置、伸缩策略
monitoring：指标、告警、日志
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 Score	Required 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"

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:

Tag	Artifact	Element Type	Code
brd	BRD	Business Requirement	01
prd	PRD	Product Feature	07
ears	EARS	EARS Statement	25
bdd	BDD	Scenario	14
adr	ADR	Document reference	(dash notation)
sys	SYS	System Requirement	26
req	REQ	Atomic Requirement	27
impl	IMPL	Implementation Phase	29
contracts	CTR	Document 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章节，且需包含所有上游标签

累积标签的元素类型代码：

标签	工件	元素类型	代码
brd	BRD	业务需求	01
prd	PRD	产品功能	07
ears	EARS	EARS语句	25
bdd	BDD	场景	14
adr	ADR	文档引用	（短横线格式）
sys	SYS	系统需求	26
req	REQ	原子需求	27
impl	IMPL	实现阶段	29
contracts	CTR	文档引用	（短横线格式）

完整格式（包含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. 实现就绪度

Tag Format Convention (By Design)

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

The SDD framework uses two distinct notation systems for cross-references:

Notation	Format	Artifacts	Purpose
Dash	TYPE-NN	ADR, SPEC, CTR	Technical artifacts - references to files/documents
Dot	TYPE.NN.TT.SS	BRD, PRD, EARS, BDD, SYS, REQ, IMPL, TASKS	Hierarchical 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-NN	ADR、SPEC、CTR	技术工件 - 指向文件/文档的引用
点	TYPE.NN.TT.SS	BRD、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层：错误（阻塞）

Check	Description
CHECK 1	YAML Syntax Validation (parseable)
CHECK 2	Required Metadata Fields (version, status, task_ready_score)
CHECK 3	TASKS-Ready Score format (✅ emoji + percentage + target)
CHECK 4	Complete Traceability Chain (cumulative_tags section)
CHECK 5	Element ID Format ( `SPEC.NN.TT.SS` )

检查项	描述
检查1	YAML语法验证（可解析）
检查2	必需的元数据字段（版本、状态、task_ready_score）
检查3	任务就绪评分格式（✅表情符号 + 百分比 + 目标值）
检查4	完整的追溯链（cumulative_tags章节）
检查5	元素ID格式（ `SPEC.NN.TT.SS` ）

Tier 2: Warnings (Recommended)

第2层：警告（推荐）

Check	Description
CHECK 6	Interface Specifications (CTR contract references)
CHECK 7	Implementation Readiness (code generation enabling)
CHECK 8	Code Generation Compatibility (TASKS creation)

检查项	描述
检查6	接口规格（CTR合同引用）
检查7	实现就绪度（支持代码生成）
检查8	代码生成兼容性（支持TASKS创建）

Tier 3: Info

第3层：信息

Check	Description
CHECK 9	Threshold Registry Integration (@threshold references)
CHECK 10	Performance 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

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

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

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

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

常见陷阱

Markdown format: SPEC must be pure YAML, not markdown
Missing cumulative_tags: Must include all 7-9 upstream tags
No contract_ref: Must link to CTR if Layer 9 created
Vague implementation: Must specify exact file paths and signatures
Missing algorithms: Functions need step-by-step algorithms
Incomplete: Must be 100% implementation-ready
Hardcoded values: Use @threshold for performance/timeout/rate limits
Wrong element IDs: Use
```
SPEC.NN.TT.SS
```
, not legacy
```
STEP-XXX
```
,
```
IF-XXX
```
,
```
DM-XXX
```
Wrong cumulative tag codes: Use correct element type codes (EARS=25, BDD=14, SYS=26, REQ=27, IMPL=29)

Markdown格式：SPEC必须是纯YAML，而非Markdown
缺失cumulative_tags：必须包含所有7-9个上游标签
无contract_ref：如果已创建第9层工件，必须关联到CTR
模糊的实现细节：必须指定确切的文件路径和签名
缺失算法：函数需要按步骤记录算法
内容不完整：必须100%实现就绪
硬编码值：对性能/超时/限流值使用@threshold
错误的元素ID：使用
```
SPEC.NN.TT.SS
```
，而非旧格式
```
STEP-XXX
```
、
```
IF-XXX
```
、
```
DM-XXX
```
错误的累积标签代码：使用正确的元素类型代码（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

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 Layer	Required Upstream Tags	Count
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)

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

Issue	Fix Action
Missing upstream tag	Add with upstream document reference
Invalid tag format	Correct to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken link	Recalculate path from current location
Missing traceability section	Insert from template

问题	修复操作
缺失上游标签	添加上游文档引用
无效标签格式	修正为TYPE.NN.TT.SS（4段）或TYPE-NN格式
链接损坏	根据当前位置重新计算路径
缺失追溯章节	从模板插入

Validation Codes Reference

验证代码参考

Code	Description	Severity
XDOC-001	Referenced requirement ID not found	ERROR
XDOC-002	Missing cumulative tag	ERROR
XDOC-003	Upstream document not found	ERROR
XDOC-006	Tag format invalid	ERROR
XDOC-007	Gap in cumulative tag chain	ERROR
XDOC-009	Missing traceability section	ERROR

代码	描述	严重程度
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

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