Spec Driven Dev

spec-driven-dev

适用于 Claude Code / OpenCode Runner 的阶段门控规格驱动开发工作流 Skill。 在 init 阶段克隆远程 Git 仓库，随后在该仓库内驱动每个生命周期阶段——强制产出产物、在迭代边界提交、并在 release 阶段推送至远端。内置 code_review 阶段，执行 commit message 合规校验、代码质量门控与 LOGAF Checklist 评审，所有 HIGH 级问题清零后方可进入 release。支持通过 spec-driven-checkpoint Skill 在任意阶段保存 checkpoint，并使用 rollback {ckpt_id} 恢复 Git 状态和 Agent 上下文。支持多语言项目，遵循 OpenSkills 渐进加载原则。

前置依赖

二进制工具

环境变量

安全说明 — SPEC_DEV_GIT_TOKEN 仅通过 OpenClaw skills.entries.*.env 机制在运行时注入，绝不写入任何产物文件、日志或迭代摘要。凭据助手使用局限于当前 Agent 会话的本地 ~/.git-credentials 存储。

快速开始

# 1 – 克隆远程仓库并初始化 US 目录
init-US042
git_remote: https://github.com/my-org/my-repo.git
us_content: |
  ## US042 – OAuth2 登录
  作为用户，我希望使用 Google 账号登录。
  ### 验收标准
  - [ ] Google OAuth2 重定向正常
  - [ ] 回调后签发 JWT
context: "Python 3.11 + FastAPI。数据库为 PostgreSQL 15，不新增依赖。"

# 2 – 链式执行各阶段（git_remote 在 init 后自动持久化到 current_iter.md）
requirements-US042
architecture-US042
process_design-US042
project_plan-US042
coding-US042
test-US042
bugfix-US042        # 仅当 test 阶段报告 HIGH 级失败时执行
code_review-US042   # 三层门控：commit message + 代码质量 + LOGAF Checklist
release-US042       # 仅当 code_review 裁决为 APPROVED 或 APPROVED_WITH_NOTES 时解锁

输入变量

触发条件

本 Skill 在以下情况激活：

1. 阶段命令模式 — 用户输入 <stage>-<us_id>，例如：

   • init-US042
   • coding-US042
   • code_review-US042
   • release-FEAT_LOGIN

2. Checkpoint 命令 — 任意时刻均可触发：

   • save_checkpoint-{us_id} 或 checkpoint-{us_id} — 手动保存当前状态
   • rollback {ckpt_id} — 回滚到指定 checkpoint
   • rollback {ckpt_id} --git-only — 仅回滚 Git
   • rollback {ckpt_id} --context-only — 仅输出恢复 Prompt
   • list_checkpoints-{us_id} — 列出所有 checkpoint

3. 下一迭代意图 — 用户输入以下任意一种：

   • {us_id}进行下一个迭代
   • next iteration {us_id}
   • start|begin|run|execute … sprint|iteration|milestone

   → 自动从 requirements/{us_id}/docs/iteration_summary/current_iter.md 恢复上下文继续执行

路径常量

所有路径使用 {us_id}、{iter_id}、{version} 作为占位符。

requirements/US/{us_id}.md
requirements/{us_id}/docs/requirements.md
requirements/{us_id}/docs/architecture.md
requirements/{us_id}/docs/process_design.md
requirements/{us_id}/docs/project_plan.md
requirements/{us_id}/docs/tasks.json
requirements/{us_id}/docs/iteration_summary/current_iter.md
requirements/{us_id}/docs/iteration_summary/{iter_id}.md
requirements/{us_id}/docs/release_notes/{version}.md
requirements/{us_id}/docs/reports/test-{us_id}-report.md
requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md
requirements/{us_id}/docs/checkpoints/index.md
requirements/{us_id}/docs/checkpoints/{ckpt_id}.md
auxiliary/coding_standards.md
auxiliary/gitflow_guide.md
auxiliary/skills/available_skills.xml
src/
tests/
config/
CHANGELOG.md
PROJECT_STATUS.md
.github/workflows/ci.yml

执行协议

每次调用必须按顺序执行以下六步协议。

第 0 步 — 发出 stage_start 检查点

[SKILL:spec-driven-dev] CHECKPOINT stage_start STATUS=OK  us_id={us_id}  stage={stage}

第 1 步 — 验证输入

1. 确认 us_id 和 stage 已存在。
2. 若提供了 us_content，写入（或合并）到 requirements/US/{us_id}.md。
3. 若提供了 context，在内存中保存，并在本次产出的每个产物中以 ### 补充上下文 标题开头注入。
4. 解析 iter_id：
   • 若显式提供，直接使用。
   • 否则从 current_iter.md 中读取。
   • 若文件不存在，默认为 iter_001。
5. 解析 git_remote：
   • 若显式提供，使用并持久化到迭代摘要。
   • 否则从 current_iter.md 的 git_remote: 字段中读取。
   • 若仍不存在且当前阶段不是 init，发出警告后继续执行。

[SKILL:spec-driven-dev] CHECKPOINT inputs_validated STATUS=OK

第 2 步 — Skill 扫描（skip_skill_scan: true 时跳过）

1. 完整读取 auxiliary/skills/available_skills.xml。
2. 将可用 Skill 与当前阶段需求进行匹配。
3. 若找到匹配项，宣布：

   "我将调用 Skill：<n> 来辅助本次任务。" 随即完整加载 auxiliary/skills/<n>/SKILL.md 后再继续执行。

4. 禁止一次性加载所有 Skill — 每次只按需加载一个（渐进披露原则）。

[SKILL:spec-driven-dev] CHECKPOINT skill_scan_done STATUS=OK  skills_loaded=[…]

第 3 步 — 执行阶段

严格按照下方阶段定义章节执行。 每写完一个强制输出文件后发出：

[SKILL:spec-driven-dev] CHECKPOINT artefacts_written STATUS=OK  files=[…]

第 4 步 — 质量门控（仅 coding / test / bugfix 阶段）

按语言检测表运行静态检查和测试。

通过时：

[SKILL:spec-driven-dev] CHECKPOINT quality_gate_passed STATUS=OK

失败时：发出 STATUS=FAIL，汇总失败信息，并指示 Agent 进入 bugfix 阶段。 同一问题连续失败 5 次后，停止自动修复并请求人工介入。

第 5 步 — 写入迭代摘要

1. 递增 iter_id（如 iter_003 → iter_004）。
2. 使用下方模板写入 requirements/{us_id}/docs/iteration_summary/{iter_id}.md。
3. 用相同内容覆盖 requirements/{us_id}/docs/iteration_summary/current_iter.md。
4. 更新 PROJECT_STATUS.md。

[SKILL:spec-driven-dev] CHECKPOINT iteration_summary_written STATUS=OK  iter_id={iter_id}

第 6 步 — 发出 stage_done

[SKILL:spec-driven-dev] CHECKPOINT stage_done STATUS=OK
<stage_done>

阶段定义

init

目的： 从环境变量配置 Git 凭据、将远程仓库克隆到工作区、初始化 US 目录树，并将纯文本 git_remote URL 记录到迭代摘要，供后续所有阶段免密推拉使用。

读取： 无（从零启动）

写入：

• 克隆后的仓库（工作区根目录）
• requirements/US/{us_id}.md（脚手架或来自 us_content）
• 完整的 requirements/{us_id}/docs/ 目录树
• requirements/{us_id}/docs/iteration_summary/current_iter.md（存根）
• PROJECT_STATUS.md（初始条目）

凭据配置 — 按此顺序执行：

# 1. 从环境变量解析运行时值
GIT_USER="${SPEC_DEV_GIT_USERNAME:-oauth2}"
GIT_EMAIL="${SPEC_DEV_GIT_EMAIL:-bot@spec-driven-dev}"
GIT_TOKEN="${SPEC_DEV_GIT_TOKEN}"        # 必填；metadata.requires.env 已做门控

# 2. 构造带认证的克隆 URL（Token 内嵌，绝不写入产物）
#    兼容：https://github.com/…  https://gitlab.com/…  https://bitbucket.org/…
REMOTE_HOST=$(echo "${git_remote}" | sed 's|https://||' | cut -d'/' -f1)
CLONE_URL="https://${GIT_USER}:${GIT_TOKEN}@${REMOTE_HOST}/$(echo "${git_remote}" | sed "s|https://${REMOTE_HOST}/||")"

# 3. 克隆
git clone "${CLONE_URL}" .

# 4. 设置提交身份
git config user.name  "${GIT_USER}"
git config user.email "${GIT_EMAIL}"

# 5. 持久化凭据，供本工作区后续 push/pull 静默认证
git config credential.helper store
printf "https://%s:%s@%s\n" "${GIT_USER}" "${GIT_TOKEN}" "${REMOTE_HOST}" \
  >> ~/.git-credentials
chmod 600 ~/.git-credentials

Token 绝不写入任何产物或日志。 仅将不含凭据的裸 git_remote URL 存入 current_iter.md。

关键指令：

1. 在任何其他 git 操作前先执行凭据配置代码块。
2. 创建路径常量中尚不存在的所有子目录。
3. 若提供了 us_content，写入 requirements/US/{us_id}.md；否则写入含占位标题的 Markdown 脚手架。
4. 若提供了 context，在脚手架中注入 ### 补充上下文 节。
5. 在 current_iter.md 的 git_remote: 字段中记录纯文本 git_remote URL（不含 Token）。

requirements

读取：

• requirements/US/{us_id}.md
• auxiliary/coding_standards.md

写入：

• requirements/{us_id}/docs/requirements.md

关键指令：

1. 识别功能范围与边界。
2. 挖掘非功能性需求（性能、安全、兼容性）。
3. 定义可量化的验收标准。
4. 注入 context 至 ### 补充上下文。

architecture

读取：

• requirements/{us_id}/docs/requirements.md
• auxiliary/coding_standards.md
• auxiliary/gitflow_guide.md

写入：

• requirements/{us_id}/docs/architecture.md — 必须包含 Mermaid 架构图

关键指令：

1. 选择架构风格（微服务 / 模块化 / 单体）并说明理由。
2. 定义组件、职责与接口。
3. 说明技术选型决策。
4. 嵌入至少一张 mermaid 架构图。
5. 注入 context 至 ### 补充上下文。

process_design

读取：

• requirements/{us_id}/docs/architecture.md

写入：

• requirements/{us_id}/docs/process_design.md — 必须包含 Mermaid 流程图或状态图

关键指令：

1. 建模主执行流程（ReAct / Plan-and-Execute / 标准 CRUD，视情况选用）。
2. 详细描述每个步骤。
3. 定义异常处理与重试/降级行为。
4. 嵌入至少一张 mermaid 流程图或序列图。

project_plan

读取：

• requirements/{us_id}/docs/architecture.md
• requirements/{us_id}/docs/process_design.md

写入：

• requirements/{us_id}/docs/project_plan.md
• requirements/{us_id}/docs/tasks.json

关键指令：

1. 将工作拆解为粒度 1–3 天的任务，附里程碑、优先级和工时估算。
2. 按以下 Schema 产出 tasks.json：

   [
     {
       "id": "task-1",
       "name": "任务名称",
       "scope": "src/module/",
       "stage": "coding",
       "depends_on": []
     }
   ]

coding

读取：

• requirements/{us_id}/docs/iteration_summary/current_iter.md ← 优先读取
• requirements/{us_id}/docs/architecture.md
• requirements/{us_id}/docs/process_design.md
• requirements/{us_id}/docs/tasks.json
• auxiliary/coding_standards.md
• auxiliary/gitflow_guide.md

写入：

• src/ 下的源代码文件
• tests/ 下的测试文件

关键指令：

1. 优先读取 current_iter.md 了解历史进度。
2. 只实现当前迭代范围内的任务。
3. 使用类型注解、清晰命名和详细 docstring。
4. 遵循语言检测表对应的工具链。
5. 创建并切换到 feature/{task-name} 分支（GitFlow）。
6. 质量门控通过前禁止提交（由 test / bugfix 阶段完成）。
7. 将 context 注入相关模块级 docstring。

test

读取：

• src/ 下的源代码文件
• auxiliary/coding_standards.md

写入：

• requirements/{us_id}/docs/reports/test-{us_id}-report.md

关键指令：

1. 按语言检测表运行（或模拟）完整测试套件。
2. 报告：格式化 · Lint · 类型检查 · 测试结果 · 覆盖率 %。
3. 覆盖率目标：整体 ≥ 80%；关键模块 ≥ 90%。
4. 每个失败项输出：严重程度（HIGH / MEDIUM / LOW）及修复建议。
5. 立即修复 HIGH 级失败；将 MEDIUM / LOW 记录到 TODO。

bugfix

读取：

• requirements/{us_id}/docs/reports/test-{us_id}-report.md
• 失败的源代码 / 测试文件

写入：

• src/ 下更新后的源代码文件
• tests/ 下更新后的测试文件
• requirements/{us_id}/docs/reports/test-{us_id}-report.md（追加新条目）

关键指令：

1. 针对每个 HIGH 级失败：分析根因 → 修复 → 验证。
2. 每批修复后重新运行测试。
3. 所有 HIGH 级失败解决后，重新运行完整套件。
4. 自动修复上限为 5 次；超限后停止并请求人工介入。
5. 自动 Checkpoint 触发：同一问题连续失败 ≥ 3 次时，在第 3 次失败后立即调用 spec-driven-checkpoint：

   invoke_skill: spec-driven-checkpoint
   action: save
   with:
     us_id: "{us_id}"
     iter_id: "{iter_id}"
     stage: "bugfix"
     interrupt_reason: "bugfix_loop_{n}"
     pending_items: "修复失败的问题列表"