中文 | English
spec-manager 是给 AI 编程用的本地规格管理层。
它把一次需求从“聊天里的一句话”变成仓库里的可追踪交付链路：
L1 PRD -> L2 Design -> L3 Impl -> Agent Task -> Verification Evidence
适用于 Claude Code、Codex、OpenCode、MiMo-Code、CodeBuddy、Cursor、Windsurf 等 AI 编程工具。所有数据都落在本地 markdown / JSON 文件里，可 git diff、可 review、可被不同 Agent 接力；不需要后端、不需要数据库、不依赖 MCP。
AI 写代码已经很快，但真实项目里更常见的问题是：
- 需求说得太短，Agent 直接开写，后面发现方向错了。
- 多轮对话之后，AI 忘了之前为什么这么设计。
- 代码改完了，但没有任务记录、验证证据和决策上下文。
- UI 需求只说“高级一点”，没有稳定的设计上下文。
- 不同 AI 工具各管各的，项目记忆散在聊天记录里。
spec-manager 的价值不是让流程变重，而是让 AI 在动手前先进入项目上下文，在交付时留下证据。
- 少跑偏：先确认 L1/L2/L3，再进入实现，Agent 有冻结的目标和边界。
- 好审查：规格、任务、决策、验证记录都在仓库里，知道改了什么、为什么改、怎么验。
- 可接力：Claude、Codex、OpenCode、MiMo-Code、CodeBuddy、Cursor、Windsurf 都能读同一套本地文件。
- 有证据：Task step、verification evidence、acceptance report 让“完成了”不只是口头结论。
- 能管设计上下文：UI/视觉任务可读取
specs/DESIGN.md，把设计 prose、tokens、do/don't 约束一起交给 Agent。
# 1. 安装
npm install -g spec-manager
# 2. 初始化你的项目
cd my-project
spec-manager project init --name my-project
# 3. 给 AI 编程工具写入工作流入口
spec-manager project agents --provider all然后可以在终端先看 spec-manager 建议的安全下一步：
spec-manager next "新增用户认证"
spec-manager brief "新增用户认证"
spec-manager dashboard也可以直接对你的 AI 工具说：
使用 spec-manager 新增用户认证。
如果是 Claude Code / CodeBuddy skill：
/spec-manager 新增用户认证
Agent 会先创建规格并请求你确认，再进入实现。你可以只停在规格阶段 review，也可以继续让它创建 Task、执行、记录验证。
简单区分一下：
- 终端命令：
spec-manager next/brief/dashboard用来查看下一步、生成上下文和检查项目状态。 - AI 聊天请求：
使用 spec-manager ...或/spec-manager ...用来让 Agent 按工作流推进。
不想一开始理解全部概念，可以只记这几个命令：
spec-manager project init --name my-project
spec-manager project agents --provider all
spec-manager next "新增用户认证"
spec-manager brief "新增用户认证"
spec-manager dashboard
spec-manager project doctor如果你想自己手动推进完整链路：
spec-manager spec new L1 --topic auth --title "用户认证"
spec-manager spec update auth-L1 --content ./l1.md --ai-summary "..." --change-summary "init"
spec-manager spec confirm auth-L1
spec-manager spec new L2 --topic auth --parent auth-L1 --title "认证设计"
spec-manager spec confirm auth-L2.1
spec-manager spec new L3 --topic auth --parent auth-L2.1 --title "JWT 实现"
spec-manager spec confirm auth-L3.1.1
spec-manager task run auth-L3.1.1 --plan ./plan.jsonspec-manager spec confirm <L3> 只负责把 L3 冻结，不会自动创建 Task。确认并执行、创建并执行任务、继续执行这个 L3 时，推荐用 task run 显式合并冻结、创建 Task 和启动 Task。
如果 L3 已经 frozen，可以用一条命令创建并立即启动 Task：
spec-manager task create auth-L3.1.1 --plan ./plan.json --start如果你需要排查或拆解 Task 生命周期，也可以继续使用高级手动链路：
spec-manager task create auth-L3.1.1 --plan ./plan.json
spec-manager task start T-001 --spec auth-L3.1.1大多数时候，你不需要手动敲完这些。把工作流入口装进 AI 工具后，让 Agent 按 spec-manager 规则来做即可。
兼容旧入口仍然可用：spec-manager guide "需求"、spec-manager assist guide --request "需求"、spec-manager flow status --topic T 适合已有脚本或需要更细命令提示的场景。
spec-manager 在项目里维护这些文件：
my-project/
├── .spec-manager/
│ ├── config.yaml
│ ├── audit.json
│ └── incidents/
├── specs/<topic>/
│ ├── <topic>-L1.md
│ ├── <topic>-L2.1.md
│ ├── <topic>-L3.1.1.md
│ ├── decisions/
│ │ └── DC-001.md
│ └── tasks/
│ └── <specCode>-T-001.json
├── changes/<name>/
└── archive/<name>/
几个概念：
- L1 PRD：做什么，为什么做。
- L2 Design：技术方案和边界。
- L3 Impl：具体实施规格，冻结后才能写代码。
- Agent Task：Agent 执行步骤、状态、验证记录。
- Decision card：重要选择为什么这么定。
- Verification Evidence：测试、lint、build、design-lint 等可追踪证据。
默认情况下，spec-manager 把 .spec-manager/、specs/、changes/ 和 archive/ 放在当前项目里。这适合一个代码仓库独立管理自己的规格。
如果你的目标是“一个 specs 根管理多个代码仓库”，推荐建立独立规划仓库或共享 specs 目录，然后让各代码仓库通过 .spec-manager/config.yaml 指向它：
project_name: app-repo
specStore:
id: product-planning
path: ../product-specs
mode: write
contextSources:
- id: platform-specs
path: ../platform-specs
mode: read几个边界要记住：
- execution root：你当前运行命令的代码仓库。
- write root：spec/task/decision 实际写入的 specs 根；配置
specStore.path后，写命令会使用 resolved write root。 - context sources：只读上下文源，只给 brief/dashboard/context 读取，不参与写入。
写入前建议先检查：
spec-manager project context --json
spec-manager project store show
spec-manager project store doctor
spec-manager dashboard --json未配置 specStore 时，行为保持单仓库默认，不需要迁移已有 specs。当前版本不提供 --store <id|path> 覆盖，也不会自动迁移 specs；如果要启用多仓库模式，请先初始化目标 specs 根，再配置 code repo 的 specStore.path。
UI/视觉项目的设计上下文也跟随 write root 管理：推荐放在 resolved write root 的 specs/DESIGN.md。代码仓库根目录的 DESIGN.md 仍作为 legacy fallback。
一次安装所有支持的入口：
spec-manager agents install
# 等价别名
spec-manager skills install只安装某个工具时，直接使用平台名：
spec-manager claude install
spec-manager codex install
spec-manager cursor install
spec-manager install --platform kimi写入前预览：
spec-manager codex install --dry-run
spec-manager kilo install --dry-run旧入口仍然保留，适合脚本或更细 provider 控制：
spec-manager project agents --provider all
spec-manager project agents --provider codex
spec-manager project agents --provider list常用平台：
| 工具 | 推荐命令 | 写入内容 |
|---|---|---|
| Claude Code | spec-manager claude install |
CLAUDE.md, .claude/skills/spec-manager/ |
| CodeBuddy | spec-manager codebuddy install |
CODEBUDDY.md, .codebuddy/skills/spec-manager/ |
| Codex | spec-manager codex install |
AGENTS.md |
| OpenCode | spec-manager opencode install |
AGENTS.md |
| MiMo-Code | spec-manager mimocode install |
AGENTS.md |
| Cursor | spec-manager cursor install |
.cursorrules |
| Windsurf | spec-manager windsurf install |
.windsurfrules |
更多平台也可以直接装。没有专属原生格式的平台会使用 AGENTS-compatible fallback instructions，也就是写入通用 AGENTS.md，不会声称已经完成原生 IDE 集成。
| 平台 | 命令 |
|---|---|
| Kilo Code | spec-manager kilo install |
| GitHub Copilot CLI | spec-manager copilot install |
| VS Code Copilot Chat | spec-manager vscode install |
| Aider | spec-manager aider install |
| OpenClaw | spec-manager claw install |
| Factory Droid | spec-manager droid install |
| Trae | spec-manager trae install |
| Trae CN | spec-manager trae-cn install |
| Gemini CLI | spec-manager gemini install |
| Hermes | spec-manager hermes install |
| Kimi Code | spec-manager kimi install 或 spec-manager install --platform kimi |
| Amp | spec-manager amp install |
| Kiro IDE/CLI | spec-manager kiro install |
| Pi coding agent | spec-manager pi install |
| Devin CLI | spec-manager devin install |
| Google Antigravity | spec-manager antigravity install |
这些命令用于让 Agent 更稳地工作，而不是替代完整流程：
spec-manager next "新增用户认证" # 输出当前最安全下一步
spec-manager brief "优化登录页视觉" # 生成 Agent Brief，UI 请求会带上 Design Context
spec-manager dashboard # 查看项目/topic 摘要
spec-manager assist guide --request "新增用户认证" # 兼容旧入口：读取本地上下文并建议下一步
spec-manager assist critique auth-L1 # 审查规格质量缺口
spec-manager assist next T-001 --spec auth-L3.1.1 # 查看任务下一步和证据状态
spec-manager assist drift T-001 --spec auth-L3.1.1 # 对账实际变更是否偏离 L3 范围
spec-manager assist acceptance T-001 --spec auth-L3.1.1 # 汇总验收证据和残余风险
spec-manager assist delivery T-001 --spec auth-L3.1.1 # 生成面向用户的交付摘要做 UI、视觉、样式相关任务时，推荐把设计上下文放在：
specs/DESIGN.md
它是 spec-manager 管理的 specs 体系的一部分。根目录 DESIGN.md 仍作为 legacy fallback 兼容。
常用命令：
spec-manager assist design-template
spec-manager brief "优化仪表盘视觉"
spec-manager assist design-export --format tokens-jsonL3 里可以把设计 lint 纳入验证：
@verify: design-lint(specs/DESIGN.md)
当前 Design Context 支持：
- 读取 DESIGN.md frontmatter 和 prose section。
- lint colors、typography、spacing、rounded、components 等 token。
- 输出
tokens-json、dtcg-json、tailwind-json、tailwind-css。 - 在 Agent Brief 中提示 prose-first、具体灵感参照、do/don't 约束。
- 用
design-diff对比两个 DESIGN.md 的结构变化。
它不会自动生成 UI、不会修改 Tailwind 配置，也不会替你判断审美质量；它的作用是把设计上下文稳定地交给 Agent。
有些任务只需要轻量流程，有些高风险任务需要更强证据。
spec-manager 支持 Profile：
standard：保持轻量，缺失证据以 warning 暴露。governed：关键 AC 必须有成功 verification evidence 才能完成 Task。
只读辅助命令：
spec-manager project profile recommend --request "新增 SSO 登录"
spec-manager project profile metrics
spec-manager project workflow preview
spec-manager project readiness critical这些命令不会偷偷修改配置，只帮助你理解风险和证据缺口。
| 命令 | 用途 |
|---|---|
spec-manager project init --name X |
初始化 .spec-manager/ |
spec-manager project agents --provider all |
写入 AI 工具入口 |
spec-manager project doctor |
检查配置和仓库完整性 |
spec-manager project docs check |
发布前检查 README、package files、Agent guidance 和生成资产边界 |
spec-manager next "需求" |
根据需求给出下一条安全命令 |
spec-manager brief "需求" |
生成 Agent Brief 和下一步 |
spec-manager dashboard |
查看项目/topic 摘要 |
spec-manager guide "需求" |
兼容旧入口：根据需求给出下一条命令 |
spec-manager new feature --topic T "标题" |
快速创建轻量 L1 |
spec-manager flow status --topic T |
查看规格链路进度和阻塞点 |
spec-manager spec list |
列出规格 |
spec-manager spec show <code> --include-content |
查看规格正文 |
spec-manager task list --topic T |
查看任务 |
spec-manager decision list --topic T |
查看决策 |
spec-manager view --topic T |
交互式浏览 |
任何命令都可以加 --help 查看细节。
适合：
- 正在用 AI Agent 维护真实项目的人。
- 想让 AI 改动可 review、可验收、可追踪的团队。
- 需要在多个 AI 编程工具之间共享项目记忆的人。
- 需要把 UI 设计上下文交给 Agent 的项目。
不适合：
- 一次性 demo。
- 完全不想保留规格和任务历史的临时代码。
- 只想让 AI 直接改一行 typo 的场景。此类小改可用
quick例外。
MIT