仓库事实来源

AI Agents 的 spec.md 模板

好的 spec.md 不是提示词外壳,而是让人类、AI agent、测试和 reviewer 对同一件事达成一致的共享契约。

更新日期:2026-05-25

spec.md 放在哪里起作用

多 agent 工作

当草拟、计划、编码和评审可能由不同工具完成时,spec.md 是共同事实来源。

仓库记忆

把决策放在代码附近,让后来的 reviewer 知道为什么要改。

Spec-First AI

让每个编码 agent 在实现前都收到同一份边界清楚的规格。

spec.md 里应该写什么

它要回答:改什么、为什么重要、哪些边界真实存在、用什么证据证明完成。不要把它写成含糊产品作文。

开放问题要认真写。如果决策还不知道,就写出负责人,并在回答前阻塞实现,或明确接受风险。

spec.md 准备度检查

  • 目标写的是最小有用结果。
  • 范围列出允许写入路径和只读上下文。
  • 非目标挡住未批准的依赖、契约和重构。
  • 验收标准至少包含一个边界或失败场景。
  • 开放问题写明负责人,以及是否阻塞实现。

可复制 spec.md

可以放在 docs/specs、.specs 或任务目录。实现发生变化时,要和 PR 一起更新它。

spec.md
# spec.md

## Context
- 问题:
- 当前行为:
- 受影响用户或系统:

## Goal
- 最小有用结果:

## Scope
- 范围内:
- 允许写入路径:
- 只读上下文:

## Non-goals
- 明确排除:
- 不能变化的依赖或契约:

## Acceptance Criteria
- [ ] AC-1:
- [ ] AC-2:
- [ ] AC-3:

## Evidence
- 自动化测试:
- 手工检查:
- 日志、截图、指标或迁移输出:

## Open Questions
- 问题:
- 负责人:
- 是否阻塞实现:yes/no

如果这份 spec 和提示词冲突,以 spec 为准。

填好的示例

这个示例展示 AI agent 可以安全执行的详细程度。

filled-example.md
# spec.md

## Context
- 用户可以关闭所有通知,但安全告警必须保持强制开启。

## Goal
- 增加按渠道设置通知偏好,同时不允许关闭安全告警。

## Scope
- 范围内:settings UI、preferences API client、preference form tests
- 允许写入:src/settings/notifications/*, tests/settings/*
- 只读上下文:src/auth/*, src/api/preferences.ts

## Non-goals
- 不修改投递管线
- 不做 digest mode
- 不修改 auth role

## Acceptance Criteria
- [ ] Marketing email toggle 保存 marketingEmail=false。
- [ ] Security alert 行可见但锁定。
- [ ] 保存失败时还原之前状态并显示错误。

## Evidence
- npm test -- notifications
- 截图:锁定的 security alert 行
- PR 说明变更文件和跳过的检查

真实场景:两轮 agent 共用同一份 spec.md

团队先让一个助手起草通知偏好计划,再让另一个编码 agent 实现。如果没有仓库里的 spec.md,第二个 agent 只会看到最新提示词,很容易漏掉最初确认过的非目标。

共享记忆

把最终决策放进 .specs/notification-preferences/spec.md,写清安全告警锁定,以及 digest mode 不在本次范围内。

更新时机

如果实现时发现 API 无法持久化按渠道设置,应先更新 spec.md 并重新评审,再扩大任务。

评审用法

reviewer 先用 spec.md 对照最终 diff,再看测试和 UI 截图。聊天历史只能作为辅助上下文,不是事实来源。

怎样让 spec.md 在 PR 中保持有效

spec.md 只有在工作变化时仍然有权威,才真正有价值。把它当成一份跟随分支移动的小契约:agent 改代码前先读它,决策变化时开发者先更新它,reviewer 最后用它判断 diff。

放在变更附近

把 spec.md 放到未来读者找得到的位置:docs/specs、.specs,或仓库约定的任务目录。如果它只留在聊天记录里,就不能被 diff、不能从 PR 链接,也不能被下一轮 agent 复用。

扩范围前先更新

实现过程中发现缺失决策时,先更新 spec.md,再让 agent 继续。不要让代码成为第一个出现新行为、新依赖、schema 变更、重试规则或权限决策的地方。

评审时按文件判断

review 时先用 spec.md 对比变更文件、验收标准、非目标和证据,再读实现风格。如果提示词历史和 spec.md 冲突,以这份持久文件为准,除非它被明确修改。

常见 spec.md 问题

提示词倾倒

文件只是重复聊天提示词,没有保存可长期引用的决策。

开放问题没有负责人

没人负责的问题会变成 agent 自行猜测的空间。

没有更新习惯

实现改变了行为,但 spec.md 没有同步更新,最后失去权威。

相关资源

以 spec.md 为锚点,再选择对应工具的交接模板。

Claude Code Spec 模板

把更窄的任务版本粘贴给 Claude Code。

打开模板

Cursor AI 编码 Spec 模板

给 Cursor 写提示词时使用读写范围。

打开模板

功能规格模板

需要产品和工程一起评审时,用更完整的模板。

复制模板

spec.md FAQ

spec.md 应该放在哪里?

可以放在 docs/specs、.specs,或仓库已有约定的任务目录里。

spec.md 需要提交到仓库吗?

只要是有意义的行为变更,就建议提交,让规格和实现证据一起移动。

提示词和 spec.md 冲突怎么办?

以 spec.md 为事实来源;继续让 agent 执行前,先明确更新 spec.md。

稳定的 spec.md 能让 AI 工具帮忙,而不是让产品决策消失在提示词里。

生成规格包