Spec Coding MCP 是一个面向 spec coding 的本地 MCP 服务。

核心思路很简单：先写或审查一份小规格，再让 AI 按规格修改代码和测试。它不再尝试把整个系统永久文档化，也不维护复杂的 CRDT 状态。

目标

• 从没有 spec 的旧项目中反推 specs/ 目录，方便用户审查当前系统。
• 用户开发前先修改或新增 spec。
• 用户可以用 TODO 清单拆分任务，模型按未勾选项顺序执行。
• 工具会把全局工程质量约束注入模型上下文，强制约束代码风格、项目结构和 UI 直觉性。
• 工具强制遵守 KISS、YAGNI、Clean Code、Clean Architecture、DDD、Fail Fast、SOLID、SoC 和 Boy Scout Rule。
• 工具还会防止混层、过度抽象和不必要的复杂度，把代码组织成适合大型项目、也适合人读的结构。
• 工具强制业务不确定性先确认：遇到金额、费率、结算、分账、退款、折扣、税费、状态机流转、并发、幂等、重试、回滚、规则来源不明或角色行为不一致时，必须先停下并向用户确认。
• 工具禁止靠常识猜业务规则；不清楚时要先说清哪里不清楚，再给出 2 到 3 种可能解释，等用户确认后再继续。
• Codex 读取 active spec，按最新规格实现代码和测试。
• 验证通过后把 spec 归档到 done/。

目录结构

specs/
  README.md
  review/
    source-inventory.md
    index.md
    *.md
  active/
    *.md
  todo/
    *.md
  done/
    *.md
  templates/
    feature.md
    bugfix.md
    removal.md

• review/：从源码反推的当前代码事实，状态通常是 source-derived/current-code，用于用户审查。
• active/：准备实现或正在实现的 spec。
• todo/：轻量可执行 TODO 清单，适合临时任务、拆分步骤或补充实现顺序。
• done/：已实现并验证通过的 spec。
• templates/：新建 spec 的模板。

MCP 工具

| 工具 | 作用 | |---|---| | spec_generate_agents | 在项目根目录生成或更新 AGENTS.md | | spec_init | 初始化 specs/ 目录和模板 | | spec_generate_from_source | 从现有源码反推 review specs | | spec_create | 根据用户描述创建 active spec | | spec_todo | 根据用户描述创建可执行 TODO 清单 | | spec_list | 列出 review、active、todo、done specs | | spec_context | 返回 spec、TODO、工程约束和可选搜索线索；默认不替模型扫描源码 | | spec_checkpoint | 实现后记录完成 TODO、变更文件、验证结果、实际行为、风险和阻塞 | | spec_review_result | 结构化记录完成、阻塞、验证命令、关联文件和实际行为 | | spec_done | 验证通过后把 spec 移到 done，并保留最终实际行为记录 |

推荐工作流

先生成项目手册

1. 在任何代码或文档变更前，先调用 spec_context。
2. 调用 spec_generate_agents。
3. 检查项目根目录的 AGENTS.md。
4. 按 AGENTS.md、specs/ 和 TODO 开始开发。

旧系统第一次接入

1. 调用 spec_generate_from_source。
2. 用户阅读 specs/review/source-inventory.md 和 specs/review/*.md。
3. 用户把源码反推内容改成真实业务规格。
4. 需要开发时，将目标 spec 放到 specs/active/，或让 spec_context 读取指定文件。
5. Codex 按 spec 修改代码和测试。
6. 验证通过后调用 spec_done。

新需求开发

1. 在任何代码或文档变更前，先调用 spec_context。
2. 调用 spec_create，根据用户描述生成 active spec。
3. 用户审阅并修改 specs/active/*.md。
4. 如需拆任务，可调用 spec_todo 或在 spec 里写 ## TODO。
5. 再次调用 spec_context，确认当前 spec、TODO 和工程约束。
6. Codex 按 spec 和未勾选 TODO 顺序实现代码和测试。
7. 阶段性完成后调用 spec_checkpoint 记录完成情况。
8. 验证通过后调用 spec_done。

spec_context 默认使用 contextMode: "workflow"，只输出任务流程、spec/TODO 和约束。需要源码线索时显式传入 contextMode: "hints"；需要完整源码扫描线索时再使用 contextMode: "full"。这些线索只是搜索入口，不是事实来源，模型修改前必须自行读取相关文件确认。

写操作硬约束

spec_create、spec_todo、spec_generate_agents、spec_checkpoint、spec_review_result、spec_done 都要求当前会话先调用过 spec_context。

如果跳过 spec_context，这些写操作会直接失败，并明确提示先读取模型上下文。

TODO 驱动任务

TODO 可以放在 specs/todo/*.md，也可以写在 active spec 的 ## TODO 中：

## TODO

- [ ] 定位用户详情接口和测试。
- [ ] 增加禁用态字段。
- [ ] 更新验证命令并记录结果。

spec_context 会提取所有未勾选 TODO，要求模型按顺序执行；完成后应把对应任务改成 [x]，无法完成时保留未勾选并说明阻塞原因。

Checkpoint 闭环

spec_checkpoint 用于把实现后的事实写回 spec 或 TODO 文件：

• 完成摘要
• 已完成并自动勾选的 TODO
• 本次变更文件
• 验证命令和结果
• 实际行为记录：业务分支条件、默认参数行为、边界处理结果
• 结构化 behaviorRecords：场景、条件、结果、默认行为、边界处理、验证和关联文件
• 已知风险

spec_done 会把结构化行为记录渲染为 ## 最终行为契约。如果没有提供 behaviorRecords，工具会在 next steps 中提示补充分支条件、默认参数行为、边界处理和验证结果。

• 阻塞项

它适合复杂项目里的阶段性开发，让下一轮 AI 或人类能直接看到已经完成什么、验证过什么、还剩什么。

spec_review_result 则更偏“阶段结果汇报”，会记录完成和未完成 TODO、验证结果、变更文件、风险和阻塞，适合复杂项目交接。

全局工程质量约束

工程质量约束的单一可信来源在 src/templates/constraints.ts，Markdown 渲染统一由 src/templates/markdown.ts 完成。

spec_context、AGENTS.md、spec 模板和 TODO 模板都应通过这套模板模块输出同一组规则，避免 README、AGENTS 和上下文各自维护一份不一致的长清单。

当前提示词协议分为三层：

• Hard Rules：Fail Fast、风险确认、文件顶部注释、禁止混层、禁止无意义抽象、性能和资源底线。
• Recommended Practices：KISS、YAGNI、Clean Code、Human Readable、Clean Architecture、DDD、SOLID、SoC、测试优先、成熟库优先、局部小步重构、AI 可生成且人类可维护。
• Business Confirmation Rules：金额、费率、结算、分账、退款、折扣、税费、状态机、并发、幂等、重试、回滚、规则来源不明或角色行为不一致时，必须先向用户确认，不允许靠常识猜业务。
• Current Task Protocol：当前任务必须如何读取 spec_context、执行 TODO、记录 checkpoint 和归档 done。

提示词协议由 src/templates/constraints.ts、src/templates/prompt-protocol.ts 和 src/templates/markdown.ts 共同生成。

安装

npm install -g @dev_xiaoyun/spec-coding-mcp
specc init

specc init 会扫描本机的 Codex、Claude Code、OpenCode、Cursor、Continue 和 Windsurf，并让你选择注册 MCP。

手动配置 Codex 时推荐使用 Node 直连入口：

[mcp_servers.spec-coding]
command = "C:\\nvm4w\\nodejs\\node.exe"
args = ["C:\\nvm4w\\nodejs\\node_modules\\@dev_xiaoyun\\spec-coding-mcp\\dist\\index.js", "serve"]

路径需要按你的 Node 全局安装目录调整。

本地开发

npm install
npm test

测试入口：

• npm run build：TypeScript 构建。
• npm run unit：细粒度单元测试，覆盖 TODO 解析、checkpoint 写回、MCP guard 和注册兼容契约。
• npm run smoke：端到端 smoke 测试，覆盖 spec、AGENTS、CLI 和注册主流程。
• npm run release:check：发布前契约检查，覆盖版本、CLI/MCP 启动参数和关键文档说明。
• npm run verify：依次运行 build、unit、smoke、release:check。
• npm test：等同于 npm run verify。

启动 MCP server：

specc serve

或：

node dist/index.js serve

发布

发布前先运行：

npm run verify

npm 发布 workflow 使用 GitHub Actions secret NPM_TOKEN。发布前需要在仓库 secrets 中配置具备发布权限的 NPM_TOKEN。

发布 workflow 会在 tag/release 触发时校验 vX.Y.Z 与 package.json 版本一致，运行 npm run verify，然后执行 npm publish。

设计边界

Spec Coding MCP 不做这些事：

• 不试图把整个系统永久文档化。
• 不追踪每个功能点和代码位置的强一致状态。
• 不使用用户手写 ID 或 change log。
• 不把半成品开发状态伪装成已完成。

它只做一件事：让每次开发都有一份清楚、可审查、可实现、可归档的 spec。