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 映射到测试用例。

常见错误

没有文件边界

提示词只写要做什么,没有写哪些文件可以改,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,并保留允许文件和证据字段。

生成规格包