sdd-mcp

Name: sdd-mcp
Author: juanklagos

本地服务

github.com/juanklagos开发工具218 周前更新

代码仓库

关于 sdd-mcp

sdd-mcp 是规范驱动开发（SDD）工作流的 MCP 服务，提供规范、计划、门禁、状态与工作日志等工具，支持中英西三语文档。它以脚本检查“批准规范前不写代码”的规则，适合希望让 AI 助手按流程推进项目的团队与个人。

主要功能

01规范、计划、任务文件的结构化生成
02门禁检查：规范批准、计划一致性与同意记录
03状态面板与工作日志记录会话
04可选的可视化构建器与只读仪表盘
05通过 npx 一键连接已安装的 AI 客户端
06升级命令支持先预览再应用

适用场景

01在已有项目中以 spec/ 目录引入 SDD 产物而不移动代码
02让 AI 助手在编写代码前完成规范与计划审批流程
03在 CI 中以 GitHub Action 校验门禁与策略文件

MCP 相关

sdd-mcp 作为 MCP 服务运行，向 Claude Code、Cursor、Codex、VS Code 等客户端暴露规范创建、门禁检查与工作日志等工具。connect 命令会将配置合并写入各客户端的配置文件。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "juanklagos-sdd": {
      "command": "npx",
      "args": [
        "-y",
        "@juanklagos/sdd-mcp"
      ],
      "env": {
        "SDD_PROJECT_ROOT": "<SDD_PROJECT_ROOT>",
        "SDD_WORKSPACES_ROOT": "<SDD_WORKSPACES_ROOT>"
      }
    }
  }
}

启动命令npx -y @juanklagos/sdd-mcp

需要配置的环境变量

SDD_PROJECT_ROOTPath to the SDD workspace (project with specs/ or a spec/ sidecar). Defaults to the current working directory.

SDD_WORKSPACES_ROOTWhere sdd_create_workspace creates ./www/<project-name>. Defaults to the current working directory.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@juanklagos/sdd-mcp2.8.0stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
profile	enum	否	minimal \| recommended \| full
assistant	string	否
useSpecKit	boolean	否
projectName	string	是

详细介绍

🌱 规范驱动开发模板

学习规范驱动开发，然后将其用于真实项目。
只有一条规则：在你批准书面规范之前，不写任何代码。每次运行时，脚本都会检查是否遵守这条规则，并准确列出检查内容。

🇺🇸 English · 🇪🇸 Español

非技术人员入门 · 快速开始 · AI Agent 入门 · 命令 · 社区

这是什么？

规范驱动开发（SDD） 是指在编写任何代码之前，先编写并批准一份清晰的规范。你的决策会记录在文件中，而不是埋没在某段聊天记录里——你关掉聊天后，就再也找不到了。到 2026 年，大多数人都通过这种方式使用 AI Agent 构建软件。

这个仓库有双重用途。

它是一所学校：一条从零开始的双语（EN/ES）学习路径，包含指南、互动课程，以及一位可以交谈的导师。你无需懂得编程，也能完成学习。

它也是一套可用于实际工作的工具包：用于检查规则的脚本、供 AI 助手读取的指令文件、一个让 AI 工具能够自行运行工作流的连接器（MCP，即模型上下文协议），以及一个可以添加到已有代码的项目中的 spec/ 文件夹——无需移动任何现有文件。

分步命令来自 GitHub Spec Kit。这个仓库在此基础上补充了指南、检查工具和模板。

流程演示——创建规范、验证并通过关卡 (每次发布时重新生成)：

实际变化是：决策不再留在聊天记录中，而是转移到 specs/。只有在 spec.md 和 plan.md 均已创建、内容一致，并且你记录了同意后，关卡才会打开——脚本会检查这些条件，而不是依赖某人的记忆。新队友或新 Agent 加入时，会看到熟悉的文件夹结构。此外，bitacora/ 会保存会话日志，这样六个月后，你仍然可以查明当初为什么那样做。

想了解行业概况？请阅读 2026 年的 SDD：现状及此模板的对比。

选择你的入口

非技术人员（创始人、产品经理、感兴趣的人）：START_HERE_NON_TECH.md — 循序渐进地入门，不含任何行话。
开发者：QUICKSTART.md — 用于搭建和验证的命令，大约需要 5 分钟。
AI Agent，或想把内容粘贴给 AI Agent 的人：AI_START_HERE.md — 操作规则，以及适用于各级别的复制粘贴提示词。

然后选择你的学习级别。文档站点上的每份指南都带有级别徽章：

🟢 初级：面向非程序员的快速指南
🟡 中级：团队规范指南
🔴 高级：治理与标准化

提示

如果你更愿意通过实践学习，可以参加**互动课程**（GitHub Skills 格式）：4 个步骤，约 35 分钟，由 Actions 自动评分。你的考试就是实际的 SDD 门禁。

30 秒快速开始

将此提示词复制粘贴到你的 AI 助手（Claude、Cursor、Copilot、Gemini……）中：

Using https://github.com/juanklagos/spec-driven-development-template, guide me step by step with SDD for my project.
My project is: [describe your project in plain language].
If my project is new, initialize from this template and GitHub Spec Kit as the base workflow.
If it already exists, adapt it without breaking current behavior.
No code before approved spec and consistent plan.

为 AI Agent 内置的命令

如果你使用 Claude Code，此仓库开箱即附带斜杠命令。从 /sdd:help 开始：

命令	功能
`/sdd:help`	告诉你当前所处的阶段，以及唯一的下一步
`/sdd:new`	循序渐进地开始：从想法到首份待审批的规范
`/sdd:spec`	使用 EARS 验收标准创建或完善规范包
`/sdd:gate`	运行门禁——审批、计划一致性、同意——并记录你的意见
`/sdd:decision`	记录一项决策，写入 `bitacora/decisiones/`：内容、原因、拒绝了什么，以及何时重新审视
`/sdd:close`	使用输出契约验证并关闭会话
`/sdd:tutor`	按级别进行对话式 SDD 课程，由实际验证脚本评分

作为插件安装到任何项目中（无需克隆）：

/plugin marketplace add juanklagos/spec-driven-development-template
/plugin install sdd@sdd-template

**VS Code / Copilot：**相同的工作流程以提示词文件形式提供，位于 .github/prompts/。
**任何 Agent（39 个工具）：**可移植的 Agent Skill，位于 skills/sdd-workflow/SKILL.md。
AI 上下文：llms.txt 为编码 Agent 汇总索引了所有文档（使用 ./scripts/generate-llms-txt.sh 重新生成）。

黄金法则

重要

必须先有已审批的 spec.md 和内容一致的 plan.md，然后才能编写代码。 脚本会强制执行此规则，并且只有在记录了你的同意后才能开始实施。

./scripts/check-sdd-policy.sh .   # multi-agent policy files are aligned
./scripts/check-sdd-gate.sh .     # spec approved + plan consistent + consent recorded
./scripts/confirm-user-consent.sh --spec 001-<slug> "User approved scope X"

（在 sidecar 项目中，相同的脚本位于 ./spec/scripts/ 下。）

也要在 CI 中强制执行。此仓库还可用作 GitHub Action，已列入 GitHub Marketplace：

- uses: juanklagos/[email protected]
  with:
    path: "."      # project root (sidecar or standalone auto-detected)
    strict: "true"

参考文件：sdd.policy.yaml · INSTRUCTIONS.md · AGENT_OPERATING_SYSTEM.md

工作原理

flowchart LR
  A["💡 Idea in plain language"] --> B["📋 spec.md approved"]
  B --> C["🗺️ plan.md consistent"]
  C --> D["✅ tasks.md prioritized"]
  D --> E["🚦 Gate + explicit consent"]
  E --> F["⚙️ Implementation"]
  F --> G["🔍 Validation + logbook"]

每个功能都有一个带编号的规范包，每个会话都会在 bitacora/（日志簿）中留下记录：

spec.md — 做什么以及为什么 (由你审批)
plan.md — 如何实现 (与规范一致)
tasks.md — 具体步骤
history.md — 演进过程

完整的演练示例：examples/002-mcp-end-to-end

应用到实际项目

最快的开始方式（无需克隆）：

npx @juanklagos/create-sdd-project@latest my-app

它会询问几个问题，并使用最新模板搭建推荐的 spec/ sidecar，或完整的工作区。

使用此模板的三种方式，从最轻量到最全面：

模式	适用场景	命令
紧凑型 `spec/` 旁置目录 ⭐	真实或现有项目：SDD 工件位于 `./spec/`，代码保留在项目根目录	`./scripts/install-spec-sidecar.sh /path/to/project --profile=recommended`
内部工作区 `www/`	可运行的项目应位于此模板仓库中	`./scripts/create-www-project.sh my-project codex`
完整独立副本	你明确希望将整个框架用作工作区	`./scripts/init-project.sh /path/to/project --profile=full`

提示

专业场景下的默认选择是紧凑型 spec/ 旁置目录，不包含其他内容。除非你确实需要独立模式，否则切勿将完整框架复制到真实代码库中。

日常命令（此处展示旁置目录模式；独立模式下，根目录中也有相同的脚本）

操作	命令
新建规范	`./spec/scripts/new-spec.sh "my-feature" "Owner"`
验证结构	`./spec/scripts/validate-sdd.sh . --strict`
策略检查	`./spec/scripts/check-sdd-policy.sh .`
SDD 门禁检查	`./spec/scripts/check-sdd-gate.sh .`
状态仪表板	`./spec/scripts/generate-status.sh`

文件夹结构与布局详情：项目组织结构图

flowchart TD
  A["Your project root (code)"] --> B["spec/"]
  B --> C["idea/"]
  B --> D["specs/ (numbered bundles)"]
  B --> E["bitacora/ (logbook)"]
  B --> F["scripts/ (gate + validation)"]

通过 MCP 连接（可选，高级功能）

如果你的 AI 工具支持 MCP（模型上下文协议），它就可以自行运行此工作流：创建规范、检查门禁、编写日志簿。在项目文件夹中运行一条命令即可完成设置：

npx @juanklagos/sdd-mcp@latest connect

它会查找你已安装的客户端——Claude Code、Codex、Cursor、VS Code、Windsurf、Gemini CLI、opencode——并将配置写入各自的配置文件。它会与现有配置合并，绝不会覆盖已有内容。先添加 --dry-run，即可查看它将修改哪些内容。然后重启客户端。

更喜欢手动操作？ 将客户端指向 npm：{"command": "npx", "args": ["-y", "@juanklagos/sdd-mcp@latest"]}。@latest 很重要——不加它，npx 可能会提供缓存的旧版本，其中可用工具更少。
正在开发此模板？ 运行 npm install && npm run build && npm run mcp:start，即可从源代码启动服务。
SDD Builder（可视化拖放工具）： 先运行 npm run builder:build 构建一次，然后运行 SDD_PROJECT_ROOT=/path/to/your/project npm run mcp:http:start，并打开 http://127.0.0.1:3334/builder——将规格组合为相互连接的卡片，每张卡片都对应磁盘上的一个真实 specs/NNN/ 文件包。在此模板仓库中，Builder 按设计无法使用（模板根目录中不能进行目标项目操作），因此请务必将 SDD_PROJECT_ROOT 指向真实工作区。请参阅可视化指南。
已经在使用 SDD，想升级到最新版本？ 运行 npx @juanklagos/sdd-mcp@latest upgrade --project-root . --dry-run，即可在实际更改前查看将会有哪些变化：框架文件会得到修复，除非使用 --apply，否则绝不会写入你的文件。请参阅升级指南。
SDD Desk（同一款 Builder 的桌面应用）： 下载，适用于 macOS、Windows 或 Linux。无需安装其他内容：应用已包含所需的一切。应用运行时，你的 AI 助手可以连接它——复制应用显示的地址，并粘贴到助手的设置中。需要注意的是，该应用未经数字签名，因此首次打开时，macOS 或 Windows 会显示看起来很吓人的警告，并询问你是否允许打开。如果你不想处理这些警告，可以改为运行 npx @juanklagos/sdd-mcp@latest --http。这是同一款工具，可在浏览器中使用，也不会出现警告。
可视化仪表板： 将服务指向一个项目——运行 SDD_PROJECT_ROOT=./www/my-project npm run mcp:http:start——然后打开 http://127.0.0.1:3334/dashboard，查看一个只能浏览、不能编辑的页面：门禁是否开放、一些关键数字、每个规格的进度，以及哪些规格正在等待其他规格。在你的语言中显示，无需编译。此文件夹（模板本身）不是一个项目，所以如果你在这里运行，它会告知你这一点。
最简单的入门说明：Easy MCP Guide
客户端配置： .mcp.json（Claude Code）· Cursor · Codex
完整参考：docs/en/41-complete-mcp-reference.md

注意：GitMCP（免费、远程）可帮助 AI 读取这个公开仓库；本地的 sdd-mcp 则运行真正的引导式工作流。二者相辅相成：GitMCP 指南。

文档

在线浏览：文档网站提供所有指南，支持搜索、EN/ES 语言切换和级别徽章。

如果只看三篇：

工作流——逐步了解 SDD 流程
结构——了解每个文件夹的用途
2026 年的 SDD：行业前沿——了解行业概况，以及此模板在其中的位置

其他所有内容：完整文档索引按主题整理了全部 53 篇指南（EN/ES）。

社区

文档网站：juanklagos.github.io/spec-driven-development-template
提问、分享想法和展示成果：GitHub Discussions
报告错误和提出具体建议：Issues
互动课程：aprende-sdd — 边做边学，由 Actions 自动评分
完成一个导师级别了吗？/sdd:tutor 会将其记录在你的日志簿中，并为你的 README 提供一枚完成徽章

法律与作者信息

许可证：MIT — 可在任何地方使用，包括商业用途和公司内部使用，无需付费或征求许可。请保留版权声明。法律指南
使用这些模板编写的内容归你所有：TEMPLATE-OUTPUT.md
发布版本 / Publicar una versión：RELEASING.md
更新日志：CHANGELOG.md · 最新版本：v2.8.0

如果它帮你避免了一次糟糕的冲刺，点个 ⭐ 就能帮助更多人找到它。

🌱 未经批准的规范和一致的计划，不写代码。

⬆️ 返回顶部

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。