我平时的开发极其依赖这些积攒下来的历史记录。我以前写 prompt 的方式比较原始，但是确实好用。之前的习惯是先去翻一下以前写得比较好、逻辑完备的提示词，把它们复制出来，再用 Codex 的 medium 推理模式结合当前代码需求生成一份个性化 prompt ，然后再切换到 high 或 xhigh 推理模式真正干活。当本地对话记录文件彻底蒸发之后，我以前很多常用的提示词也随着荡然无存了。
这次惨痛的教训让我意识到，把协作工作流只留在对话历史里是非常不安全的。这直接促使我加快开发了一套vibe coding 模板，不管以后是遇到 Codex 对话文件离奇丢失、GPT 账号突然被封号、重新开启一个完全陌生的小项目、还是入职新公司面对新的代码环境，通过复用这套 Agent 协作模板，就能快速搭建起一套非常高效的开发流水线。
这套模板主要解决什么问题
让 Agent 写出第一版代码通常不难，真正难的是长期协作。
项目一旦写久了，就会遇到很多重复问题：
vibe-coding-template 不绑定具体业务，也不替项目规定唯一开发方式。你可以把它当成一套可调整的 Agent 协作模板，复制到目标项目里，再按真实开发习惯慢慢改造为自己的工作流。
七个 skill 分别负责什么
agents-md-creator 负责生成或更新项目级 AGENTS.md。很多 Agent 协作问题，表面上是某次 prompt 没写好，实际原因是项目规则没有沉淀下来。每次都靠临时提醒，Agent 很容易忘记内容质量要求、测试方法、版本策略、修改报告记录格式、编码要求和错误处理边界。通过这个 skill 先把长期协作底线写清楚，比如代码质量如何控制、修改前必读文件、真实测试命令、版本和修改报告记录规则、错误处理原则、进度播报格式，以及不要无依据加入固定超时、长度截断等防御性编程的逻辑。
project-prompt-creator 处理一次性任务。它适合开发、修复、文档、验证，把本轮任务要做什么、先读什么、不能改什么、怎么测试、最后交付什么写成可执行 prompt 。
plan-mode-planner 用在方向不清、风险较高、需要用户先拍板决策的任务上。它解决的不是写代码能力，而是复杂任务开始前的决策顺序。很多任务失败，不是 Agent 不会写代码，而是它太早开始写代码。Plan mode 的作用是让 Agent 先慢下来，只做只读探索、阅读、搜索和静态分析，先提炼少数真正需要用户决策的问题，再进入实现。这样可以减少写完一大堆代码后发现方向错了的返工。
code-reviewer 用来生成 code review prompt 。它适合审查 diff 、PR 、指定文件、配置变更或发布前风险。它的重点是让 AI 基于真实 diff 、项目规则和证据发现问题，并给出可定位的证据、影响说明、修复方向和验证建议。
web-search 用来降低 Agent 的模型幻觉。任务依赖互联网最新信息、平台规则、论文、benchmark 、release notes 、官方 API 或技术选型时，不能只靠模型记忆下结论。它会优先使用官方文档、标准、供应商文档、官方 GitHub 、论文和 benchmark 官方页面，把来源差异整理成可追溯依据。更重要的是，检索结果最后要回到工程判断里，包括当前项目受不受影响、测试要不要覆盖真实环境等内容。
knowledge-explainer 解决的是另一类常见问题。Agent 写代码很快，但用户自己并不一定真正理解某个技术点。比如为什么数据处理流程要这样设计，为什么 benchmark 要用这种评测口径，为什么一个模型方法要拆成几个模块实现。如果这些问题没讲清楚，后续项目开发会越来越依赖 Agent 的输出，用户自己却越来越难判断代码或方案是否合理。这个 skill 适合用来做技术原理、从零教学、面试口述、项目追问和答辩准备。涉及最新资料时，再联动 web-search，先降低模型幻觉，再进入讲解。
设计哲学
agents-md-creator
AGENTS.md 的作用，是把那些长期有效、反复使用的规则固定下来。它应该回答几个核心问题：这个项目里 Agent 开始工作前必须知道什么？什么不能做？怎么验证？怎么汇报？
具体来说，AGENTS.md 需要包含这几类内容：
其中进度播报和禁止无依据防御性编程这两个约束，来自我真实踩坑的经历。
长任务里最难受的不是 Agent 做得慢，而是用户不知道它在做什么。它可能在读文件，也可能在跑测试，也可能已经卡在某个报错里，但如果中间没有反馈，整个过程就像黑箱。进度播报格式把执行过程拆成步骤、目的、执行命令、当前结果、证据路径和备注，让 Agent 的工作过程可观察、可追溯、可复盘。
防御性编程的问题更隐蔽。Agent 很喜欢主动加一些看似稳健的兜底逻辑，因为代码看起来没有报错，Agent 也不会主动告诉你它加了什么兜底。所以 AGENTS.md 必须明确写清楚：不要无依据加入防御性逻辑。如果确实要加限制，必须说明依据、触发条件、可见行为、误伤风险和验证方式。
AGENTS.md 的另一条重要原则是规定最小化修改的边界。默认做最小必要改动，但最小化修改不是盲目保守。如果只写最小化修改，Agent 很容易偷懒，把任务理解成只改小范围的几行代码，最后做出不符合真实用户需求、工业场景或业务实践的方案。更常见的问题是，两个平行功能本来应该保持一致，Agent 只在 A 里补了新设计，B 里却继续保留旧链路，后续维护会变得越来越割裂。所以需要明确：面向真实用户需求、解决反复未修复的 bug ，或者为了贴合真实业务实践时，可以允许更大范围重构。但大改前必须先说明根因、必要性、影响范围、回归方案和可回滚边界。
AGENTS.md 也不需要一次写到完美。更好的方式是随着项目推进，把真实踩过的坑、反复出现的偏差、已经验证过的工作流逐步沉淀进去。
web-search
这个 skill 的定位是降低 Agent 的模型幻觉。模型对热门前沿知识的记忆往往有偏差或过时。当任务依赖新版文档、平台规则、论文、benchmark 、API 或技术选型时，直接靠模型回答，Agent 给出的结论看起来很确定，但可能是错的。更麻烦的是，如果用户没有意识到这个结论有问题，后续开发和方案设计就会沿着错误方向推进，代价很大。
web-search 的核心设计是把检索结果和工程判断绑定在一起，而不是只给几个链接。它有一套明确的最小检索流程：
[ol]
[/ol]
输出结构也围绕工程判断设计：问题重述、检索关键词、核心发现（按来源类型分组）、结论分层、项目落地点、来源清单。如果检索服务于代码生成，还必须把结论转成工程约束：推荐用什么 API 或库、不推荐什么做法、当前项目的最小可行实现是什么、需要新增或更新哪些测试。
web-search 不会替代本地代码审查。正确的关系是：本地调用链分析 + 互联网最新信息 + 真实验证边界，三者一起定位问题。互联网最新信息最终要回到工程约束、测试要求、文档影响和风险边界。
knowledge-explainer
这个 skill 解决的是 vibe coding 过程中一个很容易被忽略的问题：Agent 写代码很快，但用户自己并没有完全理解某个技术点。
比如为什么数据处理流程要这样设计，为什么 benchmark 要用这种评测口径，为什么一个模型方法要拆成几个模块实现。如果这些问题没讲清楚，后续项目开发会越来越依赖 Agent 的输出，用户自己却越来越难判断方案或代码是否合理。
knowledge-explainer 的设计哲学，是把 Agent 的产出从用户能用推进到用户能理解、能判断。它不满足于解释一个名词或给出一段概念摘要，而是会把技术点放回当前项目里讲清楚：核心原理是什么，关键术语怎么理解，公式里的变量对应什么业务含义，评测指标为什么这样设计，工程实现为什么要做这些取舍。
它的优点在于能把一次讲解变成后续开发的判断依据。用户再遇到代码实现、模型选择或面试追问的相关问题时，不只是记住了一个结论，而是知道这个结论从哪里来、适用于什么场景、哪些地方还需要继续验证。
如何迁移到自己的项目里
我建议不要一上来就追求把整套模板直接照搬。首先更新一下根目录的AGENTS.md，下面是我的根目录的AGENTS.md。
# Codex 全局指令（长期生效）
## 1. 语言与表达
- 永远使用简体中文回复：包括说明、计划、总结、代码注释、README 修改建议、测试说明。
- 允许保留英文原文的场景仅限：代码、命令、报错、文件路径、域名、专有名词。
- 禁止输出英文小标题，如 Thoughts / Plan / Next steps ；统一使用中文标题。
- 如果误写了英文解释，必须立刻改写为中文。
## 3. 默认协作方式
- 优先做最小必要改动，避免无关重构；但最小不是盲目保守，若真实用户需求、反复未修复的 bug 、工业场景或业务实践要求更大范围调整，应先说明根因、必要性、影响范围、回归方案和可回滚边界。
- 先理解现有调用链、入口文件、依赖顺序，再动手修改。
- 发现风险时，先说明风险点，再给出能闭环真实问题的可行改法；不要为了追求局部最小而留下功能割裂或长期维护隐患。
- 输出尽量清晰、可复制、可执行，避免碎片化解释。
## 4. 进度播报格式
在执行命令、读写文件、测试页面、查看日志时，尽量输出简洁的中文进度块，格式如下：
> 🧩 步骤：{一句话描述正在做什么}
> 🎯 目的：{为什么要做}
> ▶️ 执行：{命令、页面、文件路径或操作}
> ✅ 结果：{当前状态}
> 🧾 证据：{可验证证据路径}
> 📝 备注：{可选；最多一句}
## 5. 默认协作风格
- 优先给出可直接落地的改法，不要空谈。
- 优先给出能闭环真实问题的可行方案；如果最小方案会导致功能割裂、不符合业务实践或留下反复返工风险，要明确说明并给出更合适的调整范围。
- 发现风险要明确指出，不要模糊带过。
- 不要为了省事而跳过测试。
- 不要把未验证写成已验证。
- 不要把推测写成事实；有证据就给证据，没证据就明确说明。
然后可以先用 agents-md-creator 生成一份项目 AGENTS.md。这份文件不用写得很长，核心是让 Agent 进入项目后先知道几件事：这个项目是什么，开始修改前必须看什么，哪些边界不能碰，怎么证明任务真的完成了。
我会优先写清楚这些内容：
这一步完成后，不要马上拿一个大任务测试。可以先挑一个低风险任务，比如改一小段文档、补一个局部测试、修一个很小的 bug 。
等项目继续推进，再慢慢补充 AGENTS.md 和 skill 。它们不需要一次写到完美。更好的方式是随着项目开发，把真实踩过的坑、反复出现的偏差、已经验证过的工作流一点点沉淀进去。每次更新最好对应一个具体问题，而不是凭空加原则。比如 Agent 曾经误改过某个代码，就把这个代码的处理方式写清楚；某次测试命令经常被漏跑，就把它放进任务验收要求。
后续可以按任务类型逐步使用其他 skill 。普通开发、修复、文档任务，用 project-prompt-creator 把一次性任务写清楚。方向不明确、影响范围比较大的任务，先用 plan-mode-planner 做只读探索和关键决策。代码改完后，用 code-reviewer 检查代码里的风险隐患。遇到官方文档、前沿技术等容易被模型幻觉影响的内容，就先用 web-search 建立依据。自己也没完全理解的技术点，再用 knowledge-explainer 先补齐技术原理。
这样迁移的好处是，模板不会变成一堆一次性文件，而是会逐渐变成项目自己的协作资产。对于开源项目来说，这些内容也能帮助后来参与的人更快理解这个项目应该怎么改、怎么测试、怎么 code review 。
总结
https://github.com/Philip-Cao-9527/code-note-helper/blob/main/vibe-coding-template 开发了一套把 Agent 协作变成可以复用、可以随着项目一起演进的工作流。
如果你也经常用 Codex 写项目，尤其是已经开始遇到上下文丢失、模型幻觉严重、喜欢防御性编程、反复 code review 找不到 bug 这些问题，可以把这套模板当成一个起点，按自己项目的真实内容和开发习惯慢慢迭代。觉得有用的话欢迎去 GitHub 仓库点个 star ，也欢迎在评论区交流自己 vibe coding 的经验心得！
