- name
- spec-compliance-validator
- description
- 驗證規格檔案的完整性與一致性，確保所有必要的規格元素都已定義且符合標準格式。
Spec Compliance Validator Skill
觸發時機
- 新規格檔案創建後
- 規格修改後的驗證
- 進入開發階段前的品質門檻
- 與
multi-model-reviewer 協作時
核心任務
- 結構完整性：驗證規格目錄結構
- 格式合規性：YAML 格式與 schema 驗證
- 追溯性檢查：Frame Concerns ↔ Acceptance Criteria ↔ Tests
- 跨規格一致性：標準引用、命名慣例
驗證項目
1. 目錄結構檢查
structure_checks:
required_files:
- name: "frame.yaml"
description: "Problem Frame 定義"
required: true
- name: "acceptance.yaml"
description: "驗收標準 (根目錄)"
required: true
- name: "requirements/*.yaml"
description: "需求規格"
required: true
min_count: 1
- name: "machine/machine.yaml"
description: "Machine 定義"
required: true
- name: "machine/use-case.yaml"
description: "Use Case 規格 (CBF)"
required_if: "frame_type == 'CBF'"
- name: "machine/query.yaml"
description: "Query 規格 (IDF)"
required_if: "frame_type == 'IDF'"
- name: "controlled-domain/aggregate.yaml"
description: "Aggregate 定義"
required: true
2. Frame 定義驗證
frame_checks:
- id: FR1
name: "Frame Type 有效"
rule: "frame_type ∈ {CBF, IDF, RIF, WPF, TF}"
- id: FR2
name: "Frame Concerns 完整"
rule: "每個 concern 必須有 satisfied_by 連結"
- id: FR3
name: "Phenomena 定義"
rule: "input/output phenomena 必須定義"
- id: FR4
name: "Cross-Context 識別"
rule: "cross_context_dependencies 如有則必須有對應 ACL"
3. Acceptance Criteria 驗證
acceptance_checks:
- id: AC1
name: "格式合規"
rule: "使用 acceptance_criteria 格式 (非舊版 scenarios)"
expected_format: |
acceptance_criteria:
- id: AC1
given: "前置條件"
when: "觸發動作"
then: "預期結果"
trace: "requirements/req.yaml#REQ1"
- id: AC2
name: "追溯性完整"
rule: "每個 AC 必須有 trace 連結到 requirement"
- id: AC3
name: "Tests Anchor"
rule: "應定義 tests_anchor 指向測試檔案"
4. Domain Event 標準驗證
domain_event_checks:
- id: DE1
name: "標準引用"
rule: "domain_events 應包含 includes_standard 和 standard_ref"
expected: |
domain_events:
includes_standard: true
standard_ref: "../../../../shared/domain-event-standard.yaml"
- id: DE2
name: "Metadata 屬性"
rule: "使用標準時不需重複定義 id, occurredOn"
- id: DE3
name: "屬性排序"
rule: "主要 ID 應為第一個屬性"
5. Invariant 驗證
invariant_checks:
- id: INV1
name: "Enforced 位置"
rule: "每個 invariant 必須有 enforced_in 位置"
- id: INV2
name: "測試連結"
rule: "invariant 應有對應的違反測試"
- id: INV3
name: "共享標準"
rule: "共同 invariants 應抽取到 shared/invariants.yaml"
輸出格式
驗證報告
╔═══════════════════════════════════════════════════════════════════╗
║ SPEC COMPLIANCE VALIDATION REPORT ║
╠═══════════════════════════════════════════════════════════════════╣
║ Spec Directory: docs/specs/create-workflow/ ║
║ Frame Type: CBF (Command-Behavior Frame) ║
╠═══════════════════════════════════════════════════════════════════╣
║ ║
║ 📁 STRUCTURE ║
║ ├── ✅ frame.yaml EXISTS ║
║ ├── ✅ acceptance.yaml EXISTS ║
║ ├── ✅ requirements/cbf-req-1-create-workflow.yaml ║
║ ├── ✅ machine/machine.yaml EXISTS ║
║ ├── ✅ machine/use-case.yaml EXISTS ║
║ └── ✅ controlled-domain/aggregate.yaml EXISTS ║
║ ║
║ 📋 FRAME DEFINITION ║
║ ├── ✅ FR1: Frame Type Valid PASS ║
║ ├── ✅ FR2: Frame Concerns Complete PASS ║
║ ├── ✅ FR3: Phenomena Defined PASS ║
║ └── ⚠️ FR4: Cross-Context Identified WARNING ║
║ └─ AuthorizationContext referenced but no ACL defined ║
║ ║
║ 📝 ACCEPTANCE CRITERIA ║
║ ├── ✅ AC1: Format Compliant PASS ║
║ ├── ✅ AC2: Traceability Complete PASS ║
║ └── ✅ AC3: Tests Anchor Defined PASS ║
║ ║
║ 🎯 DOMAIN EVENTS ║
║ ├── ✅ DE1: Standard Reference PASS ║
║ ├── ✅ DE2: No Duplicate Metadata PASS ║
║ └── ✅ DE3: Property Ordering PASS ║
║ ║
║ 🔒 INVARIANTS ║
║ ├── ✅ INV1: Enforced Location PASS ║
║ ├── ⚠️ INV2: Violation Tests WARNING ║
║ │ └─ 2/5 invariants missing violation tests ║
║ └── ✅ INV3: Shared Standards PASS ║
║ ║
╠═══════════════════════════════════════════════════════════════════╣
║ TOTAL: 14/16 PASS, 2 WARNINGS, 0 ERRORS ║
║ STATUS: ⚠️ CONDITIONAL PASS ║
╚═══════════════════════════════════════════════════════════════════╝
問題詳情
validation_issues:
- id: SCV-001
check: FR4
severity: warning
location: "frame.yaml#cross_context_dependencies"
message: "AuthorizationContext referenced but no ACL specification found"
current: |
cross_context_dependencies:
- context: AuthorizationContext
dependency_type: query
expected: |
# Should have corresponding file:
cross-context/authorization.yaml
suggestion: |
Run: analyze-frame --add-acl AuthorizationContext
- id: SCV-002
check: INV2
severity: warning
location: "controlled-domain/aggregate.yaml#invariants"
message: "Invariants missing violation tests"
missing_tests:
- invariant: "workflow_name_unique_in_board"
expected_test: "should reject duplicate workflow name"
- invariant: "max_stages_limit"
expected_test: "should reject when exceeding max stages"
與其他 Skills 協作
┌─────────────────────────────────────────────────────────────────┐
│ Validation Pipeline │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────┐ │
│ │ spec-compliance- │ ◄── 本 Skill (第一道防線) │
│ │ validator │ │
│ │ (規格完整性驗證) │ │
│ └───────────┬─────────────┘ │
│ │ Spec 完整 │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ code-reviewer │ │
│ │ (程式碼審查) │ │
│ └───────────┬─────────────┘ │
│ │ Code 符合規格 │
│ ▼ │
│ ┌─────────────────────────┐ │
│ │ multi-model-reviewer │ │
│ │ (多模型交叉驗證) │ │
│ └───────────┬─────────────┘ │
│ │ 三角驗證通過 │
│ ▼ │
│ ✅ Ready for PR │
│ │
└─────────────────────────────────────────────────────────────────┘
命令行工具
# 驗證單一規格目錄
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
docs/specs/create-workflow/
# 驗證所有規格
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
docs/specs/ --recursive
# 快速檢查 (只檢查結構)
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
docs/specs/create-workflow/ --quick
# 生成修復建議
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
docs/specs/create-workflow/ --fix-suggestions
# JSON 輸出
python ~/.claude/skills/spec-compliance-validator/scripts/validate.py \
docs/specs/create-workflow/ --format json
標準參考檔案
共用標準位置
shared_standards:
domain_events: "shared/domain-event-standard.yaml"
invariants: "shared/invariants-standard.yaml"
metadata: "shared/metadata-standard.yaml"
domain-event-standard.yaml 範例
# shared/domain-event-standard.yaml
standard:
name: "Domain Event Standard"
version: "1.0"
base_properties:
- name: id
type: EventId
description: "事件唯一識別碼"
- name: occurredOn
type: Instant
description: "事件發生時間"
- name: metadata
type: EventMetadata
description: "事件元資料 (correlationId, causationId, userId)"
usage:
includes_standard: true
standard_ref: "path/to/domain-event-standard.yaml"
# 使用標準後，只需定義特定屬性，base_properties 自動繼承
配置檔案
.spec-validator.yaml
version: "1.0"
structure:
strict: true
required_dirs:
- requirements
- machine
- controlled-domain
format:
acceptance: "acceptance_criteria" # new format
allow_legacy: false # reject old 'scenarios' format
traceability:
require_trace: true
require_tests_anchor: true
standards:
domain_events:
require_standard_ref: true
standard_path: "shared/domain-event-standard.yaml"
invariants:
require_enforced_in: true
require_violation_tests: true
ignore:
paths:
- "**/_draft/**"
- "**/_deprecated/**"
