规格驱动开发：用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（无论是负责实现的还是负责审查的）都成为这份合约的执行者和监督者。

这样做的好处是显而易见的：

1. 并行工作成为可能：只要合约（接口）定义清晰，前端和后端的AI可以同时开工，人类也可以同时评审不同模块的设计，而不用担心它们最后对不上。
2. 变更影响可控：修改一个模块的内部实现，只要不破坏合约，就不会影响其他模块。AI在实现时也会被约束在边界内，减少了“意外”修改全局状态的风险。
3. 知识沉淀与传承：这些规格文档（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-sdd@latest

执行后，你会看到类似下面的输出，提示技能正在被安装到对应的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-sdd@latest --codex-skills # 为 Cursor IDE 安装技能包 (Beta) npx cc-sdd@latest --cursor-skills # 为 GitHub Copilot Chat 安装技能包 (Beta) npx cc-sdd@latest --copilot-skills # 为 Windsurf IDE 安装技能包 (Beta) npx cc-sdd@latest --windsurf-skills # 为 Gemini CLI 安装技能包 (Beta) npx cc-sdd@latest --gemini-skills

> 实操心得：“Beta”状态并不意味着功能缺失。所有平台的17个技能集是完全相同的。Beta 指的是该平台集成（子代理的生成行为、用户体验、技能加载方式）经过的真实场景测试不如 Claude Code 和 Codex 那么多，可能会遇到一些边缘情况。在我的实践中，Cursor 和 Copilot 的 Beta 版本已经非常稳定，完全可以用于生产。如果遇到问题，积极到项目仓库提交 Issue 是对社区最好的贡献。

选择界面语言：这对于非英语团队或个人来说非常友好。

# 使用日文界面和文档 npx cc-sdd@latest --lang ja # 使用繁体中文界面和文档 npx cc-sdd@latest --lang zh-TW # 使用简体中文界面和文档 npx cc-sdd@latest --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，并能按天查看数据概览。

这个命令会做以下几件事：

1. 分析需求：理解你想要的到底是什么（记录PV/UV，查看概览）。
2. 评估现状：检查当前项目代码库，判断这个功能是与现有模块（如article-service）深度集成，还是作为一个独立的新服务。
3. 生成简报：在kiro/specs/article-stats/下创建brief.md，概括探索结论和后续建议。
4. 路由决策：它会给出明确的下一步命令建议。例如，它可能判断这是一个中等复杂度的新功能，建议你创建一份新的规格文档。

brief.md示例片段：

# 探索简报：文章访客统计 **结论**：建议为此功能创建一份新的规格说明书。 **理由**：功能边界清晰（数据收集、存储、查询展示），与现有文章模块耦合度低，适合独立开发后集成。 **建议命令**：`/kiro-spec-init article-stats`

4.2 阶段二：创建与细化规格

根据发现阶段的建议，我们开始创建规格。

步骤1：初始化规格

/kiro-spec-init article-stats

这个命令会在kiro/specs/article-stats/下创建规格文档的骨架。

步骤2：编写需求

/kiro-spec-requirements article-stats

AI会引导你或与你协作，生成一份结构化的requirements.md。cc-sdd推荐使用EARS格式，这是一种非常清晰的需求表达方式。

requirements.md示例片段：

## 功能性需求 - **当** 用户访问一篇博客文章页面时，**系统应** 增加该文章的PV计数，**并且** 根据访客标识（如IP+UserAgent哈希）判断是否为新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-stats

AI会将设计分解为具体的、可执行的开发任务，并写入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会：

1. 读取tasks.md中的第一个任务。
2. 启动一个全新的实现者子代理，在_Boundary:_规定的文件范围内，以TDD方式实现该任务。
3. 任务代码提交后，启动一个独立的审查者子代理，检查代码是否符合规格、有无边界违规、代码质量是否达标。
4. 审查通过，合并代码，进入下一个任务循环。
5. 如果实现失败或审查被拒两次，触发自动调试流程，分析根因并记录到后续任务的“实施说明”中。

> 注意事项：自治实现非常依赖AI代理的能力和上下文长度。对于Claude Code或Codex等强模型，效果很好。对于能力稍弱的模型或极其复杂的任务，你可能需要在关键节点（如完成2-3个任务后）进行人工检查点评审。/kiro-impl支持随时中断，之后重新运行它会从上次失败或中断的任务继续，非常安全。

5. 高级技巧与定制化：让工作流为你所用

cc-sdd开箱即用已经很强大了，但其真正的潜力在于它可以被深度定制，以贴合不同团队的工作习惯和技术栈。

5.1 定制模板：统一团队产出物格式

团队可能已经有自己的需求文档或设计文档格式。你可以直接修改kiro/settings/templates/下的模板文件。

例如，你的团队使用特定的API描述格式（如OpenAPI）。你可以修改design.md.j2（Jinja2模板）模板，在“接口设计”部分，强制要求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与Git

cc-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的插件系统或配置路径有差异。
• 解决：
  1. 确保你安装时使用了正确的--xxx-skills标志。
  2. 尝试重启你的IDE。
  3. 检查IDE的设置中，是否有关于“自定义指令”或“技能”的目录，确认cc-sdd生成的文件是否被正确放置。
  4. 查阅项目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）能快速接手，这或许才是它带来的最大价值。