AI 编码交接

Claude Code Spec 模板

当 Claude Code 准备改文件,但任务还需要边界时,用这份模板。它让 agent 知道该做什么、不能做什么,以及最后必须提供哪些证据。

更新日期:2026-05-25

什么时候用这份模板

功能切片

适合一个页面、endpoint、后台任务或工作流分支,最好能放进一个可评审 PR。

Bug 修复

先写复现路径、期望行为和回归测试,再让 AI 修补实现。

高风险修改

当仓库附近有很多 helper 或共享模块时,用允许文件挡住顺手重构。

这份 spec 要先决定什么

先写结果,不要先写实现猜测。Claude Code 需要知道哪些行为必须改变,哪些行为必须保留,哪些文件不能碰。

最关键的字段通常是合并前证据。如果 agent 不能给出指定测试命令、截图、日志查询或手工检查,最终回复就应该如实说明,而不是说工作已经完成。

粘贴之前检查

  • 任务可以用一句话说明。
  • 允许写入范围小于整个仓库。
  • 非目标挡住常见范围扩张。
  • 每条验收标准都能变成测试或手工检查。
  • agent 必须在修改未列出的文件或契约前先提问。

可复制 Claude Code Spec

第一次改文件前,把这段粘贴给 Claude Code。允许修改范围要窄;如果实现看起来需要更大范围,让 agent 停下来先问。

claude-code-spec.md
以下 spec 是唯一事实来源。

任务:
- 实现:
- 必须保留的现有行为:

允许修改范围:
- 可以修改:
- 可以阅读:
- 不能修改:

非目标:
- 不做无关重构。
- 未明确允许时,不新增依赖。
- 未列出时,不修改公开 API 或数据结构。

验收标准:
- [ ] Given ... when ... then ...
- [ ] 失败路径:
- [ ] 权限、空状态、重复请求或超时状态:

合并前证据:
- 测试命令:
- 手工检查:
- 变更文件摘要:
- 验收标准到证据的映射:

如果 spec 有歧义,先提问再改文件。

填好的示例

这个例子把“加重试”改成一个边界清楚、可以机械评审的补丁。

filled-example.md
任务:
- 当 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 映射到测试用例。

在真实 Claude Code 任务里怎么用

这份模板最好被当成一份很小的运行契约,而不是贴在 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 会留下什么证据?

最终 PR 至少应该链接 claude-code-spec.md、列出变更文件、说明跳过的检查,并把测试、截图、日志或指标映射回验收标准。否则未来的人只能读 diff 猜当时为什么这样做。

常见错误

没有文件边界

提示词只写要做什么,没有写哪些文件可以改,agent 很容易扩展到附近 helper。

只有成功路径

规格只覆盖 happy path,漏掉失败、权限、超时和空状态。

证据只是描述

最终回复只说测试通过,却没有写命令、用例、截图或日志证据。

相关资源

用这些页面把交接、实现和评审串起来,避免规格边界在生成代码时丢失。

AI 规格包生成器

在浏览器里生成 spec.md、任务、验收标准和证据要求。

打开生成器

AI Agents 的 spec.md 模板

当多个 agent 或工具要共享事实来源时,用 repo 级 spec.md。

打开模板

AI PR 评审清单

合并前用原始规格检查生成 diff。

打开清单

Claude Code Spec FAQ

让 Claude Code 改文件前应该给它什么?

给它一份短 spec:任务摘要、允许文件、非目标、验收标准和合并前证据。

spec 里要写实现步骤吗?

如果文件所有权重要,可以写一个小计划,但不要写成长任务表。验收标准和非目标更关键。

怎样防止范围漂移?

明确写允许修改范围和非目标,并要求 Claude Code 在修改边界外文件或行为前先提问。

下一次真实任务,先生成规格包,再粘贴给 Claude Code,并保留允许文件和证据字段。

生成规格包