Back to Details

doc-spec-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-spec-validator

doc-spec-validator

Validate Technical Specifications (SPEC) documents against Layer 9 schema standards.
依据Layer 9 schema标准验证技术规格（SPEC）文档。

Activation

触发时机

Invoke when user requests validation of SPEC documents or after creating/modifying SPEC artifacts.
当用户请求验证SPEC文档，或在创建/修改SPEC工件后调用。

Validation Schema Reference

验证Schema参考

Schema: 
ai_dev_flow/SPEC/SPEC_SCHEMA.yaml
Layer: 9 Artifact Type: SPEC
Schema: 
ai_dev_flow/SPEC/SPEC_SCHEMA.yaml
层级：9 工件类型：SPEC

Validation Checklist

验证检查清单

0. Folder Structure Validation (BLOCKING)

0. 文件夹结构验证（阻塞性检查）

Nested Folder Rule: ALL SPEC documents MUST be in nested folders regardless of size.
Required Structure:
SPEC TypeRequired Location
YAML
docs/09_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml
Validation:
1. Check document is inside a nested folder: docs/09_SPEC/SPEC-NN_{slug}/
2. Verify folder name matches SPEC ID pattern: SPEC-NN_{slug}
3. Verify file name matches folder: SPEC-NN_{slug}.yaml
4. Parent path must be: docs/09_SPEC/
Example Valid Structure:
docs/09_SPEC/
├── SPEC-01_f1_iam/
│   ├── SPEC-01_f1_iam.yaml        ✓ Valid
│   ├── SPEC-01.R_review_report_v001.md
│   └── .drift_cache.json
├── SPEC-02_f2_session/
│   └── SPEC-02_f2_session.yaml    ✓ Valid
Invalid Structure:
docs/09_SPEC/
├── SPEC-01_f1_iam.yaml            ✗ NOT in nested folder
Error Codes:
CodeSeverityDescription
SPEC-E020ERRORSPEC not in nested folder (BLOCKING)
SPEC-E021ERRORFolder name doesn't match SPEC ID
SPEC-E022ERRORFile name doesn't match folder name
This check is BLOCKING - SPEC must pass folder structure validation before other checks proceed.
嵌套文件夹规则：所有SPEC文档无论大小，都必须放在嵌套文件夹中。
要求的结构:
SPEC类型要求的存放位置
YAML
docs/09_SPEC/SPEC-NN_{slug}/SPEC-NN_{slug}.yaml
验证步骤:
1. 检查文档是否位于嵌套文件夹内：docs/09_SPEC/SPEC-NN_{slug}/
2. 验证文件夹名称是否符合SPEC ID格式：SPEC-NN_{slug}
3. 验证文件名是否与文件夹名称匹配：SPEC-NN_{slug}.yaml
4. 父路径必须为：docs/09_SPEC/
有效结构示例:
docs/09_SPEC/
├── SPEC-01_f1_iam/
│   ├── SPEC-01_f1_iam.yaml        ✓ 有效
│   ├── SPEC-01.R_review_report_v001.md
│   └── .drift_cache.json
├── SPEC-02_f2_session/
│   └── SPEC-02_f2_session.yaml    ✓ 有效
无效结构:
docs/09_SPEC/
├── SPEC-01_f1_iam.yaml            ✗ 未放在嵌套文件夹中
错误代码:
代码严重程度描述
SPEC-E020错误SPEC未放在嵌套文件夹中（阻塞性检查）
SPEC-E021错误文件夹名称与SPEC ID不匹配
SPEC-E022错误文件名与文件夹名称不匹配
此检查为阻塞性检查 - SPEC必须通过文件夹结构验证后，才能进行其他检查。

1. File Format Validation

1. 文件格式验证

yaml
File Format:
  - Extension: .yaml (NOT .md)
  - Naming pattern: SPEC-NNN_descriptive_name.yaml
  - Encoding: UTF-8
  - YAML version: 1.2
yaml
File Format:
  - Extension: .yaml (NOT .md)
  - Naming pattern: SPEC-NNN_descriptive_name.yaml
  - Encoding: UTF-8
  - YAML version: 1.2

2. Required Top-Level Fields

2. 必填顶层字段

yaml
Required fields:
  - id: Component identifier (snake_case)
  - summary: Single-sentence description (10-200 chars)
  - metadata: Document control and versioning
  - traceability: Upstream and downstream references
  - architecture: Component architecture and dependencies
  - interfaces: Interface definitions (classes, methods)
  - behavior: Behavioral specifications
  - performance: Performance targets
  - security: Security specifications
  - observability: Metrics, logging, health checks
  - verification: Test scenarios
  - implementation: Implementation specifics

Optional fields:
  - caching
  - rate_limiting
  - circuit_breaker
  - operations
  - changelog
  - maintenance
  - notes
yaml
Required fields:
  - id: 组件标识符（snake_case格式）
  - summary: 单句描述（10-200字符）
  - metadata: 文档管控与版本信息
  - traceability: 上下游关联引用
  - architecture: 组件架构与依赖关系
  - interfaces: 接口定义（类、方法）
  - behavior: 行为规格
  - performance: 性能指标
  - security: 安全规格
  - observability: 指标、日志、健康检查
  - verification: 测试场景
  - implementation: 实现细节

Optional fields:
  - caching
  - rate_limiting
  - circuit_breaker
  - operations
  - changelog
  - maintenance
  - notes

3. Metadata Section Validation

3. 元数据（Metadata）部分验证

Required Fields:
  • version: Semantic version (MAJOR.MINOR.PATCH)
  • status: draft | review | approved | implemented | deprecated
  • created_date: YYYY-MM-DD format
  • last_updated: YYYY-MM-DD format
  • authors: Array with at least one author (name required)
Optional Fields:
  • task_ready_score
  • reviewers
  • owners
必填字段:
  • version: 语义化版本（MAJOR.MINOR.PATCH格式）
  • status: draft（草稿）| review（评审中）| approved（已批准）| implemented（已实现）| deprecated（已废弃）
  • created_date: YYYY-MM-DD格式
  • last_updated: YYYY-MM-DD格式
  • authors: 数组，至少包含一位作者（必填姓名）
可选字段:
  • task_ready_score
  • reviewers
  • owners

4. Interfaces Section Validation

4. 接口（Interfaces）部分验证

Class Requirements:
  • name: PascalCase format
  • description: Required
  • methods: At least one method required per class
Method Requirements:
  • name: snake_case format
  • description: Required
  • input: Optional parameters object
  • output: Optional return object
  • errors: Optional error definitions
类要求:
  • name: PascalCase格式
  • description: 必填
  • methods: 每个类至少定义一个方法
方法要求:
  • name: snake_case格式
  • description: 必填
  • input: 可选参数对象
  • output: 可选返回对象
  • errors: 可选错误定义

5. Performance Section Validation

5. 性能（Performance）部分验证

Required Fields:
  • latency_targets:
    • p50_milliseconds
    • p95_milliseconds
    • p99_milliseconds
  • throughput_targets:
    • sustained_requests_per_second
  • resource_limits:
    • cpu_cores_allocated
    • memory_mb_allocated
Validation Rules:
  • p95 must be greater than p50
  • p99 must be greater than p95
必填字段:
  • latency_targets:
    • p50_milliseconds
    • p95_milliseconds
    • p99_milliseconds
  • throughput_targets:
    • sustained_requests_per_second
  • resource_limits:
    • cpu_cores_allocated
    • memory_mb_allocated
验证规则:
  • p95必须大于p50
  • p99必须大于p95

6. Security Section Validation

6. 安全（Security）部分验证

Required Fields:
  • authentication.required: boolean
  • authentication.methods: array
  • authorization.enabled: boolean
  • input_validation.strategy: string
必填字段:
  • authentication.required: 布尔值
  • authentication.methods: 数组
  • authorization.enabled: 布尔值
  • input_validation.strategy: 字符串

7. Observability Section Validation

7. 可观测性（Observability）部分验证

Required Fields:
  • metrics.standard_metrics: array (min 1 item)
  • logging.level: DEBUG | INFO | WARN | ERROR
  • logging.format: json | text | structured
  • health_checks.enabled: boolean
  • health_checks.endpoints: array
必填字段:
  • metrics.standard_metrics: 数组（至少1项）
  • logging.level: DEBUG | INFO | WARN | ERROR
  • logging.format: json | text | structured
  • health_checks.enabled: 布尔值
  • health_checks.endpoints: 数组

8. Traceability Validation

8. 可追溯性（Traceability）验证

Layer 9 Cumulative Tags:
  • @brd: BRD-NNN:XXX-NNN (required)
  • @prd: PRD-NNN:XXX-NNN (required)
  • @ears: EARS-NNN:NNN (required)
  • @bdd: BDD-NNN:scenario-name (required)
  • @adr: ADR-NN (required)
  • @sys: SYS-NNN:XXX-NNN (required)
  • @req: REQ-NNN:feature-name (required)
  • @ctr: CTR-NNN (optional)
Downstream Expected:
  • TASKS documents
  • Code (src/...)
  • Tests (tests/...)
Same-Type References:
  • related_spec: [SPEC-NN]
  • depends_spec: [SPEC-NN]
Layer 9 累积标签:
  • @brd: BRD-NNN:XXX-NNN（必填）
  • @prd: PRD-NNN:XXX-NNN（必填）
  • @ears: EARS-NNN:NNN（必填）
  • @bdd: BDD-NNN:scenario-name（必填）
  • @adr: ADR-NN（必填）
  • @sys: SYS-NNN:XXX-NNN（必填）
  • @req: REQ-NNN:feature-name（必填）
  • @ctr: CTR-NNN（可选）
预期下游关联:
  • TASKS文档
  • 代码（src/...）
  • 测试用例（tests/...）
同类型引用:
  • related_spec: [SPEC-NN]
  • depends_spec: [SPEC-NN]

Error Codes

错误代码

CodeSeverityDescription
SPEC-E001errorFile is not valid YAML
SPEC-E002errorMissing required top-level field
SPEC-E003errorMissing required metadata field
SPEC-E004errorInvalid version format
SPEC-E005errorInvalid status value
SPEC-E006errorInvalid date format
SPEC-E007errorNo authors specified
SPEC-E008errorNo classes defined in interfaces
SPEC-E009errorClass has no methods
SPEC-E010errorMissing latency_targets in performance
SPEC-E011errorMissing authentication in security
SPEC-E012errorMissing metrics in observability
SPEC-E013warningFile name does not match format
SPEC-E014errorMissing traceability section
SPEC-E015errorMissing cumulative_tags in traceability
SPEC-W001warningMissing business_requirements in upstream
SPEC-W002warningMissing cumulative tags for traceability
SPEC-W003warningNo BDD scenarios in verification
SPEC-W004warningp95 latency not greater than p50
SPEC-W005warningp99 latency not greater than p95
SPEC-W006warningMethod name not in snake_case
SPEC-W007warningClass name not in PascalCase
SPEC-W008warningid field does not match file name
SPEC-W009warningtask_ready_score below target
SPEC-I001infoConsider adding caching section
SPEC-I002infoConsider adding rate_limiting section
SPEC-I003infoConsider adding circuit_breaker section
SPEC-I004infoConsider adding operations runbook
代码严重程度描述
SPEC-E001错误文件不是有效的YAML格式
SPEC-E002错误缺失必填顶层字段
SPEC-E003错误缺失必填元数据字段
SPEC-E004错误版本格式无效
SPEC-E005错误状态值无效
SPEC-E006错误日期格式无效
SPEC-E007错误未指定作者
SPEC-E008错误接口中未定义类
SPEC-E009错误类中未定义方法
SPEC-E010错误性能部分缺失latency_targets
SPEC-E011错误安全部分缺失authentication
SPEC-E012错误可观测性部分缺失metrics
SPEC-E013警告文件名不符合格式
SPEC-E014错误缺失可追溯性部分
SPEC-E015错误可追溯性部分缺失cumulative_tags
SPEC-W001警告上游关联缺失business_requirements
SPEC-W002警告可追溯性缺失累积标签
SPEC-W003警告验证部分缺失BDD场景
SPEC-W004警告p95延迟不大于p50
SPEC-W005警告p99延迟不大于p95
SPEC-W006警告方法名不是snake_case格式
SPEC-W007警告类名不是PascalCase格式
SPEC-W008警告id字段与文件名不匹配
SPEC-W009警告task_ready_score低于目标值
SPEC-I001信息建议添加caching部分
SPEC-I002信息建议添加rate_limiting部分
SPEC-I003信息建议添加circuit_breaker部分
SPEC-I004信息建议添加运维手册（operations runbook）

Validation Commands

验证命令

bash
undefined
bash
undefined

Validate single SPEC document

验证单个SPEC文档

python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/SPEC-001_example.yaml
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/SPEC-001_example.yaml

Validate all SPEC documents

验证所有SPEC文档

python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/

Check with verbose output

启用详细输出检查

python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/ --verbose
undefined
python ai_dev_flow/scripts/validate_spec.py docs/09_SPEC/ --verbose
undefined

Validation Workflow

验证流程

  1. Verify file is valid YAML
  2. Check all required top-level fields present
  3. Validate metadata section (version, status, dates, authors)
  4. Check interfaces section (classes with methods)
  5. Validate performance section (latency targets, p50 < p95 < p99)
  6. Check security section (authentication, authorization)
  7. Validate observability section (metrics, logging, health)
  8. Check traceability cumulative tags (7 required)
  9. Verify verification section (BDD scenarios)
  10. Validate implementation section
  11. Check file naming convention
  12. Generate validation report
  1. 验证文件是否为有效的YAML格式
  2. 检查所有必填顶层字段是否存在
  3. 验证元数据部分（版本、状态、日期、作者）
  4. 检查接口部分（包含方法的类）
  5. 验证性能部分（延迟指标，p50 < p95 < p99）
  6. 检查安全部分（身份认证、授权）
  7. 验证可观测性部分（指标、日志、健康检查）
  8. 检查可追溯性累积标签（7个必填）
  9. 验证验证部分（BDD场景）
  10. 验证实现部分
  11. 检查文件命名规范
  12. 生成验证报告

Integration

集成方式

  • Invoked by: doc-flow, doc-spec (post-creation)
  • Feeds into: trace-check (cross-document validation)
  • Reports to: quality-advisor
  • 调用方：doc-flow、doc-spec（创建后触发）
  • 输出至：trace-check（跨文档验证）
  • 报告至：quality-advisor

Output Format

输出格式

SPEC Validation Report
======================
Document: SPEC-001_example.yaml
Status: PASS/FAIL

YAML Validity: Valid/Invalid

Required Sections:
- metadata: Present/Missing
- traceability: Present/Missing
- architecture: Present/Missing
- interfaces: Present/Missing
- behavior: Present/Missing
- performance: Present/Missing
- security: Present/Missing
- observability: Present/Missing
- verification: Present/Missing
- implementation: Present/Missing

Interface Summary:
- Classes defined: N
- Methods defined: N

Performance Targets:
- p50: Nms
- p95: Nms (> p50: Yes/No)
- p99: Nms (> p95: Yes/No)

Errors: N
Warnings: N
Info: N

[Details listed by severity]
SPEC验证报告
======================
文档：SPEC-001_example.yaml
状态：通过/不通过

YAML有效性：有效/无效

必填章节:
- metadata: 存在/缺失
- traceability: 存在/缺失
- architecture: 存在/缺失
- interfaces: 存在/缺失
- behavior: 存在/缺失
- performance: 存在/缺失
- security: 存在/缺失
- observability: 存在/缺失
- verification: 存在/缺失
- implementation: 存在/缺失

接口摘要:
- 已定义类数量：N
- 已定义方法数量：N

性能指标:
- p50: N毫秒
- p95: N毫秒（大于p50：是/否）
- p99: N毫秒（大于p95：是/否）

错误数：N
警告数：N
信息数：N

[按严重程度列出详细信息]

Related Resources

相关资源

  • SPEC Skill: 
    .claude/skills/doc-spec/SKILL.md
  • Naming Standards: 
    .claude/skills/doc-naming/SKILL.md
    (ID and naming conventions)
  • SPEC Validation Rules: 
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  • SPEC Schema: 
    ai_dev_flow/SPEC/SPEC_SCHEMA.yaml
  • SPEC技能: 
    .claude/skills/doc-spec/SKILL.md
  • 命名标准: 
    .claude/skills/doc-naming/SKILL.md
    （ID与命名规范）
  • SPEC验证规则: 
    ai_dev_flow/09_SPEC/SPEC_VALIDATION_RULES.md
  • SPEC Schema: 
    ai_dev_flow/SPEC/SPEC_SCHEMA.yaml

Version History

版本历史

VersionDateChangesAuthor
1.22026-02-11Nested Folder Rule: Added Section 0 Folder Structure Validation (BLOCKING); SPEC must be in 
docs/09_SPEC/SPEC-NN_{slug}/
folders; Added error codes SPEC-E020, SPEC-E021, SPEC-E022
1.1.02026-02-08Updated layer assignment from 10 to 9 per LAYER_REGISTRY v1.6; removed @impl from cumulative tagsSystem
1.0.02025-01-15Initial validator skill definitionSystem
版本日期变更内容作者
1.22026-02-11嵌套文件夹规则：新增第0节文件夹结构验证（阻塞性检查）；SPEC必须放在
docs/09_SPEC/SPEC-NN_{slug}/
文件夹中；新增错误代码SPEC-E020、SPEC-E021、SPEC-E022
1.1.02026-02-08根据LAYER_REGISTRY v1.6，将层级从10更新为9；移除累积标签中的@impl系统
1.0.02025-01-15初始验证器技能定义系统