name: sddl description: "Spec-Driven Development Loop：以结构化 Spec 为单一事实来源，双 Loop（形成 Loop 需求→冻结 Spec，派生 Loop Spec→tests/code/docs）驱动开发。Use when 用户要开始新项目开发、用 AI 写代码、规划系统设计、做需求分析、写测试、写文档、或任何需要"先定义清楚再动手"的开发任务。分阶段命令：/sddl:init /sddl:interview /sddl:spec /sddl:confirm /sddl:freeze /sddl:derive /sddl:verify /sddl:archive。" version: 1.0.0 author: 小智 license: MIT metadata: hermes: tags: [sdd, spec-driven, development-workflow, ai-coding, quality, formation-loop] related_skills: [writing-plans, test-driven-development, hermes-agent-skill-authoring]

Spec-Driven Development Loop (SDDL)

已开源：https://github.com/xt-mahh/sddl (2026-08-06, MIT License) 完整方法论 + 检查器脚本 + 示例项目见 GitHub 仓库。

Overview

SDDL 把 AI 编程从"对话驱动"升级为"规格驱动"。核心承诺：先定义清楚做什么，再动手写代码——以结构化 Spec 为单一事实来源，双 Loop 闭环保证质量和可审计性。

形成 Loop（回答"做什么"）       派生 Loop（回答"怎么做对"）
需求 ──▶ 访谈 ──▶ Spec草稿 ──▶ 冻结 Spec ──▶ tests/code/docs ──▶ 收敛
              └─▶ SQC质量检查 ──┘                  └─▶ C1-C4一致性检查 ─┘
              └─▶ 决策点确认 ──┘

为什么用 SDDL：对话式编程的痛点——上下文漂移（聊 50 轮忘了第 3 轮的约定）、多 artifact 不同步（代码改了测试/文档没跟上）、验收主观化（"感觉对了"代替"符合规格"）。SDDL 用稳定可全文加载的 Spec + 分层一致性检查解决三者。

When to Use

触发：

用户要开始新项目开发、写核心功能、设计系统架构
用户说"先规划""先设计""先写规格""这个功能怎么做"
用户需要多个 artifact（代码+测试+文档）同步产出的任务
项目接口 ≥ 5 个，或 must 级验收 ≥ 5 个，预期生命周期 > 2 周

不适用（直接写代码，不要用本 skill）：

一次性脚本 / 原型 / POC / 探索性研究代码
单文件小工具（接口 < 5，无多 artifact 需求）
用户明确说"直接写""快速做"

分阶段命令（本 skill 的核心交互方式）：

命令	阶段	做什么	产出
`/sddl:init`	初始化	建目录结构、读已有代码/需求	`sddl/` 骨架 + `state.yaml`
`/sddl:interview`	形成	分层需求访谈（L0-L2 必答）	需求陈述
`/sddl:spec`	形成	生成 L1-L5 spec 草稿 + 决策点标记	`specs/<domain>/spec.yaml`
`/sddl:confirm`	形成	决策点摘要 clarify 确认	`decisions/<domain>-confirmation.yaml`
`/sddl:freeze`	形成	SQC 检查 + 冻结	`spec_status: frozen`
`/sddl:derive`	派生	从 spec 派生 tests/code/docs	`src/ tests/ docs/`
`/sddl:verify`	派生	C1-C4 一致性检查 + 收敛判定	`checks/*.json` + 收敛/路由
`/sddl:archive`	归档	变更归档、spec 合并	`specs/` 更新 + CHANGELOG

核心原则

Spec 是神谕，但可被质疑：派生中发现的 spec 缺陷 → 解冻 → 回形成 Loop 修订 → 重新冻结（走完整质量门禁，不绕过）
确定性优先：能用静态分析/schema/测试执行解决的，绝不用 LLM 猜
收敛是工程系统：硬条件门禁 + 软条件共识率 + 预算约束 + 人工兜底
决策点不静默：模糊处 AI 给默认值 + 标记决策点，用户确认后才冻结
进度即目录：阶段完成 = 文件存在（Convention over Config），中断恢复免费

目录即状态（Convention over Config）

不看状态文件，看目录就知道进度。这是本 skill 的进度可见性机制（配合 git commit 作为 checkpoint）。

<project>/
├── sddl/
│   ├── specs/                    # 存在 = 访谈完成，spec 已生成
│   │   └── <domain>/spec.yaml    # status: frozen = 冻结完成
│   ├── changes/                  # 变更提案（增量开发，可并行）
│   ├── decisions/                # 决策点确认记录
│   │   └── <domain>-confirmation.yaml
│   ├── checks/                   # 检查报告存档（机器可读 JSON）
│   │   ├── sqc-<domain>-v1.json
│   │   └── c1-c4-<domain>-v1.json
│   └── state.yaml                # 唯一元数据：阶段指针 + 预算 + 最近检查
├── src/                          # 派生 Loop 后出现
├── tests/                        # 派生 Loop 后出现
├── docs/                         # 派生 Loop 后出现（含 current/planned 分区）
└── (git commit 在每个阶段完成时)

state.yaml 最小化（只存指针，不存进度详情）：

spec_status: frozen          # interviewing | drafting | reviewing | frozen | evolved
current_phase: derivation    # formation | derivation | complete
budget: { formation: 40%, implementation: 12%, revision: 100% }
last_check: { type: sqc, spec: auth-v0.1.0, result: pass, at: 2026-08-06T16:00 }

恢复规则：skill 重新加载时扫目录——specs/ 无 = 从 interview 开始；specs/ 有但无 decisions/ = 从 confirm 开始；decisions/ 有但 spec 未 frozen = 从 freeze 开始；src/ 有但无 checks/ = 从 derive 开始；checks/ 有 = 从 verify 开始。

阶段完成 = git commit（E 辅助）：每个命令成功结束后 commit（feat(sddl): interview complete），保证可回溯。

双 Loop 流程编排

形成 Loop（做对的事）——5 个命令

/sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
     │              │              │              │
     └─ 修订 ──────┴──────┴──────┘
       （SQC 不过 / 用户改决策点 → 回上一步，最多 5 轮）

命令	关键动作	检查点
interview	分层提问 L0-L2（≤10 问必答），产出需求陈述	需求陈述完整
spec	生成 L1-L5 spec + 决策点标记（模糊处登记 DP）	SQC-def 骨架通过
confirm	决策点摘要 → clarify 逐项确认（含自定义输入）	决策点无 pending
freeze	SQC 全检 + 确认记录签署	SQC 无 blocker + frozen

派生 Loop（把事做对）——3 个命令

/sddl:derive → /sddl:verify → (收敛) → 完成
     │              │
     └─ 路由 ───────┘
       （violation → 重派 code/tests/docs 或 解冻回形成 Loop）

命令	关键动作	检查点
derive	从 spec 派生 tests/code/docs	artifacts 可运行
verify	C1-C4 分层检查 + 收敛判定	硬门禁 + 软共识 + must 覆盖
archive	变更归档、spec 合并	CHANGELOG + spec 更新

检查器脚本（scripts/）——确定性证据，不是语义判断

脚本只负责确定性证据（类型检查/测试执行/符号表/YAML），语义审核由 agent 的 LLM 能力执行：

# SQC 确定性检查（形成 Loop 门禁）—— 脚本给出事实
python3 scripts/check_sqc.py sddl/specs/<domain>/spec.yaml --verbose

# C1-C4 确定性检查（派生 Loop 门禁）—— 脚本给出事实
python3 scripts/check_c1_c4.py . --verbose

# 状态恢复（中断后）—— 扫目录输出当前进度 + 下一步命令
python3 scripts/sddl_status.py .

退出码：0 = pass/converged，1 = fail（可挂 CI）
--json 输出机器可读证据（供 LLM 审核引用）

分工原则（重要）：

层	谁负责
确定性证据（硬条件）：schema 合法/接口存在/测试通过/符号表	脚本
语义审核（软条件）：行为覆盖/THEN 可断言/测试真覆盖/文档真实性	agent 的 LLM（见 `references/llm-review.md`）

不要用脚本启发式做语义判断——字符串匹配会假阴性爆炸（T1 实测 C1-sem 0.48）。脚本是证据收集器，agent 是裁判。

何时读哪个 Reference

按需加载，不一次全读（渐进披露）：

场景	读
执行 interview	`references/formation-loop.md`（阶段 1）
生成 spec	`references/spec-schema.md` + `templates/spec-template.yaml`
SQC 检查	`references/sqc-checklist.md`（def 用脚本，sem 用 LLM）
决策点确认	`templates/decision-summary.md`
派生 artifacts	`references/derivation-loop.md`（阶段 1-2）
C1-C4 检查	`references/checker-matrix.md`（def 用脚本，sem 用 LLM）
语义审核操作	`references/llm-review.md`（核心：LLM 如何做审核）
路由/回写/预算	`references/derivation-loop.md`（阶段 3-5）
变更提案	`references/formation-loop.md`（变更管理）

预算与降级

三预算：formation（2M token / 5 轮）/ implementation（15M / 4 sessions）/ revision（5M，L2 扣 10%、L3 扣 25%、首次 L3 免费）
预算记录在 state.yaml，每命令更新
预算耗尽 → 转人工驱动，不自动降级（spec 质量是地基）
降级路径：D1 语义降级 → D2 should/could 移风险清单 → D3 缩变异 → D4 拆 spec → D5 最佳努力交付

体验规范（重要）

分阶段命令：绝不在一个回复里跑完整个双 Loop——每个命令是独立交互单元，之间有检查点
决策点用 clarify，自定义输入显式可见：每个决策点一个 clarify，附影响说明；choices 业务选项 ≤3 个，第 4 位固定放"自定义输入（Other）"（实测 clarify 无自动 Other、choices 上限 4，必须显式占位）；question 文本提示"其他值请选自定义输入"；用户自定义值走捕获协议（记录 value+reason → 同步 spec → 确认记录标 modified）；开放式决策点直接用无 choices 的 clarify
进度可见：每个命令开始/结束时报告当前阶段 + 下一步
状态写入：每个命令结束写 state.yaml + git commit
检查报告：每次检查（SQC/C1-C4）写 checks/*.json，报告可读摘要 + 机器可读详情

Common Pitfalls

跳过形成 Loop 直接派生——Spec 没冻结就写代码 = 回到对话式编程。/sddl:freeze 是硬边界，未冻结不派生。
决策点静默决定——模糊处不标记 DP 直接写默认值 = 用户意图失真。任何"替用户选择"必须登记 DP。
检查器自证循环——信任 AI 贴的标签。C1-def 必须做结构反推（解析测试 AST），不信任标签。
语义检查绝对分数——LLM 打 0-100 分不可信。用 Checklist 二分 + 投票共识率（客观计票）。
回写绕过质量门禁——spec_error 直接改 spec = 自我放松标准。必须解冻 → 回形成 Loop → 重新冻结。
状态文件膨胀——把所有进度写进 state.yaml = 又回到"文档谎言"。state.yaml 只存指针，详情在文件本身。
预算无记录——不更新 state.yaml 预算 = 成本失控。每命令结束更新。
语义检查用粗糙字符串匹配——T1 实测：关键词匹配把 C1-sem 打到 0.48（假阴性爆炸）。优先用 Checklist LLM 投票；启发式仅作 fallback，且必须语义化（AST 提取断言 + 结构化关键词），首轮结果不可信，需人工复核。
测试间共享状态泄漏——T1 实测：内存 store 跨测试共享导致断言失败。派生时必须加隔离 fixture（autouse 重置）；测试断言走公开接口，不直接访问内部 _store。
纯查询函数带副作用——T1 实测：detectDiscrepancy 内部改 status 违反 spec B006（应保持 draft）。纯查询接口（返回报告/查询）不得修改状态，C2-sem 应检查。

Verification Checklist

One-Shot Recipes

从零开始新项目

/sddl:init → /sddl:interview → /sddl:spec → /sddl:confirm → /sddl:freeze
           → /sddl:derive → /sddl:verify → /sddl:archive

已有代码回填 spec（改造项目）

/sddl:init（读已有代码）→ /sddl:spec（反向提取现状 + 标记决策点）
  → /sddl:confirm → /sddl:freeze → /sddl:verify（验证 spec↔code 一致性）

增量功能开发（spec 已冻结）

/sddl:init → 写 changes/<name>/ 提案 → /sddl:confirm（受影响决策点）
  → /sddl:freeze → /sddl:derive → /sddl:verify → /sddl:archive

xt-mahh/sddl

What is sddl?

Ask in your favorite AI

Documentation

Spec-Driven Development Loop (SDDL)

Overview

When to Use

核心原则

目录即状态（Convention over Config）

双 Loop 流程编排

形成 Loop（做对的事）——5 个命令

派生 Loop（把事做对）——3 个命令

检查器脚本（scripts/）——确定性证据，不是语义判断

何时读哪个 Reference

预算与降级

体验规范（重要）

Common Pitfalls

Verification Checklist

One-Shot Recipes

从零开始新项目

已有代码回填 spec（改造项目）

增量功能开发（spec 已冻结）

相关 Skill

Related Skills

steipete/notion

affaan-m/seo

affaan-m/brand-voice

affaan-m/crosspost

affaan-m/x-api

affaan-m/content-engine