把一个需求稳定交给Claude Code
Claude Code 的执行能力很强，输入一句“帮我改一下”也能开始干活。真实项目里，这种指令留给模型的猜测空间太大。它不知道改动边界、完成标准、能否调整接口，也不知道哪些验证必须跑。
我把一个任务交给 Claude Code 时，通常会把协作过程拆成五段：任务契约、只读探索、方案确认、小步实现、证据验收。小改动可以压缩步骤，跨模块或高风险任务最好把这几段保留下来。
下面用“为库存预占增加超时自动释放”这个需求贯穿全文。它涉及订单、库存、定时任务和消息幂等，刚好能看出工作流为什么重要。
先写一份能执行的任务契约
高质量任务说明不需要写成长篇需求文档，但要回答五个问题。
| 问题 | 库存预占案例中的答案 |
|---|---|
| 最终要交付什么 | 超过 15 分钟未支付的订单释放库存 |
| 修改范围在哪里 | order-service、inventory-service 及相关测试 |
| 哪些东西不能动 | 不改现有表字段，不改公开下单接口 |
| 哪些行为必须兼容 | 已支付订单不能释放，重复消息不能重复加库存 |
| 怎么算完成 | 新测试先失败后通过，相关模块测试全绿，给出 diff 与风险说明 |
一段可直接使用的任务说明可以这样写：
目标：为库存预占增加超时释放能力。订单创建 15 分钟后仍未支付，
系统要释放对应库存；已支付、已取消订单不处理。
范围：只调查和修改 order-service、inventory-service 以及相关测试。
边界：不要改数据库表结构，不要修改公开下单接口，
不要执行提交、推送或部署操作。
验收：先补一个能复现库存未释放的失败测试，再修改实现。
完成后运行相关单测和模块测试，列出命令、结果、改动文件和剩余风险。
任务说明里有范围和禁止动作，Claude 的搜索与修改会更聚焦。验收标准能防止它停在“代码看起来已经写好”这一步。
第一段只读探索要拿到什么
复杂需求开始时，我会明确说“先不要改文件”。只读探索需要产出一份能支持决策的地图，至少包含：
- 请求或事件从哪里进入；
- 关键状态存在哪里；
- 哪些类负责状态变化；
- 已有的相似流程是什么；
- 当前测试覆盖到了哪里；
- 可能牵动的外部依赖与风险。
库存预占案例可以沿三条线并行调查：订单状态流转、库存流水、超时触发方式。此时先别急着确定方案。也许项目已经有延迟消息，也许统一使用定时扫描，也可能存在订单关闭事件，只是库存消费者漏了分支。
进入只读分析。请回答：
1. 下单后库存预占记录在哪里创建和释放；
2. 订单支付、取消、超时分别经过哪些类和消息；
3. 项目中已有的延迟任务或定时任务是怎样实现的；
4. 哪些测试最接近这个需求。
给出文件和方法位置，区分确认事实与待验证猜测。暂时不要修改文件。
“区分事实与猜测”很有用。Claude 很容易把类名、注释和调用关系拼成一条听起来顺畅的故事，跨服务配置、消息路由和条件开关还需要继续核对。
方案确认要把选择理由讲清楚
探索结束后，方案应该落到具体文件、数据流和验证方式。只有“增加一个定时任务”还不够，至少要说明：
- 谁产生超时信号；
- 谁读取订单最新状态；
- 谁负责释放库存；
- 重复触发怎样保持幂等；
- 失败后怎样重试和观测；
- 哪些现有行为需要回归。
如果项目已有延迟消息，可以让订单服务在预占成功后投递一条延迟检查消息。消费者收到消息后重新查询订单状态，只有仍处于待支付状态才调用库存释放。库存侧以预占流水状态做条件更新，重复消息只能有一次释放成功。
如果项目没有可靠的延迟基础设施，直接引入新中间件可能超过需求范围。此时复用已有定时任务会更合适。方案选择取决于当前仓库和部署条件，不能只按通用架构经验拍板。
我会要求 Claude 给出这样的计划：
基于刚才确认的调用链，给出实现计划。每一步写明：
- 要修改的文件和方法；
- 该改动解决哪一条业务行为；
- 对应测试怎样写；
- 失败或重复执行怎样处理；
- 可能影响的旧路径。
计划里不要包含提交、推送和部署。
实现阶段为什么要小步推进
一次改十几个文件，出错后很难知道是哪一步造成的。小步实现能保留因果关系，也便于人检查。
库存预占需求可以按下面的节奏走：
- 先补库存释放幂等测试，并确认它在旧实现上失败；
- 修改库存服务，让状态更新带上条件；
- 运行库存模块测试；
- 补订单超时触发测试；
- 接入已有延迟任务或定时任务；
- 运行订单与库存相关测试；
- 查看完整 diff，检查有没有超范围修改。
失败测试要真的失败过
测试驱动在 AI 编程里很实用，因为它先把预期行为钉在可执行证据上。测试没有在旧实现上失败过，就无法确定它是否覆盖了问题。
可以这样要求：
先只写测试，不改生产代码。测试要覆盖：
- 待支付订单超过 15 分钟会释放一次库存；
- 同一条超时消息重复消费，库存只恢复一次；
- 已支付订单收到超时消息，库存保持不变。
运行测试并保留失败信息。确认失败原因和目标问题一致后，再开始改实现。
如果失败原因是测试数据没初始化，说明用例还没触达业务缺陷。Claude 需要先修好测试基线，再进入实现。
每次改动后给它一个反馈信号
模型擅长根据反馈继续修正。构建、单测、静态检查、接口响应和截图都可以充当反馈信号。
没有验证命令时，Claude 只能靠阅读代码判断“应该能工作”。有了可运行检查，它才能看到类型错误、断言差异、事务问题和配置缺失。
怎样控制权限而不拖慢节奏
权限可以按风险分层。只读搜索和固定测试命令通常风险较低；文件修改需要看目录；删除、远端写入、生产操作和凭据读取应继续拦截。
| 操作 | 建议策略 |
|---|---|
git status、git diff、rg | 可按精确模式放行 |
| 项目已有的测试与 lint | 核对命令后按前缀放行 |
| 业务源码 Edit/Write | 保留变更可见性，按项目情况授权 |
| 历史迁移文件、生产配置、密钥目录 | deny 或 PreToolUse Hook |
| commit、push、建 PR | 用户明确要求后再做 |
| 部署、数据库写入、外部消息发送 | 人工确认、最小权限与审计 |
Auto Mode 可以减少低风险动作的确认，但它不提供完整的安全隔离。高风险任务仍应放进容器、临时凭据或受限账号，并保留权限规则和人工 Review。
工作区里的 .env、云平台凭据、SSH Key、Maven 私服密码、生产日志和数据库 dump 都可能带敏感信息。不要因为任务需要“查配置”就把整个用户目录开放给 Agent。
MCP和插件什么时候接入
本地代码与命令已经能回答的问题，没必要先接外部工具。需要读取 Sentry 错误、GitHub PR、Figma 设计稿、内部知识库或数据库只读结果时，再接入对应的 MCP Server。
接入前我会确认四件事：
- 这个 Server 暴露哪些工具；
- 工具是只读还是会产生外部写入；
- 凭据放在哪里，是否会进入配置或 Shell 历史；
- 返回结果有多大，会不会迅速挤满上下文。
工具数量也要控制。长期不用的 MCP Server 可以断开；会修改外部状态的工具最好保留逐次确认。
Claude跑偏后怎样纠正
跑偏时继续追加“还是不对”“再想想”通常效果一般。纠正应该带证据和边界。
方向错了
指出哪条事实被误解，并让它回到具体文件核对：
你把库存释放理解成直接增加 SKU 可售数，但项目使用的是预占流水状态机。
请重新阅读 ReservationRecord 和 releaseByReservationId，
先解释幂等条件，再调整方案。暂时不要改代码。
修改范围失控
立刻停下来审查 diff：
暂停实现。当前 diff 出现了公共 API 和数据库迁移文件，超出约定范围。
请逐个解释这些修改的必要性，并给出不修改它们的替代方案。
连续多次纠正仍无效
同一问题纠正三次仍在打转，当前上下文里可能已经积累了冲突判断。此时可以保存已确认事实和当前 diff，新开会话，用更干净的任务说明接着做。长任务交接的写法会在后面的文档单独展开。
最终交付应该包含哪些证据
任务结束时，我希望看到一份能快速复查的交付说明：
1. 结果：库存预占超时释放已实现。
2. 关键改动：列出文件、方法和对应业务行为。
3. 验证：列出实际执行的命令、通过数量和失败情况。
4. 未验证项：例如未连接真实消息中间件、未跑全量集成测试。
5. 风险：消息延迟、时钟偏差、旧数据兼容等。
6. 工作区：说明未提交、未推送、未部署。
“测试通过”要带命令和结果，“页面正常”要带截图或可复现步骤，“调用链已经确认”要带文件与方法。证据越具体，人接手检查越轻松。
我会把 Claude Code 当成能执行工具的工程协作者。复杂需求先写目标、范围、禁止动作和验收标准，再让它只读探索调用链。方案确认后，以失败测试为起点小步实现，每一步都运行能够反馈真实状态的检查。最终验收看 diff、测试命令和运行证据。高风险操作交给权限、Hook、Sandbox 和人工审批，避免只靠对话提醒。