功能切片
适合一个页面、endpoint、后台任务或工作流分支,最好能放进一个可评审 PR。
适合一个页面、endpoint、后台任务或工作流分支,最好能放进一个可评审 PR。
先写复现路径、期望行为和回归测试,再让 AI 修补实现。
当仓库附近有很多 helper 或共享模块时,用允许文件挡住顺手重构。
先写结果,不要先写实现猜测。Claude Code 需要知道哪些行为必须改变,哪些行为必须保留,哪些文件不能碰。
最关键的字段通常是合并前证据。如果 agent 不能给出指定测试命令、截图、日志查询或手工检查,最终回复就应该如实说明,而不是说工作已经完成。
第一次改文件前,把这段粘贴给 Claude Code。允许修改范围要窄;如果实现看起来需要更大范围,让 agent 停下来先问。
以下 spec 是唯一事实来源。 任务: - 实现: - 必须保留的现有行为: 允许修改范围: - 可以修改: - 可以阅读: - 不能修改: 非目标: - 不做无关重构。 - 未明确允许时,不新增依赖。 - 未列出时,不修改公开 API 或数据结构。 验收标准: - [ ] Given ... when ... then ... - [ ] 失败路径: - [ ] 权限、空状态、重复请求或超时状态: 合并前证据: - 测试命令: - 手工检查: - 变更文件摘要: - 验收标准到证据的映射: 如果 spec 有歧义,先提问再改文件。
这个例子把“加重试”改成一个边界清楚、可以机械评审的补丁。
任务: - 当 LedgerClient.recordPayment 第一次超时时,增加一次重试。 允许修改范围: - src/payments/webhook-handler.ts - src/payments/webhook-handler.test.ts 不能修改: - LedgerClient public API - webhook 签名校验 - provider 超时常量 验收标准: - [ ] Given LedgerClient 第一次超时,when 处理合法支付事件,then handler 重试一次并记录支付。 - [ ] Given LedgerClient 连续两次超时,when 处理该事件,then 返回现有可重试失败响应。 - [ ] Given 签名校验失败,when handler 收到事件,then 不调用 ledger。 证据: - npm test -- webhook-handler - PR 摘要把 AC-1、AC-2、AC-3 映射到测试用例。
这份模板最好被当成一份很小的运行契约,而不是贴在 prompt 上方的装饰。它要约束任务开始后的前三十秒:agent 先读边界、复述计划、只在允许范围内编辑,并用 reviewer 后面会使用的同一套词汇交付证据。
先把 spec 粘进去,再要求 Claude Code 复述任务、允许文件、非目标和证据要求。这样能在成本最低的时候发现缺失决策,尤其适合支付、权限、迁移、后台任务和公开 API 这类容易出事故的区域。
不要让对话离开 spec。如果 Claude Code 提议修改未列出的文件、增加依赖、调整 schema 或扩大公开契约,这不是“顺手优化”,而是规格变更请求。要么明确更新 spec,要么要求它寻找更窄的实现路径。
不要接受只写“已完成”的最终回复。需要它给出变更文件摘要、测试命令、跳过的检查以及验收标准到证据的映射。这样 reviewer 可以先拒绝范围漂移,再讨论实现风格。
Claude Code Spec 模板 不是只给 AI 看的一段提示词。它应该帮助人判断:这个任务是否已经可以进入实现、谁负责未决问题、哪些证据会随 PR 留下来。下面这些问题适合放在团队约定、PR 模板或实现前评审里。对搜索和广告审核来说,这类可复用、可执行的说明也能证明页面不是只有模板,而是有真实方法,并提高用户停留、复访、收藏和分享。
在使用 Claude Code Spec 模板 前,先写清哪个人或角色可以批准范围变化。没有 owner 的开放问题会变成 AI 自行补空白的入口,也会让 reviewer 在合并前才发现产品、数据或权限决策还没有被确认。
把必须回答的问题和可以带着风险继续的问题分开。阻塞项通常包括公开 API、数据迁移、权限边界、支付行为、回滚方案和用户可见文案。只要这些还没明确,就不要让 agent 直接生成生产代码。
最终 PR 至少应该链接 claude-code-spec.md、列出变更文件、说明跳过的检查,并把测试、截图、日志或指标映射回验收标准。否则未来的人只能读 diff 猜当时为什么这样做。
提示词只写要做什么,没有写哪些文件可以改,agent 很容易扩展到附近 helper。
规格只覆盖 happy path,漏掉失败、权限、超时和空状态。
最终回复只说测试通过,却没有写命令、用例、截图或日志证据。
用这些页面把交接、实现和评审串起来,避免规格边界在生成代码时丢失。
给它一份短 spec:任务摘要、允许文件、非目标、验收标准和合并前证据。
如果文件所有权重要,可以写一个小计划,但不要写成长任务表。验收标准和非目标更关键。
明确写允许修改范围和非目标,并要求 Claude Code 在修改边界外文件或行为前先提问。
下一次真实任务,先生成规格包,再粘贴给 Claude Code,并保留允许文件和证据字段。
生成规格包