spec-vc

一个在 Claude Code 中运行的变更治理工具。它试图解决一个问题：软件开发中，"为什么这么做"和"应该做什么"这两层信息往往散落在 PR、Slack、口头讨论里，事后很难追溯。

设计理念

传统版本控制（Git）只记录"做了什么"。spec-vc 在此基础上补了两层：

• ADR（Architecture Decision Record）：记录"为什么这么做"——决策的背景、权衡和结论
• Spec（形式化规格）：记录"应该做什么"——接口契约、数据形状、行为规则，用 OpenAPI / JSON Schema / Gherkin 描述

三层叠在一起，形成一个从"为什么"到"做什么"到"做了什么"的完整链路。

核心原则是：先澄清，再落计划，再改代码。轻量改动允许简化路径（[ADR-none]），不强制走完整流程。

架构

spec-vc/
├── src/spec_vc/          # Python CLI
│   ├── cli.py            # 命令路由
│   ├── adr.py            # ADR 领域模型
│   ├── spec.py           # Spec 领域模型
│   ├── change.py         # 变更状态机
│   ├── commit.py         # commit 验证协议
│   ├── hooks.py          # Git hook 校验
│   └── ...
├── templates/            # ADR/Spec/commit 模板
├── hooks/                # Git hook 脚本
└── SKILL.md              # Claude Code skill 入口

初始化到项目后：

<project>/
├── doc/arch/
│   ├── adr-NNN.md        # ADR 文件
│   ├── specs/NNN/        # Spec 目录（dev-doc + 形式化文件）
│   └── plans/            # 执行方案
├── .spec-vc.toml         # 项目配置
└── .git/hooks/           # commit-msg hook

运行流程

一个变更从开始到结束的典型路径：

用户提出变更意图
    ↓
skill load → 意图分类 → 确认需要 ADR
    ↓
clarify：自然语言对齐（动机、边界、设计、实现、验证、风险）
    ↓
plan：落为结构化计划文件
    ↓
spec：创建形式化规格（如果涉及接口/数据/行为）
    ↓
pre-validation：修改前验证口径
    ↓
代码修改
    ↓
post-validation：修改后验证
    ↓
commit prepare：AI 生成 manifest + subagent 审计（不写 token）
    ↓
commit submit：用户在终端手动提交（TTY 检测 + 交叉比对 + 写 token）
    ↓
close：回填 ADR 摘要，关闭变更

轻量改动（文档修改、小修小补）可以走 [ADR-none] 路径，跳过完整流程。

spec-vc commit 做了什么

两阶段提交协议，AI 做验证，用户在终端手动提交：

commit prepare（AI 执行）：Spec 就绪检查 → 生成 manifest → 分配 subagent 审计和测试 → 机械化 verify → 语义审查 → 提示用户下一步

commit submit（用户终端执行）：TTY 检测 → manifest 交叉比对 → verify → 交互确认 → 写 hash chain token → git commit

commit-msg hook 在提交通路二次校验 token 内哈希链，确保报告未被篡改。

快速使用

安装

git clone https://github.com/ArcaneOrion/spec-vc.git ~/.claude/skills/spec-vc
cd ~/.claude/skills/spec-vc
uv sync

初始化项目

在 Claude Code 中进入你的项目目录，运行：

/spec-vc init

提交代码

AI 完成代码修改和审计后，在终端运行：

spec-vc commit submit

AI 会先执行 commit prepare 完成 subagent 验证流程，然后提示你在终端手动提交。

其他命令

其余命令（adr new、spec new、spec formalize 等）由 AI 在对话流程中自动执行，一般不需要手动输入。

Commit message 规范

<type>(<scope>): <subject> [ADR-NNN]

示例：

feat(auth): 引入 LDAP 客户端 [ADR-007]
refactor(core): 拆分 message bus 为独立模块 [ADR-012]
docs: 修正 README 拼写 [ADR-none]

[ADR-none] 仅限不影响架构的改动。

紧急绕过

当 spec-vc binary 损坏、skill 路径变更或 venv 错乱导致 commit 被 token 门禁锁死时，可临时绕过：

SPEC_VC_BYPASS=<原因> git commit -m "fix: ... [ADR-001]"

绕过时 hook 会向 .git/spec-vc-bypass.log 写入一行审计记录（时间 | 原因 | commit subject）。建议原因字段填写 hotfix / ci / bisect / migration / repair，便于事后追溯。

如果环境变量方式自身也失效，最终兜底方案：

chmod -x .git/hooks/commit-msg  # 让 git 跳过 hook（git 原生行为）

绕过是临时应急手段，不替代正常流程。修改完成后建议恢复 hook 并重新走 spec-vc commit 路径。

友情链接

• Linux.do

License

MIT