规格驱动开发：用AI编码助手实现工程化协作与边界控制

1. 项目概述当AI编码助手学会“看图纸”施工如果你和我一样长期在项目一线和各类AI编码助手Claude Code、Cursor、GitHub Copilot等打交道那你肯定经历过这种场景你给AI一个模糊的需求比如“加个用户管理后台”它吭哧吭哧给你生成了一堆代码。乍一看挺像那么回事但仔细一瞧文件结构混乱业务逻辑和展示层搅在一起新增的功能和现有系统边界不清最后还得你亲自上手花大量时间重构和“擦屁股”。问题出在哪不是AI不够聪明而是我们和AI之间缺少一份双方都能理解、且具有约束力的“工程图纸”——也就是一份清晰、结构化、驱动开发的规格说明书Spec。这就是cc-sdd要解决的核心痛点。它不是一个全新的AI工具而是一个工作流增强套件。你可以把它理解为给现有的AI编码助手目前支持8种装上了一套“工程管理”技能包。这套技能包的核心思想是“规格驱动开发”。简单说就是先把“要做什么”、“做成什么样”、“怎么分工”这些事用结构化的文档需求、设计、任务分解定义清楚形成一份“合约”。然后再让AI基于这份“合约”去自动执行编码任务并且每个任务都有独立的“质检员”审查子代理来检查是否按图施工有没有“越界”。我最初接触这个概念是通过 Kiro IDE它的“Spec-Driven Development”理念让我眼前一亮。cc-sdd可以看作是这套理念在多种主流AI编码环境下的一个开源、可移植的实现。它最大的价值在于将人类从重复性的代码生成监督中解放出来转而投入到更高价值的“合约”制定和关键决策上。我们批准设计AI负责在明确的边界内实现。这听起来像是把敏捷开发中的“定义完成标准”和“任务拆分”环节极度前置和自动化了。2. 核心理念与架构解析为什么“边界”比“指令”更重要在深入实操之前我们必须先理解cc-sdd背后的哲学这决定了你是否能用好它。传统上我们给AI下指令像是“去盖个房子”结果AI可能给你盖了个没有厕所的别墅。而cc-sdd倡导的方式是我们先和AI一起画好建筑设计图、结构图、水电图规定好每个房间的功能、面积和接口然后AI拿着这些图纸去调用不同的施工队子代理按工序任务一步步建造并且每完成一道工序都有监理审查代理来验收。2.1 从“主从命令”到“合约协作”的范式转变很多AI编码工具的使用模式是“主从式”的人类是发出模糊指令的主人AI是尽力猜测并执行的仆人。这种模式在小型、独立的脚本任务上有效但在涉及多个模块、需要与现有系统集成的复杂功能开发中极易失控。cc-sdd引入的“合约协作”模式其核心在于“规格说明书即合约”。这份合约不是在人类和AI之间而是在系统的不同部分之间。例如user-service模块的合约规定了它对外提供什么API需要什么数据frontend-component的合约规定了它接收什么props发出什么事件。AI无论是负责实现的还是负责审查的都成为这份合约的执行者和监督者。这样做的好处是显而易见的并行工作成为可能只要合约接口定义清晰前端和后端的AI可以同时开工人类也可以同时评审不同模块的设计而不用担心它们最后对不上。变更影响可控修改一个模块的内部实现只要不破坏合约就不会影响其他模块。AI在实现时也会被约束在边界内减少了“意外”修改全局状态的风险。知识沉淀与传承这些规格文档requirements.md,design.md本身就成了项目最准确、最及时的技术文档新成员或未来的维护AI都能快速理解系统脉络。2.2 v3.0 的核心革新技能化与长时运行cc-sdd在 v3.0 版本完成了一次重要的架构重塑重点围绕“Agent Skills”和“Long-running Autonomous Implementation”。1. 技能化之前的版本v1.x, v2.x更像是为每个AI平台定制了一套独立的命令集。v3.0 则抽象出了一套共通的17个技能。无论你用的是 Claude Code 还是 Cursor安装后获得的都是这同一套技能。技能是按需加载的这意味着AI工作区不会一开始就被大量不相关的指令淹没保持了界面的整洁。这17个技能覆盖了从需求发现、规格制定到任务实现和审查的全流程。2. 长时运行与自治实现这是最让我兴奋的一点。/kiro-impl命令启动后AI可以脱离你的持续监督自主地、一个任务接一个任务地执行下去。它的工作流程设计得非常工程化独立子代理每个任务都会启动一个全新的“实现者”子代理。这就像为每个小工序换了一个全新的施工队避免了上下任务间的状态污染和思维定势。测试驱动开发每个实现者都必须遵循RED → GREEN的TDD循环。即先写一个会失败Red的测试再去实现代码让测试通过Green。这强制产生了可验证的、高质量的代码。特性开关新代码在合并前通常处于特性开关Feature Flag之后这为灰度发布和回滚提供了便利。独立审查每个任务完成后会由另一个独立的“审查者”子代理进行评审。它不看实现过程只对照“合约”规格和任务描述检查产出。自动调试如果实现者卡住了或者审查者连续两次拒绝系统会启动一个“自动调试”通道。这个调试器会在一个干净的上下文中分析根本原因其发现会作为经验教训记录到后续任务的## Implementation Notes中实现跨任务的知识传递。这个流程确保了即使你离开电脑几个小时AI也在可靠地、有质量地推进工作并且每次中断后都可以安全地重跑。2.3 边界优先的设计纪律v3.0 特别强调了“Boundary-first”。在design.md中新增了“文件结构计划”它明确规定了每个模块对应的物理文件路径。任务卡tasks.md中的每一项会携带_Boundary:_本任务负责的边界和_Depends:_依赖的其他任务注解。审查的重点也随之变化不再仅仅是检查代码风格而是严格检查边界违规。比如一个负责user-service.js的任务如果试图修改auth-middleware.js里的逻辑审查会直接将其驳回。这强制实现了高内聚、低耦合是构建可维护系统的基石。3. 环境准备与技能安装为你的AI助手赋能理论讲完了我们动手把它装起来。cc-sdd的安装极其简单因为它本质上是一套模板、规则和技能定义的集合通过 npm 分发。3.1 基础安装一键获取核心技能打开你的终端进入你想要应用此工作流的项目目录cd /path/to/your/project然后执行安装命令。默认情况下它会为Claude Code安装技能包并使用英文文档。npx cc-sddlatest执行后你会看到类似下面的输出提示技能正在被安装到对应的AI助手配置中? Installing cc-sdd skills for Claude Code... ? Locating Claude Code configuration... ? Writing skill definitions to /Users/you/.config/claude-code/skills... ? Skills installed successfully. ? You can now use commands like /kiro-discovery in Claude Code. 注意使用npx意味着你每次运行的都是最新版本无需全局安装。这保证了你能始终获得最新的特性和修复。但这也要求你的项目目录是一个合法的Node.js项目有package.json或者至少网络通畅。3.2 多平台与多语言配置cc-sdd的强大之处在于其广泛的支持。如果你主要使用其他AI编码环境或者需要非英文的文档可以在安装时指定参数。选择不同的AI代理# 为 Codex 安装技能包 npx cc-sddlatest --codex-skills # 为 Cursor IDE 安装技能包 (Beta) npx cc-sddlatest --cursor-skills # 为 GitHub Copilot Chat 安装技能包 (Beta) npx cc-sddlatest --copilot-skills # 为 Windsurf IDE 安装技能包 (Beta) npx cc-sddlatest --windsurf-skills # 为 Gemini CLI 安装技能包 (Beta) npx cc-sddlatest --gemini-skills 实操心得“Beta”状态并不意味着功能缺失。所有平台的17个技能集是完全相同的。Beta 指的是该平台集成子代理的生成行为、用户体验、技能加载方式经过的真实场景测试不如 Claude Code 和 Codex 那么多可能会遇到一些边缘情况。在我的实践中Cursor 和 Copilot 的 Beta 版本已经非常稳定完全可以用于生产。如果遇到问题积极到项目仓库提交 Issue 是对社区最好的贡献。选择界面语言这对于非英语团队或个人来说非常友好。# 使用日文界面和文档 npx cc-sddlatest --lang ja # 使用繁体中文界面和文档 npx cc-sddlatest --lang zh-TW # 使用简体中文界面和文档 npx cc-sddlatest --lang zh语言包会影响到技能描述、生成的文档模板中的提示文字等让整个工作流更贴近你的母语环境。3.3 安装后的项目结构变化安装成功后你的项目根目录下会生成一个kiro/文件夹默认名称可通过--kiro-dir自定义。这是所有规格驱动开发产物的“工作区”。your-project/ ├── kiro/ │ ├── specs/ # 存放各个功能的规格文档 │ │ └── [spec-name]/ │ │ ├── brief.md # 由 discovery 生成的工作简报 │ │ ├── roadmap.md # 多规格项目路线图 │ │ ├── requirements.md │ │ ├── design.md │ │ └── tasks.md │ └── settings/ # 自定义模板和规则 │ ├── templates/ # 文档模板 │ └── rules/ # AI生成与评审规则 ├── src/ # 你的项目源代码 └── package.json这个结构非常清晰。specs/下每个子文件夹代表一个独立的功能或模块规格。settings/则允许你深度定制整个工作流我们会在高级定制章节详细讨论。4. 核心工作流实战从想法到可运行代码现在让我们用一个完整的例子走一遍cc-sdd的标准工作流。假设我们要为一个博客系统增加一个“文章访客统计”功能。4.1 阶段一探索与定义一切始于/kiro-discovery。不要一上来就想着写规格先用这个命令来探索你的想法。在你的AI编码助手的聊天框中输入/kiro-discovery 为博客系统增加文章访客统计功能需要记录PV和UV并能按天查看数据概览。这个命令会做以下几件事分析需求理解你想要的到底是什么记录PV/UV查看概览。评估现状检查当前项目代码库判断这个功能是与现有模块如article-service深度集成还是作为一个独立的新服务。生成简报在kiro/specs/article-stats/下创建brief.md概括探索结论和后续建议。路由决策它会给出明确的下一步命令建议。例如它可能判断这是一个中等复杂度的新功能建议你创建一份新的规格文档。brief.md示例片段# 探索简报文章访客统计 **结论**建议为此功能创建一份新的规格说明书。 **理由**功能边界清晰数据收集、存储、查询展示与现有文章模块耦合度低适合独立开发后集成。 **建议命令**/kiro-spec-init article-stats4.2 阶段二创建与细化规格根据发现阶段的建议我们开始创建规格。步骤1初始化规格/kiro-spec-init article-stats这个命令会在kiro/specs/article-stats/下创建规格文档的骨架。步骤2编写需求/kiro-spec-requirements article-statsAI会引导你或与你协作生成一份结构化的requirements.md。cc-sdd推荐使用EARS格式这是一种非常清晰的需求表达方式。requirements.md示例片段## 功能性需求 - **当** 用户访问一篇博客文章页面时**系统应** 增加该文章的PV计数**并且** 根据访客标识如IPUserAgent哈希判断是否为新UV若是则增加UV计数。 - **当** 内容管理员查看文章数据概览时**系统应** 提供过去7天、30天的PV/UV趋势图**并且** 可以按文章筛选。这份文档不是写给机器看的代码而是人类和AI共同理解的、无歧义的“合约”条款。步骤3进行设计/kiro-spec-design article-stats这是最关键的一步。AI会基于需求产出design.md包含架构图用Mermaid语法描述组件关系和数据流。文件结构计划明确每个模块对应的文件路径例如src/ ├── services/ │ ├── article-stats-service.js # 核心统计逻辑 │ └── article-stats-client.js # 前端调用客户端 ├── models/ │ └── article-stat.js # 数据模型 └── frontend/ └── components/ └── ArticleStatsChart.vue # 数据图表组件技术选型与理由例如为什么选择Redis HyperLogLog来估算UV以节省空间。步骤4分解任务/kiro-spec-tasks article-statsAI会将设计分解为具体的、可执行的开发任务并写入tasks.md。每个任务都标明了边界和依赖。tasks.md示例片段## 任务列表 1. **创建数据模型与数据库迁移** - _Boundary:_ src/models/article-stat.js, migrations/2024052001_create_article_stats.js - _Depends:_ None - 描述定义ArticleStat模型包含articleId, date, pvCount, uvEstimate字段。创建迁移文件。 2. **实现文章统计服务层** - _Boundary:_ src/services/article-stats-service.js - _Depends:_ Task 1 - 描述实现incrementPv, incrementUv, getStatsByArticleId等方法。至此一份完整的“工程图纸”就准备好了。人类需要做的就是评审并批准这些文档。一旦批准AI就可以拿着图纸去自动施工了。4.3 阶段三自治实现与审查这是cc-sddv3.0 的魔法所在。在批准了tasks.md后只需一个命令/kiro-impl article-stats然后你就可以在确保有足够的API额度或本地模型资源的情况下暂时走开了。/kiro-impl会读取tasks.md中的第一个任务。启动一个全新的实现者子代理在_Boundary:_规定的文件范围内以TDD方式实现该任务。任务代码提交后启动一个独立的审查者子代理检查代码是否符合规格、有无边界违规、代码质量是否达标。审查通过合并代码进入下一个任务循环。如果实现失败或审查被拒两次触发自动调试流程分析根因并记录到后续任务的“实施说明”中。 注意事项自治实现非常依赖AI代理的能力和上下文长度。对于Claude Code或Codex等强模型效果很好。对于能力稍弱的模型或极其复杂的任务你可能需要在关键节点如完成2-3个任务后进行人工检查点评审。/kiro-impl支持随时中断之后重新运行它会从上次失败或中断的任务继续非常安全。5. 高级技巧与定制化让工作流为你所用cc-sdd开箱即用已经很强大了但其真正的潜力在于它可以被深度定制以贴合不同团队的工作习惯和技术栈。5.1 定制模板统一团队产出物格式团队可能已经有自己的需求文档或设计文档格式。你可以直接修改kiro/settings/templates/下的模板文件。例如你的团队使用特定的API描述格式如OpenAPI。你可以修改design.md.j2Jinja2模板模板在“接口设计”部分强制要求AI以OpenAPI的YAML格式来描述API。这样所有通过cc-sdd生成的设计文档其API部分都能直接导入到Swagger UI等工具中。定制示例修改模板规则你可以在settings/rules/下的规则文件中加入这样的提示词# 在 api-design-rules.yaml 中 constraints: - 所有HTTP API描述必须使用OpenAPI 3.0.0 YAML格式包含完整的path、parameters、requestBody和responses部分。 - 数据模型定义必须使用JSON Schema格式。这样AI在生成设计时就会遵循这些约束。5.2 集成现有工具链连接JIRA与Gitcc-sdd生成的是Markdown文件这使其很容易与现有工具集成。与JIRA/Linear集成你可以编写一个简单的脚本在kiro-spec-tasks完成后解析tasks.md为每个任务在JIRA上创建一个子任务Sub-task并将JIRA任务号回写到tasks.md中。这样AI的实现进度就可以在项目管理工具上跟踪。与Git工作流集成/kiro-impl的每次任务提交都可以关联到特定的Git分支例如feat/article-stats-task-1。你可以在团队规则中约定所有AI生成的代码必须通过CI持续集成流水线运行单元测试和Lint检查才能合并到主分支。cc-sdd的边界检查与TDD实践让这种集成变得非常顺畅。5.3 处理大型倡议多规格并行对于“重构用户认证系统”或“开发移动端应用”这类大型倡议一个规格可能太庞大。这时可以使用/kiro-discovery的分解能力或者直接使用/kiro-spec-batch。/kiro-discovery 重构整个用户认证系统支持OAuth 2.0、多因素认证和会话管理。discovery可能会判断这需要拆分成多个规格auth-oauth2、auth-mfa、auth-session。它会生成一个roadmap.md来描述这些规格之间的关系。然后你可以使用/kiro-spec-batch roadmap.md这个命令会并行或按顺序为roadmap.md中列出的每个子项创建独立的规格目录并进行跨规格审查检查接口是否矛盾、职责是否重复。这极大地提升了复杂项目的规划效率。5.4 调试与问题排查实录即使流程再完善实践中也会遇到问题。以下是我遇到的一些典型场景及解决方法问题1/kiro-impl卡在某个任务上反复失败。排查首先查看该任务在tasks.md中的描述是否足够清晰边界是否明确。模糊的任务描述是失败的主因。解决手动编辑tasks.md拆分或澄清该任务。然后可以尝试手动运行/kiro-steering命令针对这个特定任务进行更细致的人工指导再重新运行impl。技巧关注## Implementation Notes部分。之前任务的调试信息会记录在这里可能包含了导致当前任务失败的线索比如某个依赖的全局变量名实际已变更。问题2生成的代码风格与项目现有风格不符。排查cc-sdd默认的代码生成规则可能不匹配你的项目ESLint或Prettier配置。解决在kiro/settings/rules/coding-style.yaml中详细定义你的代码风格规则。例如强制使用单引号、箭头函数、特定的命名约定等。更有效的方法是在项目的kiro/specs/[spec-name]/目录下放置一个.eslintrc.js或prettier.config.js的副本AI子代理在生成代码时会参考这些配置文件。问题3审查代理过于严格或宽松。排查审查的标准由settings/rules/review-criteria.yaml控制。解决调整该文件中的规则权重。例如你可以降低“代码复杂度”的权重提高“边界违规”的权重。你也可以添加自定义的审查规则比如“必须为新增的公共方法编写JSDoc注释”。问题4在Curson或Copilot等Beta平台技能加载失败或命令不响应。排查通常是这些IDE的插件系统或配置路径有差异。解决确保你安装时使用了正确的--xxx-skills标志。尝试重启你的IDE。检查IDE的设置中是否有关于“自定义指令”或“技能”的目录确认cc-sdd生成的文件是否被正确放置。查阅项目GitHub仓库的Issue页面看是否有同类问题及解决方案。6. 不同AI代理的适配与选择心得cc-sdd支持8种代理但它们的体验和稳定性确有差异。根据我的深度使用分享一下选型建议Claude Code Codex首选生产级稳定。这两个是cc-sdd设计和测试的首要对象。它们的推理能力强对长上下文、复杂指令的理解准确子代理的生成和行为最符合预期。如果你追求最稳定、最强大的体验且预算允许无脑选它们。Cursor IDE平衡之选体验优秀。Cursor 本身就是一个强大的AI驱动IDE其内置的“Composer”模式与cc-sdd的“子代理”概念契合度很高。虽然标记为Beta但在我数月的使用中其稳定性和效果已经非常接近Claude Code。特别是对于前端React/Vue项目Cursor 的代码理解和生成能力极强。GitHub Copilot Chat性价比与集成度之王。如果你已经在使用GitHub Copilot那么--copilot-skills是一个无缝升级的方案。它在VS Code和JetBrains全家桶中都能工作。Copilot Chat的响应速度很快对于大多数常见的业务逻辑实现任务完全够用。它的优势在于与编辑器深度集成代码补全和技能调用之间的切换非常流畅。Gemini CLI 其他Beta代理适合探索与特定场景。这些代理的集成成熟度还在提升中。如果你对某个模型有偏好比如更快的响应速度、更便宜的成本或者你的项目技术栈恰好是某个模型擅长的领域例如Gemini对Google Cloud服务生成代码的支持不错可以尝试。但要做好遇到更多小问题的心理准备并乐于向社区反馈。核心建议不要纠结于“哪个最好”。你可以为一个项目同时安装多个代理的技能。比如用 Claude Code 来做核心的架构设计和复杂逻辑分解discovery,design然后用 Cursor 或 Copilot 来执行具体的、边界清晰的实现任务impl。cc-sdd生成的规格文档requirements.md,design.md是平台中立的可以在不同代理间无缝传递上下文。最后我想说的是cc-sdd代表的不仅仅是一个工具更是一种与AI协作的工程思想的转变。它强迫我们这些开发者在写第一行代码之前先想清楚“是什么”和“为什么”。这个过程本身就是对软件设计能力的一次次锤炼。当你习惯了这种“先定合约再动工”的节奏后你会发现不仅AI的输出质量大幅提升你自己对系统的理解也更深了团队协作的摩擦也减少了。它可能不会让你写代码的速度快10倍但它能让你的代码在6个月后依然清晰可维护让新加入的同事或AI能快速接手这或许才是它带来的最大价值。