Claude AI 的终端编码工具 Claude Code 出现后很多团队开始尝试让 AI 直接改代码但一个典型感受是让 AI 自由发挥并不能稳定交付。真正常见的问题不是模型不会写而是需求边界不清晰、任务流程不固定、验收标准模糊AI 一旦自行决定改动范围就会把项目改出大量回归。为了把“手动打开文件、逐段编辑、反复跑测试”收敛成“一次触发 AI 完成任务”我围绕 Claude Code 构建了一套以 OpenSpec 管需求、以 Superpowers 管流程的工程实践。这篇内容会从安装、配置、写需求规格、定义技能脚本到跑通完整例子和排错逐一展开。1. 先理解“一键交付”为什么成立Claude Code、OpenSpec 与 Superpowers 的分工先回答一个本质问题为什么单独使用 Claude Code 还不够Claude Code 是 Claude AI 在终端里的代理式开发工具。它不像普通聊天框只给你粘贴建议而是能读取当前项目的文件结构、执行命令、运行测试、修改代码。你用自然语言下达任务它可以完成从定位文件到修改文件再到验证结果的一整条链路。这听起来很自由但在实际工程中自由恰恰是最需要约束的地方。如果请求是“帮我加一个标签筛选功能”Claude Code 会自行推断数据模型怎么设计、接口路径叫什么、UI 交互什么样甚至会顺手“优化”掉它觉得不合理的代码。对于简单 Demo 这也许无所谓对于真实项目却是灾难。所以我理解的一键交付并不是“命令一下AI 接管一切”而是“命令一下AI 在约束范围内执行一个固定流程”。这个约束由三部分提供Claude Code负责执行是能读写工作区的 AI 代理。OpenSpec负责定义需求规格把模糊需求变成可验收的变更描述。Superpowers负责固化流程把高频任务变成可重复的技能避免每次用一大段提示词碰运气。这三个组件的核心关系可以这样理解OpenSpec 回答“要改什么”Superpowers 回答“怎么稳定地改”Claude Code 回答“谁能把改动真实落地”。三者形成一条需求到代码再到验证的流水线。在看后面的例子之前先看一张分工速查表组件解决的核心问题主要产物使用时机Claude Code代理式读写文件和执行命令被修改的代码、测试结果、命令输出所有实际改动发生层OpenSpec需求不清晰、验收标准缺失规格文档、变更提案、验收清单动手改代码之前Superpowers提示词和操作流程不固定技能定义、命令脚本、模板文件重复执行复杂任务时这段分工是后面所有步骤的基准。后续会依次说明如何配置这三层再把它接成一条完整命令。1.1 Claude Code把对话变成可执行的编辑能力Claude Code 是运行在终端里的 AI 代理。与网页对话框的区别在于它可以访问当前项目的真实文件系统。给它一个任务它会先查看相关目录、读取文件内容、尝试理解上下文然后直接修改文件并运行命令来验证。本地开发时最常见的运行方式是进入项目根目录后执行claude这会进入交互模式。你可以像聊天一样给它下达指令。它执行完一条指令后会把命令输出、文件改动结果展示出来等待下一步指示。对于需要多次试探和确认的调研型任务这种模式更合适。另一种方式是非交互模式claude -p 请检查 src 目录下测试失败的代码并修复-p表示直接传入 prompt 执行不需要进入持续对话。执行完毕后进程退出输出结果可以通过脚本捕获。这种模式适合自动化流程也是后面封装一键脚本的基础。两种模式对使用者的要求不同。交互模式允许你随时打断和纠正但每次启动都要重新描述任务。非交互模式指令一旦发出AI 会按自己的判断走完整条链路因此指令的约束力就显得更重要。很多人觉得 Claude Code 不稳定往往不是模型问题而是直接用非交互模式下达了过于模糊的指令。1.2 OpenSpec让 AI 有可遵循的需求契约OpenSpec 解决的是需求输入的质量问题。如果把 Claude Code 比作一名经验丰富的工程师它最需要的是清晰的需求文档。OpenSpec 的核心理念是把一次变更描述成一份可阅读、可评审、可验收的规格文件AI 在修改代码之前先读取这份文件。常见的变更提案会包含背景、需求、技术方案和验收标准。虽然不同实现里字段名称会有差异但核心原则一致先落文档再改代码。这样 AI 就不会基于一句模糊的话去脑补整个功能而是基于一份写清楚边界和完成条件的规格去实现。1.3 Superpowers把高频动作固化为技能Superpowers 解决的是流程不固定的问题。假设你已经梳理出一套标准实现流程读规格、检查分支、按方案实现、跑测试、输出 diff 摘要。如果每次靠手工把这段提示词复制给 Claude Code既容易遗漏也容易因人而异。Superpowers 这类的技能机制就是把流程写进一个可被 AI 读取的定义文件通过命令或技能名触发。工具之间的配合可以这样概括OpenSpec 先定义要做什么Superpowers 定义按什么顺序做Claude Code 实际执行改动。三者缺一环AI 编码都会退化成“碰运气”。2. 环境准备安装 Claude Code规划项目入口和权限边界这一部分的目标是得到一个能安全运行的 Claude Code 工作区。你需要关心三件事工具本身能不能跑、项目规则是否被 AI 读取、有哪些权限需要提前限制。2.1 安装 Claude Code 与前置条件Claude Code 是运行在终端里的 Node.js 程序。在多数系统里你只需要准备一个正常的 Node.js 环境然后通过包管理器安装。下面是一组常见命令node --version npm --version npm install -g anthropic-ai/claude-code claude --version安装完成后第一次在某个项目目录里启动claude时会要求完成登录认证。认证信息会保存在本机后续启动会复用。要注意的是不同版本的认证方式和账号权限要求不完全一样所以落地时应该先看当前 CLI 的使用说明不要假设所有版本都一样。在仓库根目录运行claude会进入交互模式。交互模式适合探索、诊断、逐步确认但在自动化和一键交付场景里更常用的是非交互模式claude -p 请检查当前目录里 src 下所有测试失败的用例-p表示直接传入指令执行执行完输出结果并退出。这个模式是后面封装一键命令的基础。2.2 项目入口文件用 CLAUDE.md 告诉 AI 规则Claude Code 在启动后会读取项目目录下的规则文件常见命名为CLAUDE.md。它相当于给 AI 的“项目手册”。把构建命令、测试命令、目录说明、编码约束写清楚AI 就不会每次凭猜测决定怎么跑项目。下面的例子是一个简单全栈项目的手册# CLAUDE.md ## 项目 React Express 的全栈待办应用。 ## 常用命令 - npm run dev 同时启动前后端 - npm test 执行单元测试 - npm run lint 执行 ESLint ## 目录 - src/server后端代码 - src/client前端代码 - specs需求规格目录 ## 约束 - 只修改与当前任务相关的文件 - 每次改动后必须运行 npm test - 数据库 schema 变更必须写迁移脚本 - 不允许读取 .env 文件 - 没有规格文档时不要直接实现大功能这个文件的价值是给 AI 划定行动边界。如果没有这些约束AI 很容易在修复一个接口问题时顺手把另一个组件的变量名也改了这种破坏会在 review 阶段才暴露出来。2.3 学习环境与生产环境的差异同样是“用 Claude Code 改代码”本地学习和团队协作的配置梯度完全不同。常见差异可以整理成一张表维度本地学习环境团队协作/生产环境分支策略允许直接在当前分支改必须从 feature 分支开始主分支禁止 AI 直接提交命令权限可以允许执行任意测试命令限制为 test、lint、git 等白名单命令读取范围可以读完整个项目通过忽略规则排除生成目录、日志、密钥模型选择使用默认模型降低使用成本根据任务复杂度固定模型版本验收方式自己看结果人工 review CI 测试门禁这种差异不是技术限制而是风险控制策略。越接近生产环境越应该把 AI 当成一个需要监督的新成员而不是权限全开的自动机器人。3. 用 OpenSpec 把需求转成 AI 可执行的规格很多人以为 AI 写代码最怕的是代码能力不够实际最怕的是需求描述含糊。OpenSpec 这种规格驱动的方式解决的就是需求到任务的翻译问题。3.1 认识规格文件的基本结构OpenSpec 在不同项目里有不同实现但核心结构高度一致一个变更提案应包含背景、需求、技术方案、验收标准。你可以把它理解为给 AI 看的需求文档加技术设计文档。下面是一个变更提案的目录示例specs/ proposals/ 20250301-add-tags/ change.md这里的change.md是核心产物。下面是一个最小模板实际使用时要根据团队习惯调整字段# Change: 为待办事项增加标签筛选 ## Why背景 用户希望按照标签查看待办事项当前列表不支持筛选。 ## What需求 - 数据模型增加 tags 字段类型为字符串数组 - 列表接口支持 tags 参数过滤 - 前端增加标签筛选器 ## How技术方案 - 后端为 Todo 增加 tags 列提供迁移脚本 - 接口GET /api/todos 增加可选 tags 参数 - 前端TodoList 增加 filter 状态请求时带上 tags ## Acceptance Criteria验收标准 1. 创建待办时可以填写 1 到 5 个标签 2. 点击标签后列表只显示包含该标签的待办 3. 现有按截止日期排序逻辑不回归 4. 无标签的旧数据可以正常展示这个文件的直接作用是让 AI 在动手之前先有一个完成定义。AI 会按照验收标准逐条检查自己是否做完而不是凭借模糊印象输出完代码就收工。对 review 的人来说验收标准也让代码审查更聚焦看实现是否满足这些条目而不是凭感觉判断。3.2 初始化规格目录和模板为了让规格管理不靠自觉最好有一个脚本负责创建目录和模板。下面是一个可直接调整的 Shell 脚本思路#!/usr/bin/env bash set -euo pipefail NAME${1:?用法: ./new-spec.sh add-tags} DATE_DIRspecs/proposals/$(date %Y%m%d)-${NAME} mkdir -p $DATE_DIR cat $DATE_DIR/change.md EOF # Change: 待补充标题 ## Why 为什么需要这次变更 ## What 需要交付什么 ## How 技术上的大致方案是什么 ## Acceptance Criteria 1. 第一条验收标准 2. 第二条验收标准 EOF echo 已创建: $DATE_DIR/change.md这个脚本的价值不只在于节省时间还在于保证每个新需求都随身携带验收标准。你不需要每次打开编辑器重新写模板因为所有新规格都从同一个结构出发。3.3 为什么不能跳过硬写需求这一步我在实际项目里反复见过两类现象。第一类是直接对 Claude Code 说“帮我加一个标签筛选功能”AI 写出来的代码能跑但数据表结构、接口命名、前端组件拆分都和项目现有风格不一致。第二类是在修复 Bug 时顺手重构无关代码导致一个很小的需求引入大量 Diffreview 成本剧增。这两类问题的共同根源是需求没有落到一个 AI 可检查的契约里。规格文件看起来只是多了一层文档实际上它改变了 AI 的执行策略从“基于模糊意图做出最优猜测”变成“基于明确验收条件完成实现”。对团队来说review 时不是凭感觉看代码而是逐条对比验收标准。这个工作方式在人和人协作中成立在人和 AI 协作中同样成立。4. 用 Superpowers 把实现流程固化为“技能”有了规格文件之后下一步解决“如何稳定地执行”。Superpowers 这类技能机制本质上是 Claude Code 的扩展目录把一段复杂的、多步骤的提示词固化成一个命令每次触发时按固定流程执行。4.1 技能的本质和目录结构Claude Code 的扩展机制在不同版本中会变化但常见的形式是在项目.claude/skills下按技能名建目录每个目录里放一个说明文件比如SKILL.md再配合模板或脚本文件。一个最小技能目录看起来像这样.claude/ skills/ implement-spec/ SKILL.md templates/ commit-message.md在 Claude Code 会话中输入/implement-spec或者在 prompt 中提到该技能AI 就会去读取SKILL.md按里面的步骤执行。技能的本质是一份可执行的流程文档它让团队流程不依赖个人记忆地重复。4.2 编写一个“按规格实现”技能下面是一个SKILL.md示例。它会要求 AI 先读规格再实施再验证最后汇总结果。这个顺序本身就是为了防止 AI 跳步。# ImplementSpec ## 使用场景 用户要求实现 specs/proposals 下的某个变更提案。 ## 执行步骤 1. 确认当前在 feature 分支不在 main 分支。 2. 读取用户指定的 change.md列出全部验收标准。 3. 如果需求不明确先向用户提问不要靠猜测实现。 4. 按 How 部分逐步实现不修改范围外的文件。 5. 每完成一个前后端模块运行相关测试。 6. 全部完成后运行 npm test 和 npm run lint。 7. 输出 git diff --stat、测试结果和遗留风险清单。这个文件中最关键的词是“不要靠猜测实现”和“不修改范围外文件”。Claude Code 的上下文和执行能力都很大如果不主动约束范围它的操作边界就会模糊。技能文档的作用就是把这些边界反复写进执行流程。4.3 封装一键命令用脚本包装 Claude Code有了技能之后典型交互会话中你可以手动输入技能名。但要做到“一键”我一般会在项目根目录放一个 Shell 脚本把分支创建、读取规格、执行 Claude Code、输出摘要串起来。#!/usr/bin/env bash set -euo pipefail SPEC_FILE${1:?用法: ./run-ai-change.sh specs/proposals/xxx/change.md} BRANCHfeature/ai-$(date %Y%m%d%H%M%S) git checkout -b $BRANCH claude -p 请使用 /implement-spec 技能实现变更$SPEC_FILE先不要提交完成测试后停下。 echo AI 执行完成请检查 git diff 和测试结果。这个脚本做了三件事创建独立分支、调用 Claude Code 的非交互模式执行技能、把控制权交回给人。脚本里的“先不要提交”很重要。如果你让 AI 把提交也一起做了就会让实现代码和误操作混合在同一个提交里后续无法单独回滚。最佳粒度的做法是让 AI 只改代码并跑测试最后由人来检查 diff 和提交。这里要区分两种触发方式的使用场景触发方式命令示例适用场景缺点交互模式claude后输入指令需求不明确、需要逐步确认人工成本高、流程不统一非交互模式claude -p 指令标准化流程、脚本化、CI 调用指令不完善时容易脱离控制5. 跑通最小闭环需求、实现、验证一次完成前几章的内容如果只作为理论读者收获会打折扣。这里用一个示例需求完整跑一遍为待办应用增加标签筛选。我会把输入、命令、输出、验证串起来。5.1 先定义需求粒度需求不宜描述得太宽也不能细到每个函数都要人工规定。合理粒度是“一次可独立交付的变更”。例如数据模型增加 tags 字段。列表接口支持按 tags 过滤。前端增加一个标签筛选器。补充相关测试。这些点都落到上一章的change.md里。验收标准必须能通过测试验证。像“页面体验更好”这种描述不能作为验收标准因为无法自动判定也无法对比验收。5.2 执行一键脚本假设你已经写好specs/proposals/20250301-add-tags/change.md并且定义了/implement-spec技能那么只需要运行./run-ai-change.sh specs/proposals/20250301-add-tags/change.md如果 Claude Code 正常运行你会看到类似下面的输出字段可能因版本而异已创建分支 feature/ai-202503011020 已读取规格specs/proposals/20250301-add-tags/change.md 已更新 Todo 模型和数据库迁移 已更新 GET /api/todos 支持 tags 参数 已更新前端筛选组件 已通过 12 个单元测试 已通过 ESLint这里要注意AI 的输出不能作为最终结果。这个过程的真正作用是收敛操作你没有手动打开十个文件而是把改动集中到一个分支的 diff 里等着检查。5.3 人工验收和回滚方式建议的验收顺序是先看git status和git diff --stat确认改动文件数量合理。运行git diff检查是否有范围外文件被修改。对照change.md的验收标准逐条在界面或接口上验证。跑完整测试和 lint而不是只看 AI 声称的“已通过”。如果发现问题直接在 feature 分支上修改如果整体不满意直接删除分支重跑。一键流程并不是“无审查流程”。它的价值是把改动收敛到可预期、可回滚的分支上减少人工编辑时的遗漏和碎片化操作。6. 关键参数、权限配置与常见坑在真正使用 Claude Code 进行团队开发时最值得花时间的不是如何写 prompt而是把参数、权限和已知的坑提前排完。这一章给出实际排查时最常用的信息。6.1 常用参数和配置项速查不同版本对参数的支持会有差异使用前应该先通过claude --help确认当前 CLI 支持哪些参数。下面是我在项目中常用的几个维度参数/配置作用使用建议-p非交互执行一段指令适合脚本和自动化流程--model指定模型版本大任务用更强模型简单任务用低配模型控制成本命令白名单限制 AI 能执行的命令只允许 test、lint、git status、git diff 等安全命令目录忽略规则阻止 AI 读取生成目录和敏感文件在配置或 CLAUDE.md 中声明忽略node_modules、dist、.env超时设置防止长时间挂起按任务复杂度设置避免无限等待这些配置的核心目标是降低 AI 操作的破坏半径。它不能让 AI 更聪明但能让 AI 的偶然失误带来的损失变小。6.2 常见坑一不写规格就让 AI 自由发挥现象AI 改完需求后无关组件被重构测试大面积失败。 原因需求边界缺失AI 把“实现某个功能”理解成“让代码变得更好”。 检查查看git diff看是否出现与需求无关的删除和替换。 解决在任何实现开始前先生成change.md并在技能中固定“不修改范围外文件”。 预防在CLAUDE.md中写明没有规格文件不要直接实现功能。6.3 常见坑二给 AI 过大的读取范围和执行权限现象AI 开始扫描node_modules或者其他大目录或者在执行某些清理命令后导致文件被误删。 原因没有提供目录忽略规则也没有限定命令白名单。 检查观察 AI 执行的命令日志看是否出现find、rm -rf等高风险命令。 解决在配置里加入忽略目录并把命令白名单收紧。 预防把 AI 当成受限用户来对待而不是管理员。6.4 常见坑三只验证能启动不验证回归现象应用能启动但已有功能不正常。 原因AI 执行了npm run dev成功后就认为完成没有运行单元测试和 lint。 检查手动运行npm test、npm run lint、构建命令。 解决把测试和 lint 写进技能的固定步骤测试失败视为未完成。 预防把验收标准写进change.md并让 AI 以“验收标准逐条成立”作为完成定义。当出现不可控行为时建议按以下顺序排查当前是否在独立 feature 分支上主分支是否被污染。需求规格是否存在验收标准是否可测试。命令白名单和目录忽略是否生效。测试和 lint 是否真的通过而不是 AI 自行声明通过。如果上下文不足是否应该把任务拆成更小的技能步骤。如果模型版本或参数配置发生变化是否直接导致行为不同。7. 让 AI 稳定交付全栈项目落地规范与检查清单最后一章落到“团队怎么用起来”。不是所有人都会像研究新工具一样研究 Claude Code所以需要把规则沉淀到项目文件、检查清单和自动化流程里。7.1 在项目文件中固化三套规则我会在项目根目录维护三样东西CLAUDE.md项目说明和约束让 AI 每次启动都先读到。.claude/skills/团队统一技能包括实现、测试、写变更日志等高频任务。scripts/一键命令封装分支、规格、执行和检查流程。这三样东西同时存在才能避免“流程只在某个成员的终端里”的情况。新成员拉到项目后只需要跑同样的脚本就能重现同样的 AI 工作流。7.2 发布前检查清单每一次由 AI 完成的变更在合并前都应过一遍下面这张表检查项通过标准需求规格change.md存在验收标准可测试分支隔离改动发生在 feature 分支主分支无直接提交改动范围git diff未包含范围外文件自动化验证测试、lint、构建全部通过人工验收对照验收标准逐条确认回滚方式相关改动可以单独 revert 或删除分支重跑敏感信息日志、.env、密钥没有出现在改动中这张表不是为了增加流程负担而是为了让“AI 改代码”这件事拥有和人改代码同等质量的下限。AI 可以提升速度但不能降低保障。7.3 生产环境还需要什么生产环境的 AI 编码工作流还应叠加这些措施配置外置化。模型版本、密钥、API 地址不应硬编码在脚本里而是走环境变量。日志和监控。记录每次 AI 执行了哪些命令、改动了哪些文件。权限最小化。AI 使用的账号或 CI 身份应当只拥有当前仓库的写权限。自动 diff 分析。如果能把 AI 改动接入自动化静态检查或差异分析可以更快发现意外改动。灰度合并。不要让 AI 直接推动生产部署代码合并依然要走 PR 和 CI 门禁。把 AI 编码能力接进生产流程与把它用在一个本地 Demo 里的风险模型完全不同。本地方便优先生产安全优先。7.4 扩展方向当基础流程稳定后可以考虑几个方向在 CI 中调用同名脚本对每个提案自动生成实现分支和 PR。建立团队级change.md模板要求所有变更必须包含验收标准。增加自动化规格检查发现缺少验收标准的提案时直接阻断。让 AI 在完成代码后自动生成变更日志和 PR 描述减少人工整理成本。对 AI 生成的 diff 做统计定期观察哪类任务成功率高、哪类容易踩坑。这些扩展的共同目标是让 AI 协作从一个人的技巧变成团队的方法论。实际操作中最重要的判断并不是“我应该用哪个模型”而是先确认这次改变是否已经有规格、是否在独立分支、是否有验证手段、是否能单独回滚。如果这四件事都成立那么让 Claude Code 去执行具体改动是省力的如果有一项不成立那么无论 prompt 写得多么完整生成的代码都需要花费更多时间审查。用 OpenSpec 约束需求用 Superpowers 固化流程用 Claude Code 执行实现用测试和 review 守住质量线这四层配合起来才能让 AI 从“能写代码”变成“能稳定交付全栈项目”。