这段时间大家都在讨论 Vibe Coding。很多人告诉我们不要一上来就写代码，要先写文档、先规划，但很少有人真正讲清楚：在开始让 Agent 干活之前，我们到底应该准备什么？这篇文章，我试着把这件事总结清楚。

本文会涉及一些背后的原理和实践方法，内容相对完整。如果你想系统理解 AI Agent 开发前的准备流程，可以完整阅读；如果只是想快速上手，也可以先关注文中的 Checklist 和实践部分。后续我也会整理一篇更偏实践、更快速上手的版本，帮助大家直接应用到自己的项目中。

AI Agent 开发项目前置准备工作指南

定位：本指南不讨论具体编程语言、不讨论具体框架、不讨论某一个 Agent。它总结的是所有使用 AI Agent 开发项目之前，都应该完成哪些准备工作——一套具有普适性的 SOP。

核心理念：AI Agent 项目的成功，80% 取决于编码之前的准备，而非编码过程中的技巧。Anthropic 将此称为 Context Engineering（上下文工程）——"在 LLM 推理时筛选和维护最优 token 集合的策略"。Cursor 官方称之为 "从规划开始"（Start with Planning）。GitHub Copilot Cloud Agent 在 2026 年将协作顺序改为 Research → Plan → Code。这些理念殊途同归：先想清楚，再动手。

参考来源：Anthropic 官方 Engineering Blog（Effective Context Engineering、Effective Harnesses for Long-Running Agents）、Cursor 官方 Agent Best Practices、AGENTS.md 开放标准（60,000+ 开源项目采用）、Spec-Driven Development（GitHub Spec Kit）、Research-Plan-Implement Pattern（AgentPatterns.ai）、以及社区实战经验。

---

目录

• 第一部分：明确目标（Goal）
• 第二部分：需求整理（Requirement）
• 第三部分：知识准备（Knowledge）
• 第四部分：上下文准备（Context）
• 第五部分：约束（Constraints）
• 第六部分：规划（Planning）
• 第七部分：文档准备（Documentation）
• 第八部分：开发规则（Working Rules）
• 第九部分：Prompt 准备
• 第十部分：风险检查（Pre-flight Checklist）
• 总结：为什么编码之前比编码过程中更重要

---

第一部分：明确目标（Goal）

为什么不能直接开始写代码？

直接开始写代码是 AI Agent 开发中最常见、也是代价最高的错误。

Anthropic 的研究表明，66% 的开发者经历过"AI 代码差不多对但不完全对"的困境，45% 的人说调试 AI 代码比自己写还慢。但遵循结构化实践的开发者，这些数字大幅下降。原因不是 prompt 技巧，而是上下文工程——给 AI 提供正确信息的能力。

当你直接说"帮我写一个 XX 功能"时，Agent 面临的信息真空会导致：

1. 方向偏差：Agent 猜测你的意图，大概率猜错细节
2. 架构冲突：Agent 选择的架构与你的预期不符
3. 范围蔓延：Agent 做了你不需要的东西，漏了你需要的东西
4. 返工成本：生成的代码与项目不兼容，修正比重写还慢

官方理念引用："模糊的计划产生模糊的代码。具有明确约束的精确计划产生集中、可审查的输出。" —— Agentic Engineering Complete Guide (2026)

如何定义项目目标？

一个清晰的项目目标应该回答以下问题：

如何描述最终交付物？

交付物的描述需要达到"另一个工程师不需要追问就能开始工作"的程度：

维度	模糊描述（❌）	清晰描述（✅）
功能	"做一个用户系统"	"支持注册、登录、密码重置、角色管理的用户系统"
交互	"页面要好看"	"列表页 + 详情页 + 表单页，支持分页和搜索"
数据	"存用户数据"	"用户表含：邮箱（唯一）、昵称、角色、状态、创建时间"
验收	"能用就行"	"注册→登录→查看个人信息→修改密码，全流程跑通"
边界	"先做着看"	"MVP 不含：社交功能、支付、消息推送"

如何划定项目边界？

划定边界是防止 Agent"自作主张"的关键。使用 In-Scope / Out-of-Scope 双列表：

如何告诉 Agent 什么是不需要做的？

这是最容易被忽略的一步。Agent 的默认行为是"尽可能多做"，你需要明确告诉它不要做什么：

告诉 Agent "不需要做什么" 的方式：

1. 在项目指令文件中明确写出 Out-of-Scope
2. 在每个任务 Prompt 中标注 "不要包含 XXX"
3. 在约束中写明 "不要修改 XXX 文件/目录"
4. 在验收标准中写明 "不需要测试 XXX"

最佳实践：Out-of-Scope 列表和 In-Scope 列表同等重要。每当你发现 Agent 做了不需要的东西，立刻把"不做 XXX"加入项目指令文件。这是增量式完善的过程。

常见错误

错误	后果	正确做法
目标只有一句话	Agent 自由发挥，方向偏离	用四维度模板完整描述
没有验收标准	不知道什么时候算"完成"	写明可验证的 Success Criteria
没有划定边界	范围蔓延，MVP 永远完不成	明确 Out-of-Scope
目标太理想化	Agent 无法在合理时间内完成	定义 MVP 最小范围
边界只存在于脑中	Agent 无法感知	写入文档，Agent 可读

✅ Checklist

•  项目解决的问题已明确描述（Problem Statement）
•  最终交付物已清晰定义（Deliverable）
•  成功标准可验证（Success Criteria）
•  MVP 最小范围已确定
•  In-Scope 列表已完成
•  Out-of-Scope 列表已完成
•  "不需要做什么"已写入项目指令文件

🏆 最佳实践

"对每一行问自己：删掉这行，Agent 会犯错吗？" —— 这是 CLAUDE.md 社区共识的黄金规则，同样适用于目标定义。如果删掉某条描述不会导致 Agent 犯错，那它就是多余的；如果 Agent 没有这条信息就会走偏，那它就是必须的。

🛠 推荐工具

工具	用途
任意 Markdown 编辑器	撰写目标文档
项目指令文件（AGENTS.md / CLAUDE.md 等）	将目标写入 Agent 可读的位置

---

第二部分：需求整理（Requirement）

如何把脑中的想法整理成 Agent 能理解的需求？

人类之间的交流依赖大量隐含上下文——对方能"猜"到你的意思。但 Agent 没有 this 隐含上下文，它只能基于你明确写出的信息工作。

需求整理的核心原则：把隐性知识显性化。

需求整理的三步法：

Step 1: 自由表达
- 不用管格式，把脑中的想法全部倒出来
- 可以是对话、语音转文字、思维导图
- 目标：捕获所有想法，不遗漏

Step 2: 结构化
- 将自由表达的内容按结构整理
- 使用统一的需求模板
- 目标：让信息有序、可检索

Step 3: 验证完整性
- 站在 Agent 的角度读一遍
- 问自己："如果我是 Agent，只看这份文档，能开始工作吗？"
- 目标：消除信息盲区

需求文档需要达到什么程度？

需求文档的黄金标准是：一个对新项目一无所知的工程师，读完文档后可以独立开始工作，不需要追问任何问题。

对于 AI Agent 来说，这个标准更高——因为 Agent 不会追问（至少不会主动追问），它会在信息缺失时自行假设，而这些假设往往是错误的。

需求文档至少应包含：

需求不完整会造成什么问题？

不完整类型	Agent 的行为	后果
缺少边界条件	Agent 自行假设边界	边界 case 崩溃
缺少错误处理要求	Agent 忽略异常	运行时崩溃
缺少性能要求	Agent 选择最简单实现	性能不达标
缺少安全要求	Agent 忽略安全	安全漏洞（研究显示 AI 代码中 45% 存在安全问题）
缺少数据格式	Agent 自行定义格式	与其他系统不兼容
缺少交互细节	Agent 自行设计交互	用户体验不符预期

数据引用：根据安全研究，AI 生成的代码中只有 55% 是安全的。XSS 漏洞出现率 86%，SQL 注入出现率 20%。2025 年对 AI 代码的信任度从 43% 下降到 29-33%。—— AI Blueprint Guide

有哪些需求描述模板？

模板一：User Story 格式（适合功能需求）

作为 [用户角色]
我想要 [做什么]
以便 [达到什么目的]

验收标准：
- [条件1] 时，应该 [行为1]
- [条件2] 时，应该 [行为2]
- 边界情况：[特殊情况] 时，应该 [处理方式]

模板二：Spec 格式（适合 Spec-Driven Development）

## Feature: [功能名称]

### Context
[为什么需要这个功能]

### Behavior
- Given [前置条件]
- When [触发动作]
- Then [预期结果]

### Constraints
- [约束1]
- [约束2]

### Out of Scope
- [明确不包含的内容]

模板三：输入-输出规格（适合 API / 接口需求）

## [功能名称]

### Input
- 参数1: 类型, 是否必填, 取值范围, 说明
- 参数2: 类型, 是否必填, 取值范围, 说明

### Output
- 成功: { 字段1, 字段2, ... }
- 失败: { 错误码, 错误信息 }

### Rules
- 规则1: [业务规则]
- 规则2: [业务规则]

### Edge Cases
- 边界1: [处理方式]
- 边界2: [处理方式]

✅ Checklist

•  需求已从"脑中想法"转化为"结构化文档"
•  每个功能有明确的输入、输出和验收标准
•  非功能需求（性能/安全/可用性）已量化
•  边界条件和异常情况已描述
•  Out of Scope 已明确列出
•  需求文档通过"陌生人测试"（不懂项目的人能看懂）

🏆 最佳实践

"Spec 先行，哪怕只是 5 行"：即使是迷你 Spec，也要说清背景、输入输出、边界条件、验收标准。比直接说"帮我做个登录"强十倍。在 Spec-Driven Development 中，Spec 是 single source of truth，AI 按 Spec 生成，Review 对照的是 Spec 而不是凭感觉。

⚠️ 常见错误

1. 需求只存在于对话中：需求散落在聊天记录里，没有沉淀为文档——Agent 在新会话中无法获取
2. 需求太抽象："做一个好用的界面"——Agent 无法理解"好用"的标准
3. 忽略非功能需求：只写功能需求，不写性能/安全/可用性——Agent 生成的代码可能不安全
4. 不写验收标准：没有标准就无法判断"是否完成"——导致无限修改

🛠 推荐工具

工具	用途
Spec Kit (GitHub)	Spec-Driven Development 工具集
OpenSpec	规格驱动开发工作流
任意 Markdown 编辑器	撰写需求文档

---

第三部分：知识准备（Knowledge）

开始开发前，需要准备哪些资料？

Agent 不是全知的。即使是最强的模型，也存在知识截止日期和对特定领域/项目的不熟悉。在开始编码前，你需要为 Agent 准备好它需要的"知识弹药"。

如何让 Agent 优先参考这些资料？

不同 Agent 工具提供了不同的机制来让 Agent 优先参考特定资料：

机制	说明	适用场景
项目指令文件	AGENTS.md / CLAUDE.md 等，Agent 每次启动自动读取	项目全局知识
规则文件	.cursor/rules/ 等，按条件自动激活	特定文件类型/目录的规范
上下文引用	在 Prompt 中用 @文件名 引用	需要特定文件时
MCP 集成	通过 MCP Server 连接外部知识源	需要动态查询时
知识库	项目内的 docs/ 目录	静态文档
Skills 系统	按需加载的专业知识	特定工作流

AGENTS.md 标准：AGENTS.md 是一个开放的跨工具标准，被 60,000+ 开源项目采用，30+ AI Coding Agent 兼容（包括 Cursor、Claude Code、Codex、Gemini CLI、Windsurf 等）。一个文件，所有 Agent 都能读。它就像"给 AI 看的 README"。

如何组织这些资料？

推荐的知识组织结构：

project/
├── AGENTS.md                    ← 项目指令文件（Agent 的"入职手册"）
├── docs/
│   ├── requirement.md           ← 需求文档
│   ├── architecture.md          ← 架构说明
│   ├── api-design.md            ← API 设计
│   ├── glossary.md              ← 术语表
│   └── references/              ← 参考资料
│       ├── sdk-guide.md         ← SDK 使用指南
│       ├── api-docs.md          ← 第三方 API 文档
│       └── design-patterns.md   ← 设计模式参考
├── .cursor/rules/               ← Cursor 规则（如使用 Cursor）
├── examples/                    ← 代码示例
│   ├── existing-pattern/        ← 已有代码模式示例
│   └── api-template/            ← API 模板示例
└── CLAUDE.md                    ← Claude Code 指令（如使用 Claude Code）

组织原则：

1. AGENTS.md 是地图，不是百科全书——只放 Agent 必须知道的核心信息，详细信息通过链接指向
2. 判断标准：如果 Agent 不知道这条信息就会写出错误的代码，放 AGENTS.md；如果只是写出不够好的代码，放详细文档，AGENTS.md 里放链接
3. 保持精简——AGENTS.md 建议控制在 50-200 行，过长的指令文件会浪费每轮对话的 token

官方理念引用："README.md 是给人看的，AGENTS.md 是给 AI 看的。AGENTS.md 补充了 README 中不适合放但 Agent 需要的上下文：构建步骤、测试命令、编码约定。" —— agents.md 官方网站

✅ Checklist

•  所用技术的官方文档链接已收集
•  关键 API 文档已准备（内联或链接）
•  已有项目代码已整理或路径已明确
•  编码规范已准备
•  业务背景知识已整理
•  术语表（Glossary）已创建
•  资料已组织到项目目录中
•  AGENTS.md（或等效文件）已创建并精简

🏆 最佳实践

"给 Agent 做入职培训"：把 Agent 当作一个刚入职的、聪明但缺乏项目背景的工程师。你会给新同事准备什么资料？项目架构图、编码规范、开发环境搭建指南、业务术语表——这些就是 Agent 需要的知识准备。Princeton 研究显示，有 AGENTS.md 的项目比没有的，中位运行时间减少 28.6%，中位 token 消耗减少 16.6%。

⚠️ 常见错误

1. 只给链接不给内容：Agent 可能无法访问外部链接，或访问速度慢——关键信息应内联
2. 资料太分散：信息散落在多个位置，Agent 需要大量探索——应集中组织
3. 不标注版本：Agent 可能使用过时 API——明确标注所用版本
4. AGENTS.md 太长：把所有文档都塞进 AGENTS.md——应只放核心信息，详细内容用链接

🛠 推荐工具

工具	用途
AGENTS.md	跨工具标准的项目指令文件
MCP (Model Context Protocol)	连接外部知识源
项目 docs/ 目录	组织静态文档

---

第四部分：上下文准备（Context）

为什么 Agent 的上下文比 Prompt 更重要？

这是 2025-2026 年 AI Coding 领域最重要的认知转变：从 Prompt Engineering 到 Context Engineering。

Anthropic 官方对此的定义：

"Context engineering represents a fundamental shift in how we build with LLMs. As models become more capable, the challenge isn't just crafting the perfect prompt—it's thoughtfully curating what information enters the model's limited attention budget at each step. The guiding principle remains the same: find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome."

—— Anthropic, Effective Context Engineering for AI Agents

Martin Fowler 也专门撰文讨论了 coding agent 的 context engineering。核心观点是：

1. Prompt 是一次性的，Context 是持续的——Prompt 只在一条消息中生效，Context 贯穿整个会话
2. Context window 是有限资源——用完即降级，研究显示存在"context rot"现象：随着上下文 token 增加，模型准确召回信息的能力下降
3. 最好的 prompt 工程师不是在 prompt 里写得最漂亮的人，而是最善于控制 AI 获得什么信息的人

Prompt Engineering vs Context Engineering：

Prompt Engineering:
- 关注：单条消息怎么写
- 隐喻：写一封好邮件
- 局限：只在一条消息中生效
- 适用：简单、一次性任务

Context Engineering:
- 关注：Agent 全程能看到什么信息
- 隐喻：设计一个工作环境
- 优势：贯穿整个会话/项目
- 适用：复杂、持续性项目

哪些信息应该提前告诉 Agent？

1. 项目目录结构

Agent 需要知道项目的布局，才能正确地创建和修改文件：

告诉 Agent 目录结构的方式：

# 在 AGENTS.md 中：

## Project Structure
src/
  modules/        ← 业务模块
    auth/         ← 认证模块
    user/         ← 用户模块
  shared/         ← 共享代码
    utils/        ← 工具函数
    types/        ← 类型定义
  config/         ← 配置文件
  tests/          ← 测试文件

最佳实践：将目录映射到职责。/src/api/ contains route handlers (thin, delegate to services). /src/services/ contains business logic.—— 不只是列出目录，还要说明每个目录的职责和规则。

2. 已有代码

Agent 需要知道项目中已有的代码模式和风格：

告诉 Agent 已有代码的方式：

1. 在 AGENTS.md 中引用示例文件
   "参考 src/modules/auth/auth.service.ts 了解 Service 层的写法"

2. 提供代码模板
   在 examples/ 目录中放置标准代码模板

3. 在 Prompt 中使用 @引用
   "参考 @src/shared/utils/response.ts 的返回格式"

3. 技术限制

Agent 需要知道项目的技术约束：

技术限制清单：
- 使用的技术栈及版本
- 不能使用的技术（已知不兼容/不安全的）
- 必须使用的特定 API 或方法
- 依赖版本锁定
- 运行环境限制（OS / Runtime 版本）

4. 开发规范

Agent 需要知道团队的编码规范：

开发规范清单：
- 代码风格（命名/缩进/格式化）
- 架构分层规则（哪层能调哪层）
- 错误处理规范
- 日志规范
- 注释规范
- 测试规范

5. 编码风格

告诉 Agent 编码风格的方式：

❌ 模糊："写干净的代码"——这种规则会被忽略

✅ 具体：
- "使用命名导出，不使用默认导出"
- "所有异步函数使用 async/await，不使用 .then()"
- "错误统一抛出 BusinessException，不使用原生 Error"
- "每个函数必须有类型标注"

社区经验："模糊的规则如'写干净的代码'会被忽略。描述具体模式的规则效果更好。告诉 Agent 在什么情况下做什么，而不是抽象原则。规则越具体，执行越可靠。" —— Cursor 社区

6. 团队规范

团队规范清单：
- Git 分支命名规则
- Commit message 格式
- PR 规范
- Code Review 流程
- 文档更新规则

7. 已有设计

Agent 需要知道已有的设计决策：

已有设计清单：
- 架构设计文档
- 数据库设计
- API 设计
- UI/UX 设计
- 已确定的技术选型

8. 历史决策

这是最容易被遗漏的。Agent 需要知道"为什么这么做"，而不仅仅是"做了什么"：

历史决策记录格式（ADR - Architecture Decision Record）：

## ADR-001: 使用 JWT 而非 Session

### Context
需要无状态认证，支持水平扩展

### Decision
使用 JWT 进行认证

### Consequences
- 优点：无状态，易于水平扩展
- 缺点：Token 撤销需要额外机制（黑名单）
- 约束：密钥必须安全存储

官方理念引用："Structured note-taking, or agentic memory, is a technique where the agent regularly writes notes persisted to memory outside of the context window. This strategy provides persistent memory with minimal overhead. This simple pattern allows the agent to track progress across complex tasks, maintaining critical context and dependencies that would otherwise be lost across dozens of tool calls." —— Anthropic, Effective Context Engineering

有哪些内容不应该遗漏？

以下是最容易遗漏但最不应该遗漏的上下文信息：

遗漏项	后果	重要性
构建命令	Agent 不知道怎么构建项目	⭐⭐⭐⭐⭐
测试命令	Agent 不知道怎么验证代码	⭐⭐⭐⭐⭐
已有代码模式	Agent 发明新的写法，与项目不一致	⭐⭐⭐⭐⭐
不能碰的文件	Agent 修改了不该碰的文件	⭐⭐⭐⭐
架构分层规则	Agent 跨层调用，破坏架构	⭐⭐⭐⭐
错误处理模式	Agent 用自己的方式处理错误	⭐⭐⭐⭐
历史决策原因	Agent "改进"了不应改的设计	⭐⭐⭐
业务术语	Agent 使用错误的术语	⭐⭐⭐

AGENTS.md 标准建议："Start with 20 to 30 lines covering the information agents most often get wrong. Add sections based on real agent mistakes, not hypothetical ones." —— 从 20-30 行开始，覆盖 Agent 最常犯的错误。基于实际错误而非假设来添加内容。

✅ Checklist

•  项目目录结构已写入 AGENTS.md（含每个目录的职责）
•  已有代码模式已提供（通过示例文件或引用）
•  技术限制已明确（技术栈/版本/禁用项）
•  开发规范已整理（代码风格/架构规则/错误处理）
•  编码风格规则具体且可执行（非"写干净代码"）
•  团队规范已明确（Git/Commit/PR 规范）
•  已有设计文档已准备
•  历史决策已记录（ADR 格式）
•  AGENTS.md 已精简至 50-200 行

🏆 最佳实践

"三层上下文管理"：

1. 持久层（AGENTS.md / 规则文件）：每次会话自动加载——放项目全局知识
2. 会话层（当前对话）：手动提供——放当前任务相关信息
3. 临时层（@引用）：按需引用——放特定文件/文档

"filesystem as memory"：Anthropic 提出将文件系统作为 Agent 的记忆。Agent 将进度写入 NOTES.md / TODO.md，在上下文重置后重新读取——这实现了跨会话的持久记忆。

⚠️ 常见错误

1. 上下文塞太多：把整个仓库、无关文件全放进上下文——浪费 token，降低质量
2. 不区分层级：所有信息都塞进 AGENTS.md——每轮对话都浪费 token 加载不相关内容
3. 不清理上下文：长会话不 /clear——context rot 导致质量下降
4. 只给描述不给示例：用文字描述代码模式——不如直接给一个示例文件

🛠 推荐工具

工具	用途
AGENTS.md / CLAUDE.md	持久上下文
.cursor/rules/	条件上下文
NOTES.md / TODO.md	进度追踪（agentic memory）
MCP	外部知识源连接

---

第五部分：约束（Constraints）

开始开发前应该告诉 Agent 哪些限制？

约束是 Agent 的"护栏"。没有约束的 Agent 就像没有车道线的公路——每个人都在自由发挥，但结果是混乱。

Anthropic 在 Effective Harnesses for Long-Running Agents 中强调：长时间运行的 Agent 需要明确的"工作约束（harness）"，就像轮班工程师需要工作制度一样。

约束清单

1. 文件级约束

文件级约束模板：

## 不可修改的文件
- 配置文件：config/production.json（生产配置不可改）
- 生成文件：generated/（自动生成的代码不可改）
- 第三方代码：vendor/（第三方库不可改）
- 迁移文件：已执行的数据库迁移不可修改

## 不可删除的目录
- .git/
- node_modules/（或等效依赖目录）
- docs/（文档目录）
- tests/（测试目录）

## 创建文件的位置规则
- 新模块放在 src/modules/ 下
- 新测试放在 tests/ 下
- 新文档放在 docs/ 下
- 配置文件放在 config/ 下

2. 规范级约束

规范级约束模板：

## 必须遵循的规范
- 编码规范：参考 docs/coding-standards.md
- API 设计规范：参考 docs/api-design.md
- 数据库设计规范：参考 docs/db-design.md
- 安全规范：参考 docs/security.md

## 架构约束
- [层] 不能直接调用 [层]（如 Controller 不能直接调 Repository）
- 所有外部调用必须经过 [层]（如所有 DB 操作必须经过 Repository 层）
- 错误处理必须使用 [模式]（如统一异常处理器）

3. API 级约束

API 级约束模板：

## 必须使用的 API
- HTTP 请求必须使用项目已封装的 httpClient
- 日志必须使用项目已封装的 logger
- 缓存必须使用项目已封装的 cacheClient

## 不能使用的 API
- 不允许直接使用 fetch / axios（使用封装层）
- 不允许使用 console.log（使用 logger）
- 不允许使用原生 JSON.parse 处理用户输入（使用安全解析）

4. 版本级约束

版本级约束模板：

## 版本锁定
- 语言版本：[如 Python 3.12 / Node.js 22]
- 框架版本：[如 Next.js 15 / Spring Boot 3.x]
- 数据库版本：[如 PostgreSQL 16]

## 不能升级的依赖
- [依赖名] 锁定在 [版本]（原因：[兼容性问题]）

## 不能引入的新依赖
- 不允许引入新的 ORM（已使用 [现有 ORM]）
- 不允许引入新的状态管理库（已使用 [现有库]）
- 如需引入新依赖，必须先询问确认

5. 输出约束

输出约束模板：

## 代码输出要求
- 每个函数/方法必须有类型标注
- 公共 API 必须有文档注释
- 复杂逻辑必须有行内注释
- 不允许 TODO 注释（要么实现，要么不写）

## 文件输出要求
- 单文件不超过 [N] 行
- 单函数不超过 [N] 行
- 圈复杂度不超过 [N]

## 格式约束
- 缩进：[2空格 / 4空格 / Tab]
- 引号：[单引号 / 双引号]
- 行尾：[有分号 / 无分号]
- 换行：[LF / CRLF]

6. 代码质量约束

代码质量约束模板：

## 必须满足的质量标准
- 所有代码必须通过 Linter 检查
- 所有代码必须通过类型检查
- 所有公共函数必须有单元测试
- 测试覆盖率不低于 [N]%

## 安全约束
- 不允许硬编码密钥/密码
- 不允许使用 eval / exec
- 所有用户输入必须验证和清理
- SQL 必须使用参数化查询

7. 测试约束

测试约束模板：

## 测试要求
- 每个新功能必须有对应的测试
- Bug 修复必须附带回归测试
- 测试必须能独立运行（不依赖外部服务）
- 测试必须快速执行（单个测试 < 1秒）

## 测试命令
- 运行全部测试：[命令]
- 运行单个测试：[命令]
- 运行测试并生成覆盖率：[命令]

## 测试规范
- 测试文件命名：[*.test.ts / *_test.py / ...]
- 测试结构：Arrange-Act-Assert
- Mock 策略：[什么该 Mock / 什么不该 Mock]

约束的优先级

当约束之间冲突时，Agent 需要知道优先级：

约束优先级（从高到低）：

1. 安全约束（不可妥协）
   - 不硬编码密钥
   - 不执行未验证的用户输入
   - 不跳过认证/授权

2. 架构约束（强烈建议）
   - 分层规则
   - 模块边界

3. 规范约束（应该遵循）
   - 编码风格
   - 命名规范

4. 偏好约束（最好遵循）
   - 代码组织方式
   - 注释风格

✅ Checklist

•  不可修改的文件/目录已明确列出
•  不可删除的目录已明确列出
•  创建文件的位置规则已定义
•  架构约束已明确（分层规则、模块边界）
•  必须使用的 API 已列出
•  不能使用的 API 已列出
•  版本锁定已明确
•  不能引入的新依赖已列出
•  输出格式要求已定义
•  代码质量标准已定义
•  安全约束已定义
•  测试要求和命令已明确
•  约束优先级已定义

🏆 最佳实践

"约束要具体、可测试"："模糊的约束如'写干净的代码'会被忽略。描述具体模式的约束更有效。例如：'所有异步函数必须使用 async/await，不使用 .then()'。约束越具体，执行越可靠。"

"用 Hooks 强制执行"：Claude Code 支持 Hooks 机制——在特定事件（如工具使用后、代码修改后）自动执行 Shell 命令。可以用 Hooks 在每次代码修改后自动运行 Linter / Formatter / 测试，实现"确定性护栏"——不依赖 Agent 自觉，而是强制执行。

⚠️ 常见错误

1. 约束太模糊："写安全的代码"——Agent 不知道具体怎么做
2. 约束太多：列了几十条约束——Agent 记不住，反而忽略所有
3. 没有优先级：所有约束同等重要——Agent 在冲突时无法决策
4. 不强制执行：只写在文档里——Agent 可能不遵循，应该用 Hooks/CI 强制

🛠 推荐工具

工具	用途
AGENTS.md	写入约束
Hooks（如 Claude Code）	强制执行约束
CI/CD	自动检查约束
Linter / Formatter	代码质量约束
.editorconfig	格式约束

---

第六部分：规划（Planning）

为什么优秀 Agent 都建议先 Planning？

因为"直接写代码"是高风险、高返工成本的协作模式。

Claude Code 官方最佳实践的第一条建议就是："先研究，再规划，再实现"（Explore → Plan → Code）。

Cursor 官方 Agent Best Practices 的核心建议是："从规划开始"（Start with Planning）。来自芝加哥大学的研究发现，有经验的开发者更倾向于在生成代码之前先进行规划。规划会促使你更清晰地思考自己要构建的内容，并为 Agent 提供明确的目标去实现。

GitHub Copilot Cloud Agent 在 2026 年 4 月将协作顺序从"有问题 → 开工 → 提 PR"改为"先研究 → 先计划 → 再编码 → 最后决定是否进入 PR"。

为什么先 Planning？

不 Planning：
  需求 → 直接 Coding → 发现方向错 → 返工 → 再 Coding → 再发现错 → ...
  问题：每次返工都浪费大量 Token 和时间

先 Planning：
  需求 → Planning → 确认方案 → Coding → 验证 → 完成
  优势：方向在编码前已确认，返工概率大幅降低

核心原理：
  "在计划上投入一小时，可节省后续十小时的返工"
  —— Thoughtworks

官方理念引用："你能做出的最大改变，就是在编写代码之前先进行规划。" —— Cursor 官方 Agent Best Practices

什么时候应该先规划？

根据 Research-Plan-Implement Pattern 的指导，规划的必要性取决于任务复杂度：

任务复杂度决策矩阵：

任务复杂度        需要的阶段                      示例
─────────────────────────────────────────────────────────
极简单           Implement only                  加一个 null 检查
简单             Plan → Implement                修复已知根因的 Bug
中等             Plan → Implement                多文件功能开发
复杂             Research → Plan → Implement     陌生模块的多文件功能
极复杂           Research → Plan → Implement     跨系统重构
                → Verify → Re-plan

判断标准：

• 需要 Planning：改动 > 3 个文件、涉及不熟悉的模块、架构变更、需要做设计决策
• 可以跳过 Planning：能用一句话描述的改动、你完全理解的小修改

Claude Code 官方建议："当你可以用一句话描述 diff 时，跳过规划。" —— AgentPatterns.ai

什么时候可以直接 Coding？

可以直接 Coding 的条件（全部满足）：

✅ 改动范围 ≤ 2 个文件
✅ 你完全理解现有代码
✅ 不涉及架构决策
✅ 不涉及新的设计模式
✅ 改动可以用一句话描述
✅ 你有明确的预期输出

如果任何一条不满足 → 先 Planning

如何拆分任务？

任务拆分是 Planning 的核心。好的任务拆分让 Agent 能聚焦、能验证、能回退。

任务拆分示例：

如何控制一次任务的大小？

任务大小控制规则：

1. 文件数限制
   - 单次任务涉及文件 ≤ 5 个
   - 超过 5 个 → 拆分

2. 代码量限制
   - 单次任务生成代码 ≤ 300 行
   - 超过 300 行 → 拆分

3. 对话轮次限制
   - 单次任务对话 ≤ 10 轮
   - 超过 10 轮 → 上下文可能已退化，考虑 /clear 后开新会话

4. 时间限制
   - 单次任务 ≤ 30 分钟
   - 超过 30 分钟 → 可能任务太大或方向偏离

如何避免一个 Prompt 做几十件事情？

这是 AI Coding 中最常见的反模式——"Prompt 堆砌"。

避免 Prompt 堆砌的策略：

1. 一个 Prompt = 一个 Task
   - ❌ "帮我实现 CRUD、分页、搜索、排序、导出"
   - ✅ "帮我实现 CRUD 接口"

2. 用 Task 列表管理多任务
   - 在 TODO.md 中维护任务列表
   - 每次只让 Agent 执行一个 Task
   - 完成后标记，再执行下一个

3. 使用 Plan Mode
   - 先让 Agent 出方案（Plan Mode）
   - 确认方案后，再逐个 Task 执行
   - 方案中已包含任务拆分

4. 抵制"顺便做了"的冲动
   - Agent 说"我顺便也做了 XXX" → 检查是否需要
   - 不需要的 → 回退；需要的 → 下次单独做

社区经验："让 AI 先生成一个包含文件列表的 Markdown 文件，每行开头有 checkbox，然后让它逐个文件处理。每行开头有 checkbox 这一点很重要。" —— Cursor 社区

✅ Checklist

•  已判断任务是否需要 Planning（使用复杂度决策矩阵）
•  需要 Planning 的任务已进入 Plan Mode
•  任务已拆分为单一职责的子任务
•  每个子任务有明确的输入、输出和验证方式
•  任务依赖关系已明确
•  单次任务大小已控制（≤5 文件 / ≤300 行 / ≤10 轮对话）
•  任务列表已写入 TODO.md
•  每个 Task 完成后做 Git Commit

🏆 最佳实践

"Explore → Plan → Code 三步走"：先让 Agent 通读项目代码理解架构，再切到 Plan Mode 出方案，最后才在一个干净的上下文中高效执行。跳过任何一步，都是在给 Bug 埋种子。

"Plan Mode 用于 > 3 文件的改动"：Claude Code 社区建议，任何涉及 3 个以上文件的改动，都应该先进入 Plan Mode。

"Planning 和 Coding 分离"：用高性能模型做规划（需要推理能力），用快速模型做执行（需要编码速度）。这是 2025-2026 AI 驱动开发的黄金工作流。

⚠️ 常见错误

1. 跳过 Planning 直接 Coding：复杂任务不规划——方向偏离，大量返工
2. Plan 太详细：把每行代码都写进 Plan——浪费时间，限制了 Agent 的灵活性
3. Plan 后不确认就执行：Agent 出了 Plan 直接开始写——应该人工审查 Plan 后再执行
4. 任务拆分太细：每个任务只改一两行——频繁切换上下文，效率低下
5. 不写 TODO.md：任务列表只存在于对话中——新会话丢失上下文

🛠 推荐工具

工具	用途
Claude Code Plan Mode (Shift+Tab)	规划模式
Cursor Plan Mode	规划模式
TODO.md	任务列表追踪
Git Commit	任务检查点

---

第七部分：文档准备（Documentation）

开始开发前，推荐有哪些文档？

文档是 Agent 的"长期记忆"。在 AI Coding 时代，文档不仅是给人看的，更是给 Agent 看的。

文档清单

必须文档（P0 - 开发前必须完成）

文档	文件名	解决什么问题	Agent 如何利用
项目指令文件	AGENTS.md	Agent 的"入职手册"，每次会话自动读取	Agent 启动时自动加载，获取项目全局上下文
需求文档	docs/requirement.md	定义"做什么"和"不做什么"	Agent 参考需求理解任务范围和验收标准
架构文档	docs/architecture.md	定义"怎么组织"——模块划分、服务边界、数据流	Agent 参考架构确保代码符合设计
API 设计文档	docs/api-design.md	定义接口规范——路径、参数、响应格式	Agent 按规范生成 API 代码
任务列表	TODO.md	定义"先做什么后做什么"	Agent 按顺序执行任务，完成后标记
编码规范	docs/coding-standards.md	定义"代码怎么写"	Agent 遵循规范生成一致风格的代码

推荐文档（P1 - 开发前推荐完成）

文档	文件名	解决什么问题	Agent 如何利用
数据库设计	docs/database.md	定义数据模型、表结构、索引	Agent 按设计创建数据库结构
测试计划	docs/test-plan.md	定义测试策略和覆盖率要求	Agent 按计划编写测试
路线图	docs/roadmap.md	定义开发阶段和里程碑	Agent 了解当前所处阶段
风险评估	docs/risk.md	定义已知风险和应对措施	Agent 避免已知风险
术语表	docs/glossary.md	定义项目专有术语	Agent 使用正确术语
部署文档	docs/deployment.md	定义部署流程和环境配置	Agent 按文档生成部署配置

可选文档（P2 - 按需准备）

文档	文件名	解决什么问题
技术调研报告	docs/research.md	记录技术选型的调研过程和结论
技术选型文档	docs/tech-stack.md	记录技术选型决策和理由
决策记录	docs/adr/	记录架构决策的上下文、决策和后果
运行手册	docs/runbook.md	记录常见问题和处理方式

哪些是必须的？

必须的标准：如果 Agent 没有这份文档就会写出错误代码 → 必须；如果只是写出不够好的代码 → 推荐/可选。

最小必须文档集（6 份）：

1. AGENTS.md         ← Agent 的全局上下文
2. docs/requirement.md ← 需求定义
3. docs/architecture.md ← 架构设计
4. docs/api-design.md   ← API 规范
5. TODO.md              ← 任务列表
6. docs/coding-standards.md ← 编码规范

这些文档分别解决什么问题？

文档解决的问题矩阵：

问题                        → 解决文档
──────────────────────────────────────────────
Agent 不知道项目是什么       → AGENTS.md
Agent 不知道要做什么         → requirement.md
Agent 不知道怎么组织代码     → architecture.md
Agent 不知道接口怎么设计     → api-design.md
Agent 不知道先做什么         → TODO.md
Agent 不知道代码怎么写       → coding-standards.md
Agent 不知道数据怎么存       → database.md
Agent 不知道怎么测试         → test-plan.md
Agent 不知道项目术语         → glossary.md
Agent 不知道为什么这么设计   → adr/

Agent 如何利用这些文档？

Agent 利用文档的方式取决于文档的位置和格式：

AGENTS.md 标准格式

AGENTS.md 是 2025-2026 年最重要的 AI Coding 标准之一。它是跨工具的——一个文件，所有 Agent 都能读。

AGENTS.md 官方建议："Keep rules under 500 lines. Split large rules into multiple, composable rules. Provide concrete examples or referenced files. Avoid vague guidance. Write rules like clear internal docs." —— agents.md 官方文档

✅ Checklist

•  AGENTS.md 已创建（50-200 行，精简版）
•  docs/requirement.md 已完成
•  docs/architecture.md 已完成
•  docs/api-design.md 已完成
•  TODO.md 已创建
•  docs/coding-standards.md 已完成
•  P1 文档骨架已建立
•  文档已纳入 Git 版本控制
•  README.md 中含文档索引

🏆 最佳实践

"AGENTS.md 是地图，不是百科全书"：只放 Agent 必须知道的核心信息。判断标准：如果 AI 不知道这条信息就会写出错误的代码，放 AGENTS.md；如果只是写出不够好的代码，放详细文档，AGENTS.md 里放链接。

"从 20-30 行开始，基于实际错误增量完善"：不要一开始就写几百行。从最核心的信息开始，每当 Agent 犯了一个错误，就把对应的规则加进去。这样你的 AGENTS.md 每一条都是"血泪教训"，没有废话。

"文档是 Agent 的长期记忆"：Anthropic 提出"filesystem as memory"——将文件系统作为 Agent 的记忆。文档不只是给人看的，更是 Agent 跨会话保持上下文的机制。

⚠️ 常见错误

1. AGENTS.md 太长：把所有文档内容都塞进去——每轮对话浪费 token
2. AGENTS.md 太短：只写了项目名——Agent 缺乏必要上下文
3. 文档不更新：代码改了但文档没更新——Agent 基于过时信息工作
4. 文档只给人看：文档写得像论文——Agent 难以解析和理解
5. 不纳入 Git：文档只在本地——团队成员和 Agent 都无法获取

🛠 推荐工具

工具	用途
AGENTS.md	跨工具标准项目指令
GitHub Spec Kit	Spec-Driven Development 工具
OpenSpec	规格驱动开发工作流
Git	文档版本控制

---

第八部分：开发规则（Working Rules）

Agent 与人的协作规则有哪些？

AI Agent 不是" autonomous code generator"（自主代码生成器），而是"junior engineer that needs supervision"（需要监督的初级工程师）。协作规则的核心是：Human-in-the-loop——人始终在循环中。

谷歌工程负责人的建议："在激进地利用 AI 能力的同时，依然对最终产出的软件负全部责任。把 LLM 当成一个特别聪明、但很容易犯错的初级工程师。"

什么时候应该 Review？

Review 时机矩阵：

必须 Review                建议 Review               可选 Review
──────────────────────────────────────────────────────────────────
每次 AI 生成代码后          修改配置文件后             修改注释后
每次 AI 修改 3+ 文件后      修改测试代码后             修改文档后
每次 AI 修改安全相关代码后   修改 UI 组件后
每次 AI 修改数据库后        重构代码后
每次 AI 安装新依赖后
每次 AI 修改认证/授权逻辑后

Review 的三个层次：

三层 Review 体系：

Layer 1: AI 自审（Self-Review）
- Agent 完成后，自己检查代码
- Prompt: "检查你的代码是否有以下问题：类型安全/错误处理/安全漏洞/边界条件"
- 成本：低，但可靠性也低

Layer 2: AI 互审（Cross-Review）
- 用另一个 AI（或另一个会话）审查
- 不同模型有不同盲区，交叉审查能发现更多问题
- 成本：中，可靠性较高

Layer 3: 人工审查（Human Review）
- 人工逐行检查关键代码
- 重点关注：安全性/业务逻辑/架构一致性
- 成本：高，但不可省略

安全数据："AI code needs the same or more review rigor as human code. Only 55% of AI-generated code is secure. XSS vulnerabilities appear 86% of the time. SQL injection appears 20% of the time. Review as if reviewing a junior developer who thinks they are a senior." —— AI Blueprint Guide

什么时候应该 Commit？

这是 AI Coding 中最重要的版本控制实践——"Commit-Before-You-Prompt"规则。

Git Commit 时机规则：

原则：AI 动手前 = commit checkpoint

# ✅ 正确节奏（为 AI 协作设计的）
你的代码 → commit "feat: 基础结构"       ← 你的 checkpoint
让 AI 改 API → commit "ai: API 层"       ← AI 的 checkpoint
让 AI 改 Service → commit "ai: Service 层" ← AI 的 checkpoint
让 AI 改测试 → commit "ai: 测试更新"     ← AI 的 checkpoint

# 任何时候发现 AI 的改动有问题 → git revert <ai-commit>

# ❌ 错误节奏（为自己设计的）
写代码 30 分钟 → commit "WIP"
让 AI 改 6 个文件 → ...没有 commit
# 出问题 → 无法回退

Commit 策略三原则：

原则一：AI 动手前 = commit checkpoint
- 每次 AI 修改代码前，先 commit 当前状态
- 这样 AI 的改动可以精确回退

原则二：用前缀区分"你的"和"AI 的"commit
- 你自己写的：feat: / fix: / refactor:
- AI 帮你写的：ai: [功能] - [部分]
- 便于追踪和批量回退

原则三：AI 改动量大时，先 branch 再动手
- 改动 > 5 个文件 → 创建新分支
- 在分支上工作，验证通过后再合并
- 不通过 → 删除分支，零成本

什么时候应该停下来确认？

   - 修改范围不明确
   - 架构方案选择
   - 核心代码修改
   - 大规模变更

什么时候允许 Agent 自主决策？

   - 低风险代码
   - 已确定方案实现
   - 有项目规范约束

什么时候必须人工确认？

   - 数据库迁移
   - 安全代码
   - 删除操作
   - 生产环境操作

社区警告："The most dangerous vibecoding mistake is allowing an AI agent to execute database migrations directly against a live database without human review. Always generate migration files first, read them, then apply them manually." —— How to Vibecode Like a Pro (2026)

✅ Checklist

•  Review 时机已明确（三层 Review 体系）
•  Commit 策略已确定（Commit-Before-You-Prompt）
•  Commit 前缀规范已定义（区分人工和 AI）
•  必须停下来确认的场景已明确
•  Agent 自主决策范围已定义
•  必须人工确认的操作已列出
•  数据库迁移流程已定义（先生成后审查再执行）
•  安全相关代码的 Review 流程已建立

🏆 最佳实践

"把 AI 当初级工程师管理"：聪明但容易犯错。给明确的任务、明确的约束、明确的验收标准。完成后必须 Review。不盲信任何一段 AI 生成的代码。

"小步提交，频繁提交"：把 git commit 当作"存档点"。每完成一个小任务、通过一次测试，就做一笔干净的提交。大胆尝试 AI 建议的重构，但一旦发现跑偏，就回滚到上一个稳定点。

"用 git worktree 隔离并行 Agent"：如果团队多人同时用 Agent 跑任务，使用 git worktree 让每个 Agent 有独立的物理目录，共用 .git 仓库——避免互相踩踏。

⚠️ 常见错误

1. 不 Review 直接合并：AI 代码直接进主分支——引入安全漏洞和技术债
2. 不 Commit 就让 AI 改：AI 改了 10 个文件发现错了——无法回退
3. 让 AI 直接操作数据库：AI 直接执行 migration——可能导致数据丢失
4. 不区分 AI 和人工 commit：git log 混在一起——无法追踪 AI 改了什么
5. 过度信任 AI：觉得 AI 很自信就一定对——AI 的"自信"不等于"正确"

🛠 推荐工具

工具	用途
Git	版本控制和 checkpoint
Git Worktree	并行 Agent 隔离
CI/CD	自动化检查
AI 互审（不同模型）	交叉审查
Linter / Type Checker	自动质量检查

---

第九部分：Prompt 准备

一个好的开发 Prompt 应该包含哪些信息？

在 Context Engineering 时代，Prompt 不再是"怎么写一条消息"，而是"怎么设计一次交互"。

一个好的开发 Prompt 应该包含：

有哪些固定模板？

模板一：功能开发 Prompt

## 任务
[描述需要实现的功能]

## 背景
请先理解当前项目结构和已有实现：

项目说明：
@[项目说明文件]

相关代码：
@[相关文件路径]

## 功能需求
需要实现：

1. [需求1]
2. [需求2]
3. [需求3]

## 技术要求
请遵循：

1. 不破坏已有功能和接口兼容性
2. 优先复用项目已有组件、工具类和设计模式
3. 遵循当前项目代码规范
4. 对新增代码添加必要的注释
5. 考虑异常处理、边界情况和性能问题

## 实现要求

请按照以下步骤执行：

1. 先分析当前代码结构，说明实现方案
2. 列出需要修改和新增的文件
3. 说明每个文件的修改目的
4. 再开始编写代码

## 验收标准

完成后请检查：

- [ ] 功能是否满足需求
- [ ] 是否存在明显 Bug
- [ ] 是否影响已有功能
- [ ] 是否需要新增测试用例

模板二：Bug 修复 Prompt

## Bug 描述

当前问题：

[描述 Bug 现象]

出现位置：

@[文件路径]

复现步骤：

1. [步骤1]
2. [步骤2]
3. [步骤3]

预期结果：

[应该是什么效果]

实际结果：

[当前错误表现]

## 相关信息

错误日志：

模板三：代码审查 Prompt

## 审查目标
审查以下代码，重点关注：

1. 正确性：逻辑是否正确？边界条件是否处理？
2. 安全性：是否有安全漏洞？输入是否验证？
3. 性能：是否有性能问题？是否有不必要的计算？
4. 可维护性：代码是否清晰？命名是否合理？
5. 一致性：是否符合项目编码规范？

## 代码
@[文件路径]

## 项目规范
@[编码规范文件]

模板四：Plan Mode Prompt

## 任务
[描述要做什么]

## 要求
请先阅读以下文件了解项目：
- @[文件1]
- @[文件2]

然后制定一个实现计划，包括：
1. 需要修改/创建哪些文件
2. 每个文件的改动内容概述
3. 任务之间的依赖关系
4. 潜在风险和注意事项

不要写代码，只出计划。

有哪些反模式？

   - Prompt 无限膨胀
   - 缺少上下文
   - 一次任务过大
   - 缺少验收标准

为什么 Prompt 不应该越来越长？

   - 信息密度下降
   - Agent 理解成本增加
   - 难以维护

如何管理 Prompt？

   - 项目规则 → 指令文件
   - 高频任务 → Prompt 模板
   - 核心模板 → Git 管理

✅ Checklist

•  开发 Prompt 六要素模板已准备（任务/上下文/约束/输入/输出/验收）
•  常用 Prompt 模板已整理（功能开发/Bug 修复/代码审查/Plan Mode）
•  Prompt 反模式已了解并避免
•  Prompt 长度已控制（最小高信噪比原则）
•  持久化 Prompt 已放入项目指令文件
•  重要的 Prompt 模板已纳入 Git

🏆 最佳实践

"一个 Prompt = 一个 Task"：不要在一个 Prompt 中塞入多个任务。如果有多个任务，用 TODO.md 管理任务列表，一次执行一个。

"先让 Agent 出方案，确认后再执行"：对于复杂任务，先用 Plan Mode 让 Agent 出方案。审查方案后再执行——这比直接让 Agent 写代码再修改要高效得多。

"用示例代替描述"：与其用文字描述代码模式，不如直接给一个示例文件让 Agent 参考。Agent 从示例学习的效果远好于从描述学习。

⚠️ 常见错误

1. Prompt 越来越长：不断往 Prompt 里加内容——context rot 降低质量
2. 不提供示例：只用文字描述——Agent 理解偏差
3. 不设边界：不说"不要做什么"——Agent 自由发挥
4. 不写验收标准：不说"怎么算完成"——无限修改
5. Prompt 只存在于对话中：不沉淀为模板——下次又要从头写

🛠 推荐工具

工具	用途
Plan Mode	先规划再执行
AGENTS.md / Rules	持久化 Prompt
docs/prompts/	Prompt 模板管理
Git	Prompt 版本控制

---

第十部分：风险检查（Pre-flight Checklist）

正式开发之前，需要检查哪些内容？

以下是正式让 Agent 写第一行代码之前的完整检查清单。每一项都是"如果不检查可能导致后续大返工"的关键项。

---

《AI Agent 开发项目前置检查清单》

一、目标检查

•  项目目标已明确：能用一段话清晰描述项目要解决的问题
•  最终交付物已定义：知道最终要产出什么（应用/库/服务/API）
•  成功标准可验证：有明确的、可验证的完成标准
•  MVP 范围已确定：知道最小可行版本包含什么
•  In-Scope 列表已完成：明确列出要做的事情
•  Out-of-Scope 列表已完成：明确列出不做的事情
•  "不需要做什么"已写入项目指令：Agent 能看到 Out-of-Scope

二、需求检查

•  需求已结构化：从"脑中想法"转化为"结构化文档"
•  功能列表已完成：每个功能有输入、输出、验收标准
•  非功能需求已量化：性能/安全/可用性有具体指标
•  边界条件已描述：异常情况和边界 case 已考虑
•  需求文档通过"陌生人测试"：不懂项目的人能看懂
•  需求已写入 docs/requirement.md

三、知识检查

•  官方文档已收集：所用技术的官方文档链接已整理
•  API 文档已准备：关键 API 文档已内联或链接
•  已有代码已整理：代码仓库/路径已明确，关键模式已标注
•  编码规范已准备：代码风格、架构规则、命名规范已整理
•  业务背景已整理：领域知识和业务规则已文档化
•  术语表已创建：项目专有术语已定义
•  资料已组织到项目目录：docs/ 目录已建立

四、上下文检查

•  AGENTS.md 已创建：包含项目概述、构建命令、目录结构、编码风格、规则
•  AGENTS.md 已精简：控制在 50-200 行，只放必要信息
•  目录结构已写入 AGENTS.md：每个目录有职责说明
•  已有代码模式已提供：通过示例文件或引用
•  技术限制已明确：技术栈、版本、禁用项
•  编码风格规则具体可执行：非"写干净代码"这种模糊描述
•  历史决策已记录：重要设计决策有 ADR 记录

五、约束检查

•  不可修改的文件已列出：Agent 知道不能碰什么
•  不可删除的目录已列出
•  文件创建位置规则已定义
•  架构约束已明确：分层规则、模块边界
•  必须使用的 API 已列出
•  不能使用的 API 已列出
•  版本锁定已明确
•  不能引入的新依赖已列出
•  安全约束已定义：不硬编码密钥、验证输入、参数化查询
•  测试约束已定义：测试要求、命令、Mock 策略
•  约束优先级已定义

六、规划检查

•  任务复杂度已评估：使用复杂度决策矩阵判断是否需要 Planning
•  需要 Planning 的任务已进入 Plan Mode
•  任务已拆分：每个 Task 单一职责、可验证、可回退
•  任务依赖关系已明确
•  任务大小已控制：≤5 文件 / ≤300 行 / ≤10 轮对话
•  TODO.md 已创建：任务列表已写入
•  Plan 已人工审查：确认方案后再执行

七、文档检查

•  AGENTS.md 已完成（P0）
•  docs/requirement.md 已完成（P0）
•  docs/architecture.md 已完成（P0）
•  docs/api-design.md 已完成（P0）
•  TODO.md 已创建（P0）
•  docs/coding-standards.md 已完成（P0）
•  P1 文档骨架已建立
•  文档已纳入 Git 版本控制
•  README.md 含文档索引

八、协作规则检查

•  Review 时机已明确：三层 Review 体系已建立
•  Commit 策略已确定：Commit-Before-You-Prompt 规则
•  Commit 前缀规范已定义：区分人工和 AI 的 commit
•  必须停下来确认的场景已明确
•  Agent 自主决策范围已定义
•  必须人工确认的操作已列出（数据库迁移/生产配置/安全代码/依赖安装/删除操作）

九、Prompt 检查

•  开发 Prompt 模板已准备：六要素模板
•  常用 Prompt 模板已整理：功能开发/Bug 修复/代码审查/Plan Mode
•  Prompt 反模式已了解
•  Prompt 长度已控制：最小高信噪比原则

十、环境检查

•  开发环境已就绪：所需工具已安装
•  版本控制已初始化：Git 仓库已创建
•  依赖管理已配置：包管理器已安装
•  Linter / Formatter 已配置
•  测试框架已配置
•  CI/CD 已配置（如适用）
•  .gitignore 已配置：排除敏感文件和无关目录
•  .editorconfig 已配置：统一编辑器格式

十一、安全检查

•  敏感信息不在代码中：密钥/密码使用环境变量
•  .env 已加入 .gitignore
•  Agent 无直接生产环境访问权限
•  数据库迁移需人工审查后执行
•  Agent 的文件操作权限已限制

---

检查清单使用方法

使用方法：

1. 打印或打开本检查清单
2. 逐项检查，完成的打 ✅
3. 未完成的项目：要么完成，要么明确标注"已接受风险"
4. 全部检查通过后，再开始让 Agent 写第一行代码
5. 开发过程中如发现新的前置条件，补充到检查清单中

原则：
- 宁可多检查，不可少检查
- 每一项都是"血泪教训"的总结
- 如果某项不适用于你的项目，标注"N/A"而非跳过

---

总结：为什么 AI Agent 项目的成功，很大程度取决于编码之前，而不是编码过程中

核心论点

"在计划上投入一小时，可节省后续十小时的返工。" —— Thoughtworks

"AI 是放大器。好的准备让 AI 如虎添翼，差的准备让 AI 雪上加霜。"

AI Agent 项目的成功，80% 取决于编码之前的准备工作。这不是夸张，而是 2025-2026 年 AI Coding 领域形成的共识。

为什么？

1. Context Engineering 决定了 Agent 的能力上限

Anthropic 官方的核心论点："最好的 prompt 工程师不是在 prompt 里写得最漂亮的人，而是最善于控制 AI 获得什么信息的人。"

Agent 的输出质量，不取决于你写了多好的 Prompt，而取决于 Agent 能看到什么信息。如果上下文是垃圾，再好的 Prompt 也只能产出垃圾。而上下文的准备，100% 是编码之前的工作。

输出质量 = f(上下文质量, Prompt 质量, 模型能力)

其中：
- 上下文质量：编码前准备 ← 权重最大
- Prompt 质量：编码时技巧 ← 权重中等
- 模型能力：你无法控制 ← 权重最小（现代模型差距不大）

2. Planning 消除了最大的返工源

研究表明，AI Coding 中最大的浪费不是"代码写错了"，而是"方向走偏了"。方向偏差的修复成本是代码错误的 10 倍——因为你需要回退、重新理解、重新生成。

Planning 在编码前确认方向，将方向偏差的风险降到最低。这就是为什么 Claude Code、Cursor、GitHub Copilot 都在 2025-2026 年将 Planning 提升为核心功能。

3. 约束防止了不可逆的破坏

AI Agent 可以在几秒钟内修改几十个文件。如果没有约束，一个错误的修改可能需要数小时来修复。约束是"护栏"——它不能让 Agent 更快，但能让 Agent 不犯致命错误。

没有约束的 Agent：
  快速生成 → 快速犯错 → 长时间修复 → 净效益为负

有约束的 Agent：
  稳定生成 → 少犯错 → 快速验证 → 净效益为正

4. 文档是跨会话的"长期记忆"

Agent 的上下文窗口是有限的——长会话会导致 context rot。文档是唯一可靠的跨会话记忆机制。

没有文档：每个新会话都从零开始，Agent 反复犯同样的错误。 有文档：新会话从文档恢复上下文，Agent 基于之前的成果继续工作。

Anthropic 官方："This simple pattern allows the agent to track progress across complex tasks, maintaining critical context and dependencies that would otherwise be lost across dozens of tool calls."

5. Spec-Driven Development 重新定义了"代码"的角色

2026 年，Spec-Driven Development（SDD）提出了一个颠覆性的观点："规范书才是最重要的工程产物"。

在 SDD 中，Spec 是 single source of truth。AI 按 Spec 生成代码，Review 对照的是 Spec 而不是凭感觉。这意味着——编码前准备的 Spec 文档，比编码过程中写的代码更重要。

数据支持

指标	数据	来源
有 AGENTS.md 的项目运行时间	减少 28.6%	Princeton 研究
有 AGENTS.md 的项目 token 消耗	减少 16.6%	Princeton 研究
AI 代码安全率	仅 55%	安全研究
调试 AI 代码比手写慢的比例	45%	Anthropic
遵循结构化实践后问题减少	显著下降	Anthropic
SDD 团队效率提升	5人7天完成20人数周工作	行业案例

从"Vibe Coding"到"Spec-Driven"

AI 编码的演进：

2023 年前    手动编码          → 人类写所有代码
2023-2024    AI 辅助编码       → AI 补全，人类主导
2025 年      Vibe Coding       → AI 生成，人类接受
2026 年      Spec-Driven       → 人类定义 Spec，AI 按 Spec 执行

趋势：
- 人的角色从"写代码"转向"写 Spec / 管 Agent"
- 价值从"编码速度"转向"准备质量"
- 核心能力从"Prompt Engineering"转向"Context Engineering"

最终建议

不要把 Agent 当成一个会写代码的工具，而应该把它当成一个需要被正确引导的协作者。

Vibe Coding 最大的变化，并不是让 AI 帮我们减少多少代码量，而是改变了软件开发中“思考”和“执行”的顺序。

过去我们更多关注如何写代码，而在 Agent 开发模式下，更重要的是如何定义问题、准备上下文、拆解任务、建立约束。

在开始让 Agent Coding 之前，花时间明确目标、整理资料、设计方案，看起来像是在降低开发速度，但实际上是在减少后期反复修改的成本。

一个好的 Agent 不缺少编码能力，真正缺少的是清晰的目标、完整的信息和合理的约束。

所以，Vibe Coding 的第一步不是打开编辑器，也不是输入 Prompt，而是先想清楚：

我要解决什么问题？Agent 需要知道什么？我应该提前准备什么？

当这些问题被回答之后，Coding 才真正开始。

---

参考来源

本指南综合参考了以下来源的官方理念和社区最佳实践：

1. Anthropic Engineering Blog - Effective Context Engineering for AI Agents (2025)
2. Anthropic Engineering Blog - Effective Harnesses for Long-Running Agents (2025)
3. Anthropic Engineering Blog - Claude Code: Best Practices for Agentic Coding (2025)
4. Cursor 官方 - Agent Best Practices: Start with Planning
5. AGENTS.md - 开放标准（60,000+ 开源项目采用，30+ Agent 兼容）
6. GitHub Spec Kit - Spec-Driven Development (2025)
7. AgentPatterns.ai - Research-Plan-Implement Pattern
8. Agentic Engineering Complete Guide - Plan → Execute → Verify (PEV) Framework (2026)
9. Martin Fowler - Coding Agent Context Engineering
10. GitHub Copilot Cloud Agent - Research, Plan, and Code (2026)
11. Princeton 研究 - AGENTS.md 对 Codex 性能的影响
12. Claude Code 社区 - 50+ 技巧总结 (2026)
13. 腾讯云开发者社区 - AI 协作 Git 工作流
14. AI Blueprint Guide - Working with AI Coding Tools Effectively
15. How to Vibecode Like a Pro - Best Practices in 2026