1. 项目概述当AI编码助手学会“看图纸”施工如果你和我一样长期在项目一线和各类AI编码助手打交道肯定经历过这种场景你给Claude或Cursor描述了一个功能需求它噼里啪啦生成了一堆代码乍一看挺像回事但仔细一读发现逻辑有漏洞、边界不清晰或者干脆把不同模块的职责混在了一起。你不得不打断它重新解释它再生成你再修正……几个来回下来那种“让AI自主干活”的畅想很快就被拉回“人工监工”的现实。问题的核心在于大多数AI编码工作流缺乏一个稳定、可重复的“契约”。我们人类工程师之间协作靠的是需求文档、设计稿、API约定这些“图纸”。AI与AI之间或者AI与人类之间如果没有类似的“图纸”作为共同遵循的规范就很容易各干各的产生混乱。cc-sdd这个工具正是为了解决这个问题而生。它不是一个全新的AI模型而是一套运行在现有AI编码助手如Claude Code、Cursor、GitHub Copilot等之上的“规范引擎”。简单来说cc-sdd引入了一套名为“Kiro”的规格说明书驱动开发流程。它把你的一个想法比如“做一个带上传、标签和分享功能的相册系统”通过一系列结构化的命令逐步转化为机器可读、AI可执行的“施工图纸”包括需求、设计、任务分解最后指挥AI编码助手们依据这份图纸进行长期、自治的代码实现。最妙的是它在每个任务环节都会启动一个独立的“审查员”AI来复核代码如果实现被阻塞或审查不通过还会自动启动“调试”流程分析根因并把经验教训传递下去。这套方法特别适合中大型功能开发、遗留系统重构或者任何你需要多个AI会话协作、且希望产出质量稳定可控的场景。无论你是独立开发者想提升AI助手的产出可靠性还是团队技术负责人希望建立AI辅助开发的标准化流程cc-sdd提供的这套“契约化”工作流都值得深入尝试。2. 核心理念与架构解析为什么是“规格驱动”在深入实操之前我们必须先理解cc-sdd背后的设计哲学。这决定了你能否用好它而不是仅仅把它当作另一条命令。2.1 从“指令跟随”到“契约协作”的范式转变传统我们使用AI编码模式是“人类下指令AI生成代码”。这本质上是主从模式。cc-sdd倡导的是契约协作模式。这里的“规格说明书”就是契约。它不是一个巨细靡遗的、命令AI去执行的“圣旨”而是一份明确了系统各部分边界和接口的合同。举个例子你要开发一个用户注册模块。在契约模式下规格书会明确边界注册模块负责从接收表单数据到用户记录落库的完整流程但不负责发送欢迎邮件那是邮件服务模块的事。接口注册模块暴露一个registerUser(email, password)函数返回一个包含userId和status的对象。邮件服务模块订阅“用户已创建”事件。有了这份契约人类可以专注于审核和批准契约内容“这样的设计合理吗”而AI实现者则可以在这个明确的边界内自由发挥采用TDD、选择具体库函数只要最终产出符合接口约定。另一个AI审查员也依据同样的契约来检查代码看是否有越界行为。边界不是束缚而是让内部实现可以安全、高效进行的保护罩。2.2 v3.0 的核心革新Agent Skills与长期自治cc-sdd在v3.0版本完成了一次重要架构升级核心是引入了“Agent Skills”模式。你可以把它理解为一套标准化的“技能插件”能够安装到不同的AI编码平台Agent上。统一的技能集无论底层是Claude Code还是Cursor安装后都获得完全相同的17个技能Skill。这些技能对应着SDLC的不同阶段如/kiro-discovery探索、/kiro-spec-design设计、/kiro-impl实现等。这保证了工作流的一致性。按需加载技能不是一股脑儿全塞给你的聊天界面而是“渐进式披露”。当你输入/kiro时才会看到相关的技能列表避免了界面混乱。长期运行的/kiro-impl这是自治实现的核心。它不是一个生成代码就结束的命令而是一个工作流引擎。对于任务列表tasks.md里的每个任务它会启动一个全新的“实现者”AI子代理subagent。该实现者在一个特性开关的保护下采用TDD红-绿流程编写代码。完成后启动另一个独立的“审查员”AI子代理进行代码审查。如果审查员两次拒绝或实现者被阻塞引擎会启动“自动调试”流程在一个干净的环境里分析根本原因。每个任务的经验教训会以“## Implementation Notes”的形式更新到tasks.md中指导后续任务。最重要的是这个过程是可中断、可恢复的。你可以随时停下改天再运行/kiro-impl它会从上次中断的任务继续。这种设计使得AI驱动的开发能够以“任务”为粒度持续、稳定地向前推进真正逼近“自治”的目标。2.3 关键文件与信息流理解cc-sdd生成的文件及其作用是掌握工作流的关键。它们构成了契约的实体。brief.mdroadmap.md由/kiro-discovery生成。brief.md是对当前工作范围的简要描述用于在中断后快速恢复上下文。如果探索发现需求需要分解成多个规格则会额外生成roadmap.md描述多个规格间的关系和范围。requirements.md使用EARS格式编写的需求规格。EARS是一种结构化需求语法强调“当…时系统应…”非常清晰利于AI理解和后续验证。design.md系统设计文档。包含架构图Mermaid格式、组件说明以及最关键的文件结构计划。这个计划直接决定了后续任务如何划分边界。tasks.md实现任务列表。每个任务都带有_Boundary:_本任务负责修改的文件范围和_Depends:_依赖的前置任务注解。这是/kiro-impl引擎的执行清单。{{KIRO_DIR}}/settings/这是自定义规则的宝库。你可以在这里修改模板和规则让生成的规格书更符合你团队的习惯比如改用PRD格式的需求或加入你公司的API设计规范。3. 从零到一的完整实操构建一个相册功能理论说得再多不如亲手跑一遍。我们以构建一个“带上传、标签和分享功能的相册”为例完整走一遍cc-sdd的标准化流程。假设你已经在项目根目录下。3.1 环境准备与技能安装首先你需要为你的AI编码助手安装cc-sdd技能。这里以最稳定的Claude Code为例如果你用Cursor或GitHub Copilot只需替换--claude-skills为对应的flag即可。# 在项目根目录下执行 npx cc-sddlatest --claude-skills这条命令会做几件事检查环境下载必要的技能模板和规则文件到本地项目的.kiro目录默认然后在你的Claude Code环境中注册一系列以/kiro-开头的命令。安装完成后你在Claude Code的聊天输入框里输入/应该能看到一系列kiro-开头的技能选项了。实操心得第一次安装时建议加上--dry-run参数先预览将要做的更改确认无误后再正式安装。另外如果你团队使用中文沟通可以在安装时指定语言npx cc-sddlatest --claude-skills --lang zh。这会让后续生成的文档和AI交互提示更符合中文语境。3.2 阶段一探索与规划 (/kiro-discovery)一切从探索开始。不要一上来就想着写规格先用/kiro-discovery让AI帮你理清思路。/kiro-discovery 构建一个相册功能支持用户上传图片、添加标签如#旅行#家庭并能够将相册或单张图片通过链接分享给其他用户。执行这个命令后AI此时扮演“探索者”角色会分析你的需求并输出一个决策。它可能会判断直接实现如果需求很小它可能建议直接写代码。创建单一规格对于这个相册功能它很可能建议走完整规格流程。分解为多个规格如果需求极其庞大比如“重构整个电商平台”它会建议分解并生成roadmap.md。对于我们的例子它大概率会输出类似这样的建议探索完成。建议为此“相册功能”创建一个新的规格说明书。 已创建 brief.md 以记录当前工作范围。 接下来请运行 /kiro-spec-init photo-albums 以初始化名为‘photo-albums’的规格说明书。同时项目里会多出一个brief.md文件里面用一两段话描述了“相册功能”的范围。这个文件的意义在于如果你一周后回来继续这个项目不用重新向AI解释一遍直接看brief.md就能恢复上下文。3.3 阶段二规格说明书编制接下来我们按照探索者的建议逐步编制规格说明书。这是一个层层递进的过程。3.3.1 初始化规格 (/kiro-spec-init)/kiro-spec-init photo-albums这个命令会创建一个以photo-albums为名的规格目录例如specs/photo-albums/并搭建好基本的文档结构框架。它相当于为这个项目建立了一个正式的“合同档案袋”。3.3.2 编写需求 (/kiro-spec-requirements)/kiro-spec-requirements photo-albumsAI会基于之前的探索生成一份requirements.md。你会看到类似EARS格式的需求当用户访问相册列表页时系统应显示用户拥有的所有相册的缩略图、标题和创建时间。 当用户点击“新建相册”按钮时系统应弹窗让用户输入相册标题和描述。 当用户在选择图片后点击“上传”按钮时系统应将图片文件上传至对象存储服务并在数据库中创建图片记录关联到当前相册。 ...每一条需求都附带清晰的验收标准。这个阶段你需要像产品经理一样仔细审核这些需求确保它们完整、准确、无歧义。如果有问题你可以直接修改这个requirements.md文件或者与AI对话进行修正。3.3.3 编写设计 (/kiro-spec-design)/kiro-spec-design photo-albums这是最关键的一步。AI会根据需求产出design.md。这份文档通常包含系统架构图用Mermaid语法描述前后端组件及其关系。数据模型定义主要的数据库表或数据结构如Album,Photo,Tag,ShareLink。API设计关键接口的路径、方法和请求/响应体。文件结构计划这是v3.0的重点。它会明确列出项目中将创建或修改的文件及其职责例如frontend/ components/AlbumList.vue components/PhotoUploader.vue pages/AlbumDetail.vue backend/ routes/albumRoutes.js controllers/albumController.js models/Photo.js services/imageStorageService.js这个计划直接定义了后续任务的边界。你需要重点审核这个计划确保技术选型合理、模块职责清晰。3.3.4 分解任务 (/kiro-spec-tasks)/kiro-spec-tasks photo-albums最后AI会将设计转化为可执行的tasks.md。每个任务都基于“文件结构计划”来划分例如1. [后端] 创建数据模型Album, Photo, Tag _Boundary:_ backend/models/* _Depends:_ None 实现Album, Photo, Tag的Mongoose Schema/Squelize模型。 2. [后端] 实现图片上传服务 _Boundary:_ backend/services/imageStorageService.js _Depends:_ Task 1 集成云存储SDK如AWS S3提供上传和删除接口。 3. [前端] 搭建相册列表页面 _Boundary:_ frontend/pages/AlbumList.vue, frontend/components/AlbumCard.vue _Depends:_ Task 1 调用后端API获取相册列表并展示。 ...每个任务都有明确的_Boundary_修改范围和_Depends_依赖关系。这保证了任务可以独立、且按正确顺序执行。至此一份完整的“施工图纸”就准备好了。3.4 阶段三自治实现 (/kiro-impl)最激动人心的部分来了。现在你可以让AI自己“照图施工”了。/kiro-impl photo-albums运行这个命令后cc-sdd引擎就会启动。它会读取tasks.md从第一个任务开始启动实现者引擎会为任务1创建一个全新的Claude Code会话子代理并将任务描述、相关规格需求、设计以及之前所有任务的“Implementation Notes”作为上下文提供给它。这个实现者会在一个特性开关例如一个环境变量或配置标志的保护下开始工作。TDD循环实现者通常会先写一个失败的测试RED然后编写实现代码让测试通过GREEN。所有代码修改都严格限制在_Boundary:_指定的文件范围内。独立审查任务代码提交后引擎会启动另一个全新的AI子代理作为“审查员”。审查员不知道实现者是谁它只根据规格说明书契约和代码标准来审查提交的代码。它会检查功能是否满足需求代码是否在边界内是否有明显的bug或坏味道自动调试如果审查员两次拒绝该实现或者实现者在过程中被阻塞例如遇到无法解决的错误引擎会触发“自动调试”模式。它会再次启动一个干净的AI会话分析错误日志、代码上下文试图找出根本原因并将诊断结果记录下来。经验传承无论任务成功还是失败其经验教训“在Model X中字段Y需要建立索引以提高查询效率”、“使用库Z时需要注意异步错误处理”都会被追加到tasks.md的“## Implementation Notes”部分。这样任务2的实现者就能学到任务1的经验。这个过程会一个任务接一个任务地自动进行下去。你可以放心地关掉终端第二天再运行/kiro-impl photo-albums它会自动从上次未完成的任务继续。这种“长期运行”的能力使得开发一个完整功能可以像运行一个CI/CD流水线一样自动推进。4. 高级用法与定制化指南掌握了基础流程后我们来看看如何把cc-sdd用得更加得心应手以及如何让它适应你团队的特殊需求。4.1 处理大型倡议多规格并行 (/kiro-spec-batch)当你有一个非常庞大的想法比如“为我们的SaaS平台增加AI助手功能”时/kiro-discovery可能会生成一个roadmap.md建议将其分解为多个规格例如specs/ai-chatbot/(AI聊天机器人)specs/knowledge-base/(知识库集成)specs/analytics-dashboard/(分析仪表盘)此时你可以使用/kiro-spec-batch命令基于roadmap.md并行创建和初始化所有这些规格目录。更重要的是在生成每个规格的设计时cc-sdd会进行跨规格审查检查不同规格之间是否存在矛盾、职责重复或接口不匹配的问题。这相当于在项目早期就进行了一次架构层面的协调避免了后期集成时的噩梦。4.2 扩展现有系统 (/kiro-steering)很多时候我们不是在绿地上开发而是在现有代码库上增加功能。cc-sdd为此提供了/kiro-steering命令。这个命令会先分析现有的代码库结构理解当前的模块划分和依赖关系。然后当你运行/kiro-discovery或/kiro-spec-init时AI会基于对现有系统的理解来提出设计方案确保新功能能够平滑集成而不是破坏现有边界。你还可以在生成设计后使用/kiro-validate-gap命令。这个命令会对比新生成的设计与现有系统的实现分析出需要修改的“差距”部分并将其作为专门的任务加入到tasks.md中比如“重构UserService以支持新的权限字段”。4.3 深度定制让规格书说你的“行话”cc-sdd的默认模板是通用的但真正的力量在于定制。所有模板和规则都在{{KIRO_DIR}}/settings/目录下默认是项目根目录下的.kiro/settings/。定制需求模板如果你公司使用标准的PRD格式你可以修改templates/requirements.md.j2这个Jinja2模板文件。你可以加入固定的章节比如“业务背景”、“用户画像”、“成功指标”等。定制设计规则在rules/design_rules.md中你可以定义团队的设计原则。例如“所有后端API响应必须遵循统一的{ code, data, message }格式”、“前端组件必须使用Composition API编写”。AI在生成设计时会遵循这些规则。集成外部工具你可以在任务模板中插入特定的指令。例如在templates/tasks.md.j2中你可以让每个生成的任务都自动包含一个指向JIRA票证的链接或者要求在提交代码前运行特定的lint检查脚本。避坑技巧定制时建议先复制一份默认模板进行修改而不是直接覆盖。另外修改模板后最好用一个简单的小项目测试一下生成效果确保你的定制没有破坏原有的逻辑。团队协作时可以将定制好的settings目录纳入版本控制作为团队资产共享。4.4 多AI平台混用与选型建议cc-sdd支持8种AI编码助手但稳定程度不同。我的经验是追求最稳定体验首选Claude Code。它的长上下文、代码理解能力和指令跟随性在目前是顶级的与cc-sdd的配合也最成熟。深度IDE集成如果你主要使用Cursor或Windsurf IDE那么选择对应的--cursor-skills或--windsurf-skills。技能会直接集成到IDE的命令面板中体验更无缝。考虑成本与速度GitHub Copilot和Codex也是不错的选择响应速度快。但要注意Copilot Chat的上下文长度可能有限对于非常复杂的规格生成和审查可能需要更精细的提示词拆分。实验性与未来Gemini CLI和Antigravity仍处于Beta阶段。如果你喜欢尝鲜可以试试但要做好遇到更多边缘情况的准备。一个高级用法是用Claude Code生成规格和设计因为它更擅长理解和规划然后用Cursor来执行/kiro-impl因为它与编辑器深度集成写代码和重构的体验更好。只要它们都安装了cc-sdd技能并且读取的是同一套规格文件这个工作流是可行的。5. 常见问题、排查与实战心法在实际使用中你肯定会遇到各种情况。下面是我踩过坑后总结的一些典型问题和解决思路。5.1 规格生成阶段的问题问题1AI生成的需求或设计太笼统缺乏可执行细节。原因初始的探索指令(/kiro-discovery)可能不够具体。解决在探索阶段就提供更多约束。例如不要只说“构建相册”而是说“构建一个基于Vue 3前端、Node.js后端、使用MongoDB和AWS S3存储的相册功能需要支持JWT鉴权”。越具体的上下文能引导AI产出越具体的设计。事后补救直接修改生成的requirements.md或design.md文件补充细节。cc-sdd的工作流是“AI起草人类审核修改”你拥有文件的完全控制权。问题2文件结构计划不合理导致任务边界模糊。原因AI对项目现有结构的理解可能不深。解决在运行/kiro-spec-design之前确保你的项目是打开的并且有清晰的目录结构。AI会参考现有结构。你也可以在运行设计命令后手动调整design.md中的“文件结构计划”部分然后再运行/kiro-spec-tasks来重新生成任务。5.2 自治实现阶段 (/kiro-impl) 的问题问题3/kiro-impl卡在某个任务反复失败。排查步骤检查tasks.md中的“Implementation Notes”前面失败的任务可能已经留下了线索。查看AI子代理的对话在Claude Code等界面你会看到为每个任务创建的独立会话。进去看看“实现者”遇到了什么错误“审查员”又因为什么原因拒绝。最常见的原因是依赖包未安装、环境变量未配置、或AI生成的代码存在语法错误。手动干预如果自动调试也无法解决你可以手动完成这个任务。修改代码确保测试通过然后手动在tasks.md中将该任务标记为完成例如在任务项前加上[x]并添加一条经验笔记。之后重新运行/kiro-impl它会跳过已完成的任务继续下一个。问题4AI生成的代码质量不高有“坏味道”。原因审查员的审查规则可能不够严格或者AI的代码生成能力本身有局限。解决强化审查规则定制settings/rules/review_rules.md文件加入更严格的代码规范例如“禁止使用var”、“函数长度不得超过50行”、“必须为公共API添加JSDoc注释”等。引入人工检查点不要完全放任AI从头跑到尾。在完成几个关键任务后例如完成所有数据模型构建后暂停/kiro-impl人工检查一下生成的代码进行一次代码评审。确认没问题后再继续。迭代改进把AI生成的、但你不满意的代码作为一个“学习案例”。在任务的经验笔记中明确指出问题所在例如“## Implementation Notes: 避免使用嵌套过深的回调应使用async/await”。这有助于AI在后续任务中改进。5.3 性能与成本考量问题5这个过程会不会很慢消耗大量AI Token实话实说是的与直接让AI写一段代码相比cc-sdd的完整流程探索、需求、设计、任务分解、自治实现消耗的Token要多得多因为它涉及多次AI调用和文档生成。权衡建议不要对所有改动都用cc-sdd。它的价值在于中大型、复杂度高、需要长期维护的功能。对于修一个bug、加一个简单的工具函数直接让AI写更快。把它看作是你项目中的“重型机械”在开挖地基、建造主体时使用而不是用来拧螺丝。优化技巧在/kiro-impl阶段你可以通过配置限制AI使用的模型。例如对于简单的CRUD任务可以让它使用更轻量、更便宜的模型如果平台支持。另外清晰的规格书本身就能减少后续实现阶段的反复和浪费。5.4 团队协作心法问题6如何在团队中推广和使用cc-sdd从小处试点不要一开始就在核心业务模块上使用。找一个边缘的、相对独立的新功能或工具项目进行试点让一两个感兴趣的工程师先跑通全流程。将规格书纳入代码评审将requirements.md和design.md像代码一样提交到Git仓库并作为Pull Request的一部分进行评审。这不仅能保证AI的设计符合团队标准也是一个极好的知识传递和架构讨论的机会。定制团队模板这是成功的关键。花时间根据团队的技术栈和规范定制一套settings模板。当所有人生成的规格书都遵循同一套格式和规则时协作效率会大大提升。明确角色cc-sdd不是取代工程师而是增强工程师。它最适合的角色是“高级工程师或技术负责人”用来将高层的产品想法快速转化为详细、可执行的技术方案和初始代码框架。初级工程师则可以更多地参与到后续的/kiro-impl执行和代码润色中。使用cc-sdd近半年我最大的体会是它强迫我和我的团队更前置地思考。以前可能边写代码边设计现在必须先把需求、设计、任务分解都想清楚、写成文。这个过程本身就能暴露出大量早期问题。而一旦有了这份清晰的“契约”AI就从一个需要时时盯防的“实习生”变成了一个可以委派具体任务、且产出相对可靠的“初级工程师”。项目的可预测性和代码的整体一致性得到了显著的改善。当然它不是一个银弹依然需要人类的监督和决策但它确实为AI辅助软件开发提供了一条通向更高成熟度的、切实可行的路径。