Spec Coding MCP

给 AI 编程工具使用的 spec / 执行清单 / 进度记录本地 MCP 工作流

先审查规格，再执行任务，最后把实现事实写回项目。

文档与网站 · 快速开始 · MCP 工具 · npm 包

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

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

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

目标

• 从没有 spec 的旧项目中反推 specs/ 目录，方便用户审查当前系统。
• 用户开发前先修改或新增 spec。
• 用户可以用执行清单拆分任务，模型按未勾选项顺序执行。
• 工具会在模型上下文中输出轻量 guidance 推荐，提醒模型按需读取工程、UI/UX、spec 写作和质量审查原则。
• 工具强制遵守 KISS、YAGNI、Clean Code、Clean Architecture、DDD、Fail Fast、SOLID、SoC 和 Boy Scout Rule。
• 工具还会防止混层、过度抽象和不必要的复杂度，把代码组织成适合大型项目、也适合人读的结构。
• 工具强制业务不确定性先确认：遇到金额、费率、结算、分账、退款、折扣、税费、状态机流转、并发、幂等、重试、回滚、规则来源不明或角色行为不一致时，必须先停下并向用户确认。
• 工具禁止靠常识猜业务规则；不清楚时要先说清哪里不清楚，再给出 2 到 3 种可能解释，等用户确认后再继续。
• UI/UX guidance 强调事实优先和语境优先：不编造指标、客户、性能数据、邮箱或商业定位；官网、工具、企业站、产品站、作品集、OSS 组织和文档站应使用不同信息架构。
• Codex 读取 active spec，按最新规格实现代码和测试。
• 验证通过后把 spec 归档到 done/。

目录结构

specs/
  README.md
  guidance/
    engineering.md
    ui-ux.md
    spec-writing.md
    git-commit.md
    pr-submit.md
    quality-review.md
  review/
    source-inventory.md
    index.md
    *.md
  active/
    *.md
  todo/
    *.md
  done/
    *.md

• review/：AI 源码审查任务，状态通常是 source-review/needs-ai-summary；静态线索只用于指导 AI 阅读源码，不代表业务事实。
• active/：准备实现或正在实现的 spec。
• todo/：轻量可执行清单，适合临时任务、拆分步骤或补充实现顺序。
• done/：已实现并验证通过的 spec。
• guidance/：可编辑的指导性提示词，供模型在忘记工程、UI/UX、spec 写作、Git 提交、PR 工作流或质量审查原则时按需读取。

MCP 工具

主路径工具

工具	作用
spec_bootstrap	首选项目入口：新项目生成 AGENTS、specs 和起步 active spec；旧项目生成 AGENTS、specs 和 AI 源码审查任务
spec_context	所有写操作前必须调用；返回 spec、TODO、工程约束、可选搜索线索和下一步推荐
spec_list	inspect 阶段查看 review、active、todo、done 状态，并推荐下一步先读取 spec_context
spec_guidance_list	列出内置且可编辑的指导性提示词名称、版本、分类、描述、触发词、适用对象和 specs/guidance/*.md 路径
spec_guidance_read	按名称读取一份指导性提示词；guidance 目录缺失、为空或缺少默认文件时会先写入内置默认 Markdown，再读取项目内容
spec_skills_search	通过官方 skills CLI 搜索 skills.sh，用于复杂任务前寻找专项 skill
spec_skills_install	使用随包 official skills CLI 安装 skill，必要时回退 npx skills add；默认安装 ui-ux-pro-max 到 Codex 全局 skills 目录

任务创建工具

工具	适用场景
spec_create	功能开发、问题修复或移除任务，需要行为约定、完成标准和实现计划
spec_todo	小而明确的临时任务，适合按执行清单顺序执行

结果记录工具

工具	适用场景
spec_checkpoint	阶段性完成后记录清单项、文件、验证、执行记录、风险和阻塞
spec_review_result	高级交接/审查记录，适合部分完成、存在未完成 TODO 或阻塞时使用
spec_done	仅在实现、TODO、验证和最终行为契约都完成后归档

高级维护工具

工具	适用场景
spec_init	只初始化或刷新 specs/ 目录和模板；普通项目接入优先用 spec_bootstrap
spec_generate_agents	只重新生成 AGENTS.md 和 CLAUDE.md；普通项目接入优先用 spec_bootstrap
spec_generate_from_source	只重新生成旧项目的 AI 源码审查任务；普通旧项目接入优先用 spec_bootstrap

推荐工作流

统一入口

1. 新项目先调用 spec_bootstrap，传 projectKind: "new"，生成 AGENTS.md、CLAUDE.md、specs/ 和起步 active spec。
2. 旧项目先调用 spec_bootstrap，传 projectKind: "existing"，生成 AGENTS.md、CLAUDE.md、specs/ 和 AI 源码审查任务。
3. 不确定时使用 projectKind: "auto"，工具会根据源码线索选择新项目或旧项目流程。
4. 之后再调用 spec_context，按 active spec 或 open TODO 开始开发。

旧系统第一次接入

1. 调用 spec_bootstrap，传 projectKind: "existing"。
2. AI 阅读 specs/review/source-inventory.md 和 specs/review/*.md 里的源码线索，并打开真实源码和测试。
3. AI 把阅读后的真实行为总结成业务规格；不允许只靠静态线索补业务结论。
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 里写 ## 执行清单。
5. 再次调用 spec_context，确认当前 spec、TODO 和工程约束。
6. Codex 按 spec 和未勾选 TODO 顺序实现代码和测试。
7. 阶段性完成后调用 spec_checkpoint 记录完成情况。
8. 验证通过后调用 spec_done。

流程选择规则

• 新项目初始化：spec_bootstrap。
• 旧项目接入：spec_bootstrap，然后 AI 补全 review spec。
• 临时小任务：spec_todo。
• 需要行为约定和完成标准的功能：spec_create 或已有 active spec。
• 阶段记录：spec_checkpoint 或 spec_review_result。
• 完成归档：只在实现、验证和最终行为契约都完成后调用 spec_done。

spec_context 默认使用 contextMode: "workflow"，只输出任务流程、spec/TODO、guidance 索引、轻量 guidance 推荐和必要执行护栏。工程、UI/UX、spec 写作、Git 提交、PR 提交、质量审查等原则详情不在 context 中展开；模型忘记原则或需要校准时，应先调用 spec_guidance_list 查看索引，再调用 spec_guidance_read 读取对应 name。需要源码线索时显式传入 contextMode: "hints"；需要完整源码扫描线索时再使用 contextMode: "full"。这些线索只是搜索入口，不是事实来源，模型修改前必须自行读取相关文件确认。

spec_list 和 spec_context 都会输出 Recommended Next Step，但语义不同：spec_list 属于 inspect 阶段，通常推荐下一步先读取 spec_context；spec_context 属于执行前上下文阶段，才推荐执行 TODO、补全 review、实现 active spec 或记录结果。即使当前没有 active、todo、review 或 selected spec，spec_context 也必须输出结构化下一步推荐，而不是只提示“不要开始实现”。空任务状态优先推荐 spec_bootstrap 建立项目入口，并把 spec_todo、spec_create 作为用户已给出明确任务时的备选。推荐会固定包含 nextTool、alternatives、arguments、reason、when 和 afterwards。nextTool 始终是单一工具 ID；arguments 只放可安全推导的上下文值或占位说明，不替模型编造 prompt、title 或行为记录。模型应优先执行 nextTool，只有用户明确要求或条件不满足时才考虑 alternatives。

spec_list 和 spec_context 的输出头部会显示当前 Spec Coding MCP 版本号。版本号来自 src/shared/meta.ts 读取的 package.json，用于判断当前运行中的 MCP 服务是否已经重启或更新到最新构建。

两者也会输出 Workflow State 摘要，展示 active、todo、review、done、selected spec 和 open TODO 数量。这个摘要只来自当前 specs 状态，帮助模型快速判断工作流位置，不替代源码阅读或业务判断。

spec_guidance_list 和 spec_guidance_read 是按需提醒工具。spec_init 和 spec_bootstrap 会生成默认的 specs/guidance/engineering.md、specs/guidance/ui-ux.md、specs/guidance/spec-writing.md、specs/guidance/git-commit.md、specs/guidance/pr-submit.md 和 specs/guidance/quality-review.md；用户可以直接编辑这些 Markdown。每份默认 guidance 顶部都有类似 SKILL.md 的 YAML 元信息，包含 name、version、title、description、category、triggers、appliesTo 和 updated，方便工具和模型按名称、版本、描述、适用场景检索。读取 guidance 时，如果目录缺失、目录为空或缺少某个默认文件，工具会先把缺失的内置默认 Markdown 写入项目，再读取项目内容；已有文件不会被覆盖。guidance 内容不塞进 spec_context，也不替代 selected specs、open TODO、用户要求或真实源码阅读。

spec_skills_search 和 spec_skills_install 用于接入外部 skills。搜索走 skills.sh，安装优先使用随包安装的 official skills CLI，找不到或执行失败时回退 npx skills add；安装默认使用全局 scope，并默认把 https://github.com/nextlevelbuilder/ui-ux-pro-max-skill 中的 ui-ux-pro-max 安装到 Codex 全局 skills 目录。UI/UX 任务默认优先使用这个 skill；ui-ux guidance 只负责路由到该 skill，不再维护本地设计原则或 checklist。需要先看命令而不改全局目录时，给安装工具传 dryRun: true。

YAML 元信息只用于需要被工具读取的文档，例如 AGENTS.md、CLAUDE.md、specs/README.md、specs/guidance/*.md 以及 review/active/todo/done specs。普通 README.md 和 VitePress docs/**/*.md 不默认加入这套 SKILL/spec 风格元信息；VitePress 页面只保留自身需要的 front matter。

写操作硬约束

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

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

执行清单驱动

执行清单可以放在 specs/todo/*.md，也可以写在 active spec 的 ## 执行清单 中：

## 执行清单

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

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

进度记录闭环

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

• 完成摘要
• 已完成并自动勾选的 TODO
• 本次变更文件
• 验证命令和结果
• 执行记录：功能全过程、全部已知分支条件、默认参数行为、模型采用的默认策略、边界处理结果
• 结构化 behaviorRecords：场景、条件、触发入口、输入与前置状态、执行步骤、输出结果、副作用、默认行为、边界处理、验证和关联文件
• 已知风险

spec_done 会把结构化行为记录渲染为 ## 最终行为契约。这部分是给用户审查的完整功能全景，必须交代所有已知正常、失败、边界、权限、状态、异常、空值和默认行为；即使是模型自己采用的默认策略，也要写明来源、触发条件和结果。如果没有提供 behaviorRecords，工具会在 next steps 中提示补充完整行为契约，并标记该 done 记录不可作为真实行为事实。

• 阻塞项

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

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

全局工程质量约束

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

AGENTS.md 和 CLAUDE.md 只保留短启动协议：提醒模型先调用 spec_context，按 selected specs/open TODO 执行，并在忘记原则时读取 guidance。完整工程、UI/UX、spec 写作、Git 提交和 PR 提交原则放在 specs/guidance/*.md，不塞进启动文件。

完整 guidance 默认内容包含：

• 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、执行清单、记录进度并归档 done。
• Git Commit Workflow：用户要求提交时如何验证、暂存相关文件、避免混入无关变更、选择提交信息语言并报告 hash。
• PR Submit Workflow：用户要求 PR 时如何发现模板、提交未提交工作、推送分支、生成或创建 PR，并在工具不可用时提供 compare URL。
• Quality Review Workflow：实现后如何自查代码质量、测试覆盖、架构边界、UI/交互状态、真实定位、首屏对象、Web 端口/截图验收和交付风险。

UI/UX guidance 不再内置设计原则、视觉约束、官网结构规则、AI 味 checklist、文案约束或首屏 checklist。模型遇到 UI/UX 任务时，应读取 ui-ux guidance，并使用指定的 ui-ux-pro-max skill 完成设计判断；本仓库只维护 skill 路由和安装说明。

提示词协议由 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 --help

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

初始化项目工作流时，也可以直接用 CLI 对齐 MCP 的 spec_bootstrap 主入口：

specc status --project-root .
specc status --project-root . --json
specc bootstrap --project-root . --project-kind auto
specc bootstrap --project-root . --project-kind new --initial-prompt "创建一个简单 CLI 项目"
specc bootstrap --project-root . --project-kind existing --project-name "用户系统"
specc bootstrap --help

specc status 只读输出当前版本、项目路径、specs 路径、Workflow State 计数、open TODO 数量和下一步建议，不启动 MCP server，也不会写入文件。需要给脚本或 CI 解析时使用 --json。

specc status --json 会输出顶层 schemaVersion，用于脚本、CI 和编辑器插件判断机器可读契约版本；当前 schemaVersion 为 1。JSON 仍保留兼容旧脚本的 nextStep 字符串，同时提供机器可读的 recommendation.nextTool、recommendation.alternatives、recommendation.arguments、recommendation.reason、recommendation.when 和 recommendation.afterwards。脚本和编辑器插件应优先读取 recommendation.nextTool 与 recommendation.arguments，避免解析人类可读文案。

--project-kind 支持 auto、new、existing，默认 auto。specc bootstrap 会生成 AGENTS.md、CLAUDE.md、specs/ 和第一批可执行入口；旧项目会生成 AI 源码审查任务，新项目会生成起步 active spec。

手动配置 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：细粒度单元测试，覆盖执行清单解析、进度记录写回、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 release:manual -- 0.2.6 --dry-run
npm run release:manual -- 0.2.6 --publish

--dry-run 只检查工作区、tag 和 npm 版本，不修改文件。--publish 会同步版本、运行验证、提交版本变更、创建 tag，并 push main 和 tag。

等价的手动命令如下：

npm version 0.2.6 --no-git-tag-version
npm install --package-lock-only --ignore-scripts
npm run verify
git add package.json package-lock.json
git commit -m "发布 0.2.6"
git tag v0.2.6
git push origin main
git push origin v0.2.6

vX.Y.Z tag 会触发 Publish npm 工作流完成 npm 发布。

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

如果某个 tag 已经由失败发布创建过、但 npm 没有发布成功，可以删除并重建同版本 tag 后重新 push。

发布前本地也可以运行：

npm run verify

Publish npm 工作流会在 tag/release 触发时校验 vX.Y.Z 与 package.json 版本一致，运行 npm run verify，然后执行 npm publish。手动触发 Publish npm 时，dry_run=false 才会真实发布。

设计边界

Spec Coding MCP 不做这些事：

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

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