Specky：规范驱动开发平台，从AI氛围编程到确定性工程实践

1. Specky一个重新定义AI辅助开发的确定性工程平台如果你和我一样在过去几年里深度使用过GitHub Copilot、Claude Code这类AI编程助手你肯定经历过那种又爱又恨的矛盾感。爱的是它们确实能快速生成代码片段把我们从重复的样板代码中解放出来恨的是这种“即兴发挥”式的编码方式——业界戏称为“氛围编程”——常常导致项目陷入混乱。你让AI“给我做个登录系统”它确实生成了代码但可能完全忽略了密码重置的安全要求或者没考虑JWT令牌的刷新机制。结果就是团队40%的时间都花在了返工上因为需求从未被清晰地定义和验证。这就是我接触到Specky时感到眼前一亮的原因。它不是一个简单的代码生成工具而是一个完整的规范驱动开发平台。简单来说Specky在“你的想法”和“生成的代码”之间插入了一个由13个智能体、57个MCP工具和10个强制阶段组成的确定性引擎。它强迫你或者说引导你的AI助手先写清楚“要做什么”再动手写“怎么做”。这听起来像是回到了传统的软件工程流程但关键在于整个过程是由AI高效驱动的而非缓慢的人工流程。Specky的核心价值在于它将AI的创造力管道化了。你的AI助手不再是那个天马行空、有时会闯祸的“实习生”而是变成了一个严格遵循工程规范、拥有全套专业工具的“资深架构师”。无论你是从零开始一个全新项目还是在现有代码库上添加功能或是要现代化一个遗留系统Specky都提供了一套统一的、可审计的、确定性的工作流。接下来我将带你深入拆解这个工具集的每一个核心部分分享我从零开始用它构建一个微服务API的实战经验以及那些官方文档里不会写的“踩坑”心得。2. 核心架构与设计哲学为什么是“规范驱动”2.1 从“氛围编程”到“确定性开发”的范式转变在深入工具之前我们必须先理解Specky试图解决的根本问题。传统的AI编码助手本质上是“概率模型”它们根据上下文和提示词预测最可能的下一个代码令牌。这种模式在补全单行代码或小函数时很棒但在处理复杂系统时就会暴露其非确定性的弱点。同一个提示词在不同时间、不同上下文中可能产生结构迥异、甚至逻辑矛盾的代码。项目规模稍大这种随机性就会累积成巨大的技术债务。Specky引入的“规范驱动开发”哲学其核心是“先定义后实现”。这里的“规范”不是一份束之高阁的Word文档而是一系列活的、机器可读的Markdown文件它们被版本控制并与代码同步演进。SDD认为一份优秀的规范应该具备几个关键特性机器与人都可读使用Markdown既能被AI工具解析也能被工程师轻松阅读。结构化与可验证采用EARS符号等结构化方法书写使得需求可以被程序化地验证而非依赖模糊的人工判断。可追溯从需求到设计再到任务和代码每一步都有明确的映射关系。Specky的整个架构都是为服务这一哲学而构建的。它不是取代AI而是为AI装备了一套“工程纪律”。2.2 剖析Specky的四大核心构件Specky CLI安装的不仅仅是一个MCP服务器而是一个完整的开发体验套件。理解这四部分如何协同工作至关重要智能体这是与你对话的“角色”。specky-orchestrator是总指挥负责协调整个10阶段流水线。spec-engineer专注于撰写和验证规范design-architect负责系统设计task-planner进行任务分解。每个智能体都内置了特定的“技能”和“工具”调用权限。这避免了让一个“通用”AI去干所有事导致的质量不稳定问题。技能这是注入给智能体的“领域知识”。例如SDD Pipeline Rules技能让智能体深刻理解10个阶段的门禁规则EARS Patterns技能让它精通6种需求模式。技能文件是静态的、可审计的确保了智能体行为的一致性。MCP工具这是具体的“能力”。57个工具覆盖了从导入文档(sdd_import_document)、撰写规范(sdd_write_spec)、生成架构图(sdd_generate_diagram)到合规检查(sdd_compliance_check)的全流程。MCP协议使得这些工具可以被任何兼容的AI IDEVS Code, Cursor, Windsurf等调用。钩子这是流水线的“自动化检查点”。16个钩子在每个工具调用前后运行。例如artifact-validator钩子会检查生成的SPECIFICATION.md文件是否包含所有必需的EARS模式phase-gate钩子会阻止你试图从“设计”阶段跳回“发现”阶段。钩子确保了流程的强制性。一个生动的类比你可以把Specky想象成一个高度自动化的汽车工厂。MCP工具是各种机器人手臂焊接、喷漆、组装。智能体是经验丰富的车间主任他知道什么时候调用哪个机器人。技能是这些主任脑中牢记的标准化作业程序。钩子则是遍布生产线的传感器和质量检查站确保上一道工序合格前绝不进入下一道。而那个强制性的10阶段流水线就是不可逆的总装线。2.3 技术栈与生态兼容性Specky本身是一个TypeScript项目通过npm分发。它对宿主环境的要求非常宽松Node.js 20这是运行CLI和MCP服务器的基石。任何支持MCP的AI IDE官方对VS Code GitHub Copilot和Claude Code的支持最完善。但理论上任何实现了MCP客户端协议的编辑器都能连接上Specky的服务器。操作系统macOS、Linux、Windows包括WSL均可。一个容易被忽略但极其重要的特点是Specky默认工作在“空气隔离”模式。所有处理都在本地完成你的代码、规范、设计文档永远不会离开你的机器。这对于处理敏感或合规要求高的项目如医疗、金融是一个巨大的优势。它通过MCP协议与你的AI助手通信而AI助手调用云端大模型时传递的只是经过处理的、不包含核心IP的提示词。3. 实战演练从零构建一个任务管理API理论说得再多不如亲手做一遍。我将以构建一个简单的“任务管理API”为例带你完整走一遍Specky的10阶段流水线并穿插我遇到的实际问题和解决方案。3.1 阶段零环境准备与项目初始化首先全局安装Specky CLI。这里有一个关键细节官方推荐为项目指定IDE类型而不是使用默认的--ideauto。# 推荐全局安装CLI npm install -g specky-sddlatest # 进入你的项目目录可以是空目录 cd my-task-api # 初始化Specky项目并明确指定为Copilot如果你用VS Code specky install --idecopilot踩坑记录IDE冲突我最初尝试了--ideauto希望同时在VS Code和Claude Code中使用。结果发现两个IDE的MCP配置和钩子文件会相互干扰导致智能体行为错乱。官方文档在不起眼的地方提到了这一点但只有踩过坑才知道有多麻烦。强烈建议一个项目只绑定一个主IDE。如果团队中有人用Copilot有人用Claude可以考虑在.gitignore中忽略各自的MCP配置文件或者使用npx specky-sddlatest install进行临时安装。安装完成后运行specky doctor检查一切是否就绪。你会看到一个漂亮的终端输出列出所有已安装的组件和状态。3.2 阶段1-2初始化与探索——打好地基现在在你的AI IDE聊天框中召唤启动向导specky-onboarding智能体会检测到这是一个空目录Greenfield项目并引导你开始。我直接使用了更强大的总指挥specky-orchestrator 我需要构建一个任务管理API支持任务的CRUD、状态流转和基于用户的访问控制。请运行流水线。智能体首先调用sdd_init在.specs/目录下创建了001-task-management-api/文件夹并生成了CONSTITUTION.md。这个文件像是项目的“宪法”定义了核心原则比如“API优先”、“数据所有权明确”等。接着它自动进入发现阶段调用sdd_discover向我提出了那7个经典问题范围“v1版本要解决的核心问题是什么边界在哪里” 我的回答“v1提供一个内部团队使用的RESTful API管理个人任务。边界不包含团队协作、任务分配、复杂报表。”用户“主要用户是谁技能水平” 答“开发团队成员具备技术背景通过API或简单的前端调用。”约束“技术栈、框架、托管、预算、时间线” 答“Node.js ExpressPostgreSQLDocker部署无特定预算两周内完成MVP。”集成“需要与哪些外部系统/API集成” 答“初期无外部集成未来可能连接公司SSO。”性能“预期负载、并发用户、响应时间” 答“预计最多50个并发用户95%的API响应时间200ms。”安全“认证、授权、合规要求” 答“基于JWT的令牌认证RBAC基础模型用户只能操作自己的任务暂无强合规要求。”部署“CI/CD、监控、回滚策略” 答“使用GitHub Actions通过PM2或Docker Compose部署基础日志监控。”我的心得不要小看这7个问题。在传统敏捷开发中这些答案可能散落在不同的会议纪要或头脑风暴里。Specky强制你在一开始就系统性地思考并记录这些答案会直接成为后续所有工作的输入和约束条件。回答得越具体后面生成的规范和质量就越高。3.3 阶段3规范撰写——EARS符号的力量发现阶段完成后智能体自动进入规范阶段调用sdd_write_spec。这是Specky的精华所在。它生成的不是一段模糊的描述而是采用EARS符号编写的、结构化的SPECIFICATION.md。EARSEasy Approach to Requirements Syntax定义了6种需求模式强制要求清晰、无歧义。我的任务API规范部分内容如下## 功能性需求 **REQ-001 [通用型]**: 系统应提供一个RESTful API用于创建、读取、更新和删除任务资源。 * **验收准则**: * AC-001.1: POST /api/tasks 应接受JSON负载并创建新任务。 * AC-001.2: GET /api/tasks 应返回经过认证用户的任务列表。 * AC-001.3: GET /api/tasks/:id 应返回指定ID的任务如果任务不属于当前用户或不存在则返回404。 * AC-001.4: PUT /api/tasks/:id 应更新指定任务的全部字段。 * AC-001.5: DELETE /api/tasks/:id 应删除指定任务。 **REQ-002 [事件驱动型]**: 当用户创建一个新任务时系统应为其分配一个全局唯一的标识符UUID并在响应体中返回该标识符。 * **验收准则**: * AC-002.1: 创建的每个任务都必须有一个id字段值为UUID v4格式。 * AC-002.2: 创建成功的API响应必须包含该任务的完整JSON表示包括生成的id。 **REQ-003 [状态驱动型]**: 当任务处于“进行中”状态时系统应防止其被删除除非提供明确的“强制删除”确认参数。 * **验收准则**: * AC-003.1: 对状态为“进行中”的任务发起DELETE请求若未提供forcetrue查询参数应返回409冲突状态码及错误信息。 * AC-003.2: 若提供了forcetrue参数则允许删除并在审计日志中记录此强制操作。 **REQ-004 [非预期型]**: 如果API接收到格式错误的请求体如JSON解析失败那么系统应返回400状态码及描述性的错误信息。 * **验收准则**: * AC-004.1: 错误响应体应包含{“error”: “Invalid JSON”, “details”: “...”}格式。此时智能体暂停了。它会在聊天中提示“规范草案已生成请查看.specs/001-task-management-api/SPECIFICATION.md。如果确认无误请回复LGTM以进入设计阶段。”核心技巧善用LGTM门禁这个暂停点至关重要。不要盲目地输入LGTM。你应该仔细审查这份规范完整性是否覆盖了发现阶段讨论的所有功能点清晰度EARS模式使用是否正确“系统应...”的表述是否明确验收准则每个准则是否可测试、无歧义 我在这里花了15分钟调整了几个验收准则的表述并补充了一个关于分页的需求REQ-005。修改后我才输入LGTM。这个人工确认环节是确保AI工作方向正确的安全阀。3.4 阶段4-5澄清与设计——从需求到蓝图收到LGTM后智能体进入澄清阶段调用sdd_clarify。它会自动扫描规范寻找可能存在的模糊点。例如它可能会问“REQ-001中提到的‘任务资源’具体包含哪些字段请明确title,description,status的约束如长度、枚举值。” 你回答后它会更新SPECIFICATION.md并生成一个DECISION_TREE.md文件记录这些设计决策。接着进入设计阶段调用sdd_write_design生成DESIGN.md。这个文件内容非常丰富C4模型架构图使用Mermaid绘制了系统上下文、容器、组件图。数据模型定义了Task和User实体及其关系生成了ER图。API契约详细定义了每个端点的URL、方法、请求/响应模式JSON Schema格式、状态码。序列图绘制了“创建任务”和“更新任务状态”的关键交互流程。技术栈决策及理由解释了为什么选择Express而非Fastify选择PostgreSQL而非MongoDB等。我的心得设计文件是给后续开发无论是AI还是人的蓝图。Specky生成的设计不仅全面而且因为它基于之前的规范所以具有高度的一致性。例如API端点路径和字段名与规范中的验收准则完全对应。这从根本上避免了设计与需求脱节的老问题。同样设计阶段结束后需要再次LGTM确认。3.5 阶段6任务分解——将蓝图转化为工单设计确认后进入任务阶段调用sdd_write_tasks生成TASKS.md。这个文件将用户故事拆解成具体的、可执行的开发任务并标注了依赖关系。## 用户故事: 作为一个用户我可以创建新任务 **任务 T-001**: 实现 POST /api/tasks 端点处理程序 * **依赖**: 无 * **复杂度**: 中 * **验收准则映射**: AC-001.1, AC-002.1, AC-002.2 * **子任务**: * ST-001.1: 在 src/routes/tasks.js 中创建路由和处理函数骨架。 * ST-001.2: 实现请求验证中间件检查JSON格式和必填字段。 * ST-001.3: 集成数据访问层将任务持久化到数据库。 * ST-001.4: 生成UUID并包含在响应中。 * ST-001.5: 编写单元测试覆盖成功和失败场景。 **任务 T-002**: 实现 GET /api/tasks 端点处理程序 * **依赖**: T-001 (需要数据库模型) * **复杂度**: 低 * **验收准则映射**: AC-001.2这份任务清单可以直接导出到GitHub Issues、Jira或Azure Boards。更重要的是每个任务都明确关联到了SPECIFICATION.md中的具体验收准则AC-xxx。这建立了可追溯性。3.6 阶段7-10分析、实现、验证与发布后续阶段自动化程度更高分析调用sdd_run_analysis和sdd_compliance_check生成质量报告。它会检查规范、设计、任务三者之间的对齐度给出一个“一致性分数”。对于我的项目它提示“所有验收准则均在设计中有对应实现在任务中有对应开发项一致性分数100%”。实现此时你可以手动编码或者继续用AI助手基于清晰的任务描述来编写代码。因为规范足够清晰AI生成代码的准确率大幅提升。验证调用sdd_verify_tasks检查代码实现是否真正完成了任务清单上的所有项防止“幽灵完成”标记了完成但实际未做。发布调用sdd_create_pr可以自动生成Pull Request描述其中会嵌入规范的摘要和设计决策的链接极大提升代码审查效率。4. 高级用法与集成场景4.1 处理现有项目与遗留系统Specky并非只适用于绿地项目。对于棕地项目第一步永远是sdd_scan_codebase。这个工具会扫描你的代码库分析技术栈、目录结构并生成一份报告。当你后续初始化新功能时智能体会自动引用这份报告作为上下文。例如它会说“检测到项目使用TypeScript Next.js Prisma。新功能的认证模块应考虑与现有lib/auth.ts的模式集成。”对于现代化遗留系统你可以批量导入所有现有文档sdd_batch_import和会议记录sdd_batch_transcripts。Specky能从这些杂乱的信息中提取需求、约束和决策形成规范的输入帮助你构建现代化的“目标规范”并与当前代码进行差距分析。4.2 合规性框架集成这是我非常欣赏的一个企业级功能。通过sdd_compliance_check你可以针对特定合规框架如SOC2, HIPAA验证你的规范。例如运行“检查本规范是否符合SOC2信任服务原则”后它会生成一份报告控制域要求规范覆盖情况状态CC6.1逻辑访问安全REQ-004 (输入验证), REQ-005 (认证)✅ 已覆盖CC7.1系统变更管理设计文档中的部署流程部分⚠️ 部分覆盖CC8.1风险评估未发现明确的风险评估需求❌ 未覆盖这份报告能帮助你在设计阶段就识别合规缺口而不是在审计前夕手忙脚乱。4.3 与现有DevOps工具链的MCP集成Specky的威力不仅在于自身。通过MCP协议它可以与其他的MCP服务器协作形成一个工具网络生成Terraform代码后可以通过Terraform MCP服务器直接计划和应用。创建的任务清单可以通过GitHub MCP服务器直接创建为Issue。架构设计可以导出到Figma MCP服务器进行可视化评审。这意味着Specky可以成为你AI增强型DevOps流水线的智能调度中心。5. 常见问题、排查与性能调优在实际使用中你可能会遇到一些典型问题。以下是我的排查记录问题1智能体无响应或报错“工具调用失败”。排查首先运行specky doctor。90%的问题出在MCP配置上。检查你的IDE是否正确加载了Specky的MCP配置通常位于.vscode/mcp.json或Claude Code的配置目录。解决尝试重新安装specky uninstall --idecopilot然后specky install --idecopilot。确保没有多个MCP配置冲突。问题2生成的图表Mermaid在IDE中无法渲染。原因Specky生成的是Mermaid代码块需要IDE有对应的预览插件支持。解决在VS Code中安装“Markdown Preview Mermaid Support”这类插件。或者Specky生成的图表代码可以轻松复制到Mermaid Live Editor在线查看。问题3流水线卡在某个阶段无法手动推进。原因通常是前置条件未满足。例如试图从“设计”阶段直接跳到“实现”但“任务”阶段还未完成。排查检查当前特性目录下的.sdd-state.json文件查看currentPhase和phaseHistory。查看blockedReasons字段通常会有明确提示如“Missing TASKS.md artifact”。解决根据提示完成缺失的产出物或使用specky-orchestrator询问“我当前被卡住的原因是什么”问题4处理大型文档如百页PDF时速度慢或内存占用高。调优Specky的文档导入工具默认会尝试处理整个文档。对于超大文件建议先手动将其拆分为逻辑章节如“需求”、“架构”、“接口”然后使用sdd_batch_import分批次导入。也可以在项目配置.specky/config.yml中调整文本处理的块大小和重叠参数。问题5团队协作时规范目录.specs/如何管理最佳实践将.specs/目录纳入版本控制Git。每个特性目录是独立的可以并行开发。在Pull Request中除了代码变更也应包含规范文件的变更便于进行“规范审查”。Specky生成的CROSS_ANALYSIS.md可以用来检查不同特性之间的需求冲突。经过几个项目的深度使用我的体会是Specky带来的最大改变不是速度而是确定性和可复用性。初期建立规范似乎拖慢了节奏但一旦规范确立后续的开发、测试、甚至人员交接都变得异常顺畅。AI从一个“才华横溢但不可预测的搭档”变成了一个“严格遵循图纸施工的可靠工程师”。对于追求工程质量、面临合规要求或需要管理复杂项目的团队来说Specky提供了一套将AI能力“工业化”的宝贵范式。它可能不是所有项目的银弹但对于那些受够了“氛围编程”副作用的团队绝对值得投入时间学习和引入。