SillySpec
规范驱动开发工具包 · 多 agent 时代的变更账本与确定性验收层
融合 Superpowers + OpenSpec + GSD，从「你说要啥」到「代码能跑」的完整流程
兼容 Claude Code / Cursor / Codex / OpenCode / OpenClaw / Gemini
📖 在线文档 · 🐙 GitHub
---
> 💡 **核心理念：Code is Cheap, Context is Expensive.**
>
> 文档是核心资产，代码是文档的产物。没有文档就没有代码——文档是 AI 的记忆，是团队协作的基础，是后续维护的唯一依据。
## 它解决什么问题
AI agent（Claude Code / Cursor 等）直接上手编码时，容易跳过需求澄清、方案设计、任务拆解这些关键步骤，产出偏离预期、且无法审计。
更要命的是**多 agent 并行**：多个会话同时改一个仓库时，谁改了哪个文件分不清、任务编号会被抢注、测试结果靠自报、中断即失忆、跨仓改动误伤用户在途文件。
SillySpec 把一个变更的完整生命周期固化为一组**强制阶段**——每个阶段都有明确的入口契约、产物文件名和门禁校验，AI 必须按状态机推进，不能跳步、不能偷工。进度、决策、产物全部持久化到 SQLite，可审计、可回溯、可断点恢复。**纪律不靠模型自觉，靠进程、磁盘和门禁：自报的不算，CLI 亲自跑过的才算。**
## 快速开始
需要 Node.js >= 22.13，一条命令完成初始化：
```bash
npx sillyspec init
```
首次运行会自动安装 CLI，并检测你正在使用的 AI 工具。之后 `/sillyspec:brainstorm`、`sillyspec progress show` 等命令即可直接使用。
**指定 AI 工具：**
| 工具 | `--tool` | 产物位置 |
|---|---|---|
| Claude Code（推荐） | `claude` | `AGENTS.md`（完整指引）+ `CLAUDE.md`（`@AGENTS.md` 指针）+ `.claude/skills/sillyspec-*/` |
| Cursor | `cursor` | `.cursor/skills/sillyspec-*/` |
| OpenAI Codex | `codex` | `AGENTS.md`（完整指引） |
| OpenClaw | `openclaw` | `.openclaw/skills/sillyspec-*/` |
| OpenCode | `opencode` | `AGENTS.md`（完整指引）+ `.opencode/skills/sillyspec-*/` |
| Gemini | `gemini` | `AGENTS.md`（完整指引） |
```bash
npx sillyspec init --tool claude # 指定工具
npx sillyspec init --dir /path/to/x # 指定项目目录
npx sillyspec init --interactive # 完整引导
```
## 平台支持
SillySpec 进度库使用 SQLite 持久化（基于 Node.js 内置的 `node:sqlite` 模块，纯 JS 无原生编译依赖）。
- **Node.js 版本要求 >= 22.13.0**：`node:sqlite` 自 v22.13.0 起免 `--experimental-sqlite` flag 直接可用。支持 Linux x64、macOS x64 / arm64、Windows x64 等所有 Node.js 官方支持平台。
- **零编译安装**：`node:sqlite` 是 Node.js 内置模块（官方预编译发行，非纯 JS 实现），不依赖 node-gyp / C++ 工具链或任何第三方原生绑定，npm install 即装即用，无平台编译失败风险。
## 从哪里开始
| 场景 | 命令 |
|---|---|
| 全自动，一句话到代码 | `/sillyspec:auto <需求描述>` |
| 全新项目（空目录） | `/sillyspec:init` |
| 已有代码的项目 | `/sillyspec:scan` |
| 多项目工作区 | `/sillyspec:workspace` |
| 随时自由思考 | `/sillyspec:explore "想法"` |
## 完整工作流
```
绿地：init → brainstorm → plan → execute → [verify] → archive
棕地：scan → brainstorm → plan → execute → verify → archive
全自动：auto（自动推进全部阶段，支持用户确认门控）
大模块：brainstorm（多图）→ 拆分 → MASTER.md → 逐 stage 全流程 → archive
```
**也可以跳过完整流程：**
- 小改动：`/sillyspec:flow "修复 xxx"`
- 不确定做什么：`/sillyspec:explore`
- 中断恢复：`/sillyspec:resume`
- 不知道下一步：`/sillyspec:continue`
## 命令一览
### 核心流程
| 命令 | 用途 |
|---|---|
| `/sillyspec:init` | 绿地项目：深度提问 → 需求文档 → 路线图 |
| `/sillyspec:scan` | 棕地项目：扫描代码库，生成 7 份架构文档 + 模块映射 |
| `/sillyspec:brainstorm` | 需求探索 + 规范生成：产出 design.md + tasks.md |
| `/sillyspec:plan` | 实现计划：文件路径 + 任务描述 + Wave 拓扑分组 |
| `/sillyspec:execute` | TDD 执行：子代理并行 + worktree 隔离 |
| `/sillyspec:verify` | 验证：对照规范 + 测试套件 + 代码审查 |
| `/sillyspec:archive` | 归档：规范沉淀到 knowledge/ |
| `/sillyspec:auto` | 全自动推进全部阶段 |
### 辅助工具
| 命令 | 用途 |
|---|---|
| `/sillyspec:status` · `/sillyspec:state` | 查看进度 / 当前工作状态 |
| `/sillyspec:continue` | 自动判断并执行下一步 |
| `/sillyspec:explore` | 自由思考：画图、讨论、调研、HTML 原型 |
| `/sillyspec:flow` | 轻量变更（默认快道）：需求明确的小改动两步收口 |
| `/sillyspec:resume` | 恢复工作（支持大模块阶段进度） |
| `/sillyspec:doctor` | 项目自检与状态修复 |
| `/sillyspec:commit` | 智能提交 |
| `/sillyspec:push` | 推送前压扁本地未推送提交并快进推送 |
| `/sillyspec:workspace` | 多项目工作区管理 |
| `/sillyspec:export` | 导出成功方案为可复用模板 |
## CLI 命令
```bash
sillyspec run 执行阶段（auto/brainstorm/plan/execute/verify/archive/scan/explore）
sillyspec run --done 完成当前步骤并推进到下一步
sillyspec run --status 查看阶段进度
sillyspec progress show 显示当前项目状态
sillyspec push 推送前压扁本地未推送提交并快进推送（默认 by-change）
sillyspec init 初始化（零交互，自动检测工具）
sillyspec setup 安装推荐 MCP 工具（交互式）
sillyspec setup --list 查看已安装 MCP 状态
sillyspec doctor 全量自检 + 修复进度
sillyspec change-delete <变更名> 删除变更（DB status=deleted 与归档语义分离；默认 dry-run，--confirm 执行）
```
## 核心特性
> 完整能力地图与对外叙事基准：[docs/sillyspec/capability-highlights-2026-09-14.md](docs/sillyspec/capability-highlights-2026-09-14.md)
**第一层：护城河（外部状态，模型能力不可替代）**
- **多 agent 并发控制** — 会话/变更/worktree 三级隔离；文件锁 ID 分配 + 双占用 fail-closed 硬拦；`--files` 边界声明切分"这是谁改的"；`--done` 前并发写预检告警他者未提交改动；平台同步乐观锁（base_ts + 身份 + 服务器权威钟）+ 冲突血统归属（自回声不误报）
- **实测验收门禁** — verify 收尾时 CLI **亲自执行** test / lint 与 agent 自报对账，不符即阻断回滚；docHash 重算比对 + git 提交证据交叉对账防伪造；门禁跑在隔离快照，不受并行会话脏文件污染
- **持久账本 + 断点恢复** — SQLite（node:sqlite）单一进度源，进度/决策/审批答复全落库，跨会话跨天续跑；quicklog 四字段结构化台账可检索
- **跨仓变更管理** — task 卡声明 `repo:` 字段即可管理跨仓任务：同构 worktree 隔离、base 锚快照、apply 永不覆盖用户在途改动
**第二层：确定性对账（机械核验，零模型轮次）**
- **范围对账** — 计划改动 × 实际改动三态对账（planned / unplanned / untouched），"偷偷改了计划外的东西"会被告警
- **API 契约矩阵** — 自动识别 task 间 provider / consumer 关系，后端完成提取 endpoint 契约注入前端 task，verify 阶段前后端 API parity 对账
- **文档一致性棘轮** — 文档里源码引用真实性校验（HEAD 模式），失败数只降不升
- **noAI 下沉** — 机械轮次（骨架预生成 / 上下文注入 / 归档核对代算）下沉为 CLI 代码，判断层留给 agent，token 成本与模型能力同向优化
**第三层：协作与流程**
- **规范驱动 + 阶段状态机** — 入口契约 / 产物文件名 / 门禁校验强制流转，不能跳步
- **子代理并行 + Wave 拓扑排序** — depends_on 自动排序，同 Wave 并行执行
- **Worktree 隔离** — execute 在独立 git worktree 中工作，不污染主分支
- **分层独立审查** — Design Grill / stage review / task review 带 provenance 盖章
- **跨机派发** — 子代理任务可派到 SillyHub MCP 远端 worker 池，自动探测回退本机
- **平台同步（可选）** — 对接 SillyHub：文档同步 + 团队审批 + 本地 agent 会话日志路径主动上报（支持 Claude Code / Codex / ZCode 自动探测，其他 CLI 用 `SILLYSPEC_AGENT_LOG` 显式指定）；本地独立使用功能完整
- **棕地入库** — scan 扫描已有代码库生成 7 份架构文档 + 模块映射
- **知识飞轮** — 模块知识按需注入、成功变更 export 为模板、决策 D-xxx@vN 版本化
**第四层：自我运维**
- **doctor 自诊自愈** — 13 维诊断，幽灵 worktree / 僵尸会话自动归档
- **摩擦计数** — 门禁回滚 / 实测失败 / 审查打回结构化计数，喂改进循环
- **dashboard 可视化** — 本地 Web 进度面板（`packages/dashboard/`）
## 可靠性保障
SillySpec 不只是 prompt，还有硬校验兜底：
- **锚定确认** — 各阶段执行前必须逐个确认读过规范文件
- **Hard Gate 自检** — 关键命令生成文件后强制自检格式，不通过则修正
- **postcheck 识别偷懒** — 自动识别占位符、fallback、未分析等 AI 偷懒模式
- **归档确认** — archive 操作前展示内容等待用户确认
## 防幻觉机制
| 环节 | 机制 |
|---|---|
| scan | 强制扫描代码库结构 / 约定 / 集成 / 测试 / 债务，生成 7 份文档 |
| brainstorm | 必须读 ARCHITECTURE.md 数据模型，支持原型图分析 |
| execute | 写代码前强制读现有源码，禁止编造方法调用 |
| 全流程 | postcheck + 硬门兜底 |
## MCP 增强
通过 `sillyspec setup` 一键安装 MCP 工具，增强 AI 能力：
- **Context7** — 查询最新库文档和 API 参考
- **Chrome DevTools** — 浏览器自动化，支持 E2E 验证
## 目录结构
```
sillyspec/
├── bin/sillyspec.js # CLI 入口（shebang）
├── src/
│ ├── index.js # 命令分发
│ ├── run.js + run/ # 阶段状态机引擎（barrel + 实现模块）
│ ├── init.js / setup.js # 初始化 + MCP 工具安装
│ ├── progress.js / db.js # SQLite 进度存储（facade + 实现）
│ ├── sync.js # SillyHub 平台同步
│ ├── workflow.js # 工作流编排 + postcheck
│ ├── worktree*.js # worktree 隔离执行
│ ├── dispatch/ # 任务派发（本地 agent / SillyHub MCP）
│ ├── sillyhub-mcp/ # SillyHub MCP 客户端
│ ├── hooks/ # worktree 守卫等钩子
│ └── stages/ # 各阶段定义（scan/brainstorm/plan/execute/verify/...）
├── templates/workflows/ # 工作流定义（scan-docs / archive-impact）
├── test/ # 原生 node:test 测试套件
├── packages/dashboard/ # 独立可视化面板子包
├── SKILL.md # 技能描述
└── README.md
```
## 致谢
- [Superpowers](https://github.com/obra/superpowers) — 工程纪律
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — 需求管理
- [GSD](https://github.com/gsd-build/get-shit-done) — 上下文工程
## License
MIT