![](/blog-assets/ai-collaboration-playbook.webp) 你是否遇到过这样的场景： - 让 AI 修复一个 bug，结果它把不相关的代码也改了，最后还得手动回滚 - 写了一堆 prompt，AI 还是找不到正确的文件位置，只能靠"猜" - 对话进行到一半，AI 开始遗忘之前的约束，输出质量断崖式下降如果你把 AI 当成"更快的搜索框"，这些问题不会暴露；但当你把 AI 当成"可协作的队友"时，这些问题会直接影响交付质量。本文会展示一套**可执行的工程化方法**，让 AI 协作从"玄学 prompt"变成**可复制的流程**。PrivyDrop 项目实践后，新增特性/修复 bug 的节奏明显更快、更稳——不是靠冒险，而是靠减少返工。你最终会得到一套可以直接复制进任意代码仓库的最小结构： - `AGENTS.md`：项目级硬约束（红线、默认值、验收方式） - `docs/ai-playbook/index.md`：一页式索引入口（高信噪比导航） - `docs/ai-playbook/code-map.md`：代码地图（去哪改） - `docs/ai-playbook/flows.md`：关键流程（怎么跑） - `docs/ai-playbook/collab-rules.md`：协作规则 + 变更计划模板（怎么协作）本文的所有示例都来自开源仓库 PrivyDrop，你可以直接对照实现： [**https://github.com/david-bai00/PrivyDrop**](https://github.com/david-bai00/PrivyDrop) 另外，最近 OpenAI 的一篇实践文章也有相似的方法论： [**https://openai.com/index/shipping-sora-for-android-with-codex/**](https://openai.com/index/shipping-sora-for-android-with-codex/) --- ## Step 0：先定义边界与 Done（不要从 prompt 开始）这一步只做一件事：把“什么是做完”写清楚，否则 AI 只会拼命让代码“跑起来”，而不是按你团队期望的方式“长期可维护地跑起来”。建议先定 3 类最小约束： 1. **边界（Boundary）**：哪些事永远不能做（隐私/架构红线、协议兼容、关键参数护栏） 2. **范围（Scope）**：一次只做一个目标，禁止“顺手修复” 3. **验收（Done）**：构建/测试/手测回归点，必须写出来可以把它们压缩成一句话，放在每次需求的开头： ```text 目标明确、单一主题、先交计划再动手；不得越过隐私/架构红线；完成必须可构建并列出回归点。 ``` --- ## 常见反模式：别踩这些坑在开始之前，先看看最常见的 3 个错误做法： 1. **直接让 AI "改代码"，不要计划** - 后果：改了 10 个文件，最后发现方向错了，回滚成本巨大 - 正确做法：先让 AI 输出变更计划，你批准后再动手 2. **把所有文档都塞给 AI** - 后果：上下文爆炸，AI 反而抓不住重点（连"入口文件在哪"都找不到） - 正确做法：用 index + code-map 提供高信噪比导航 3. **让 AI "顺手优化"其他代码** - 后果：一次 PR 混杂多个目标，code review 成本翻倍，出 bug 难回滚 - 正确做法：单一主题，一次只解决一个明确目标 --- ## Step 1：写 `AGENTS.md`（项目级硬约束，强制稳定复用）把 `AGENTS.md` 理解为：你团队“默认值”和“红线”的机器可读版本。它的作用不是解释原理，而是**在每次会话中都能被重复应用**。在 PrivyDrop 里，建议重点展示这 5 条（足够代表"工程协作约束"的核心）： - 计划先行：`AGENTS.zh-CN.md:7` - 单一主题：`AGENTS.zh-CN.md:8` - 隐私与架构红线：`AGENTS.zh-CN.md:9` - 文档同步：`AGENTS.zh-CN.md:12` - 验证要求：`AGENTS.zh-CN.md:13` 对应文件：[**AGENTS.zh-CN.md**](https://github.com/david-bai00/PrivyDrop/blob/main/AGENTS.zh-CN.md) 如果你想从零写一个最小版本，可以用下面这个结构（建议保持短、硬、可执行）： ```md # AGENTS — Repo Rules 最重要的原则 - Plan-first：任何改动先交变更计划，获批后再写代码 - Single-scope：一次只解决一个目标，禁止顺手修复 - Redlines：隐私/架构/协议/关键参数不得突破 - Docs-sync：涉及流程/入口/接口变更必须同步更新 playbook - Validation：必须给出构建/测试/关键手测回归点 ``` ### 多语言支持如果你的项目需要支持多语言协作（比如中英文团队），建议： - 创建 `AGENTS.zh-CN.md` 和 `AGENTS.en.md` - 每个协作者首次 clone 仓库后，根据语言选择创建符号链接： ```bash # 中文用户 ln -s AGENTS.zh-CN.md AGENTS.md # 英文用户 ln -s AGENTS.en.md AGENTS.md ``` - 在 `.gitignore` 中添加 `AGENTS.md`，避免符号链接冲突不同语言版本的 `AGENTS.md` 已经包含了各自语言的其他文档引用路径。 > **核心洞察** > AI 协作的本质不是"写更好的 prompt"，而是"把约束变成代码库的一部分"。AGENTS.md 让规则可复用，AI Playbook 让上下文可延续。 --- ## Step 2：写 `docs/ai-playbook/index.md`（高信噪比入口索引） AI 最常见的跑偏原因之一是：**不知道你家代码“入口在哪”**。这会导致它用“猜”的方式找文件、提方案。索引页要做到两件事： - 30 秒读完：只放"项目快照 + 链接索引" - 一键跳转：把读者/AI 带到 code-map / flows / collab-rules 参考实现：[**docs/ai-playbook/index.zh-CN.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/index.zh-CN.md) 最小模板（可直接复制）： ```md # AI Playbook — Index ## 项目快照 - 栈：Next.js / Node / ... - 红线：... ## 文档索引 - 代码地图：docs/ai-playbook/code-map.md - 关键流程：docs/ai-playbook/flows.md - 协作规则：docs/ai-playbook/collab-rules.md ``` --- ## Step 3：写 `code-map.md`（去哪改：入口文件 + 职责一句话）代码地图的目标是“快速定位”，不是“教你怎么改”。写法也很简单： - 只列关键目录与关键入口文件 - 每个入口文件只写一句话职责 - 看到需求时，先在 code-map 里命中 3–8 个候选文件，再深入读参考实现：[**docs/ai-playbook/code-map.zh-CN.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/code-map.zh-CN.md) 可选：也可以加一段“常见需求 → 入口文件”的速查表，进一步降低定位成本： ```md 常见需求定位 - 新增页面/SEO：frontend/app/\*\*/page.tsx + metadata.ts - i18n 文案：frontend/constants/messages/\* - 博客：frontend/content/blog/\* + frontend/lib/blog.ts ``` code-map 怎么生成（以及如何迭代）： - 初版：让 AI 基于对整个代码库的理解，先做一次“目录 + 关键入口文件”的梳理，目标是帮助定位而不是追求完备。 - 迭代：把它当作活文档维护。每次有实质性改动时，让 AI 根据本次变更（PR/commit/文件清单）做增量更新，避免一次性重写。 --- ## Step 4：写 `flows.md`（怎么跑：关键流程 + 调试要点 + 微方案模板）如果 code-map 解决“去哪改”，flows 解决的就是“怎么跑”。它对 AI 的价值非常大： - 把时序与不变量写清楚，AI 就不需要"凭感觉改" - 你可以把"历史上踩过的坑"压缩为调试要点，直接复用参考实现：[**docs/ai-playbook/flows.zh-CN.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/flows.zh-CN.md)（并拆分了深度阅读小节）建议至少包含三块内容： 1. **关键流程/时序**（必要时给 Mermaid） 2. **调试要点**（哪些日志/状态最关键） 3. **微方案模板**（让 AI 先写计划再动手） flows 怎么生成（以及如何迭代）： - 初版：让 AI 先复述“端到端流程 + 关键时序 + 不变量”，你负责校正（尤其是边界/红线/不变量），再把结果沉淀进文档。 - 迭代：同样按增量维护。每次流程/接口/时序变化，优先更新 flows，而不是让它慢慢过时。 --- ## Step 5：把“计划先行”工程化（计划 = 迷你设计文档）这是提速的关键：把评审从"读 diff"前移到"读计划"。建议在 `collab-rules.md` 里固化计划模板，并把它当成强约束。 PrivyDrop 的模板：[**docs/ai-playbook/collab-rules.zh-CN.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/collab-rules.zh-CN.md) 模板可以直接复用其中的结构（目标/范围/方案/风险/验收/回滚/验证）,参考如下: ```text Title: <简明标题> Goals - <预期达成的目标> Scope / Files - <将修改与新增的文件路径清单 + 原因> Approach - <实现思路与关键设计点> Risks & Mitigations - <主要风险> → <缓解策略> Acceptance Criteria - <可验证的验收项> Rollback - <如何快速回滚> Docs to Update - docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others? Validation - Build: next build - Manual: <列出关键用例与回归点> ``` 实践中更稳的做法是：让 AI 先做两步，再进入写计划阶段： 1. 读 playbook 的 index + code-map + flows（只读，不动代码） 2. 用自己的话复述现状与约束（你纠正一次） 3. 再产出变更计划（你批准后才允许写代码） > **避坑指南** > 计划阶段先纠偏，避免写完再推倒重来；单一主题让回滚成本变低，合并也更容易。 --- ## Step 5.1：上下文续航（对话变长就"存档换对话"）长任务进行到一半时，AI 输出质量下降几乎是必然的。可以把“续航”变成固定动作：当开始出现猜测、遗忘约束、跑偏时，先把当前状态写成一个文件，然后开新对话继续；或者先执行一次“压缩/总结（compress）”把上下文收敛，再继续推进。最小续航文档模板（建议放到 `docs/ai-playbook/handoff.md` 或临时文件里）： ```md # Handoff ## 问题定义（3–5 句） ## 已确认的计划（逐条） ## 已完成 / 未完成 ## 关键文件与入口 ## 红线与不变量 ## 验收与回归清单 ## 下一步 checklist ``` 这一步的目标不是“写漂亮文档”，而是把上下文从“对话窗口”转成“可被下一次会话稳定读取的文件”。 --- ## Step 6：形成协作闭环（像带新同事一样带 agent）当你把前面几步做完，协作会变成一种稳定的“流水线”： 1. 需求 → 约束（引用 `AGENTS.md`） 2. 定位 → 入口（引用 `index + code-map`） 3. 对齐 → 流程（引用 `flows`） 4. 计划 → 迷你设计文档（引用 `collab-rules` 模板） 5. 实现 → 小步单一主题（便于回滚） 6. 验证 → `next build` + 关键手测回归点 7. 同步 → 文档不落后（playbook 及时更新）我最直观的收益是：现在新增特性/修复 bug 的节奏明显更快、更稳。更重要的是，“快”不是靠冒险，而是靠**减少返工**： - 计划阶段先纠偏，避免写完再推倒重来 - 单一主题让回滚成本变低，合并也更容易 - flows 把历史坑浓缩成 checklist，减少重复踩坑需要加一道“门禁”时，可以把这两条写进 PR 模板： - 本 PR 是否包含变更计划链接/摘要？ - 是否更新了 `docs/ai-playbook/*`（如涉及入口/流程/接口）？ ## 实战提示词样例当你准备好 AI Playbook 后，可以用类似下面的提示词启动协作： --- **角色设定** 你是一名资深的 Next.js 全栈工程师，擅长全栈开发、重构优化、bug 定位修复，做了很多成功的在线产品。你的协作质量直接决定了这个开源项目能否长期稳定迭代，请发挥你的专业能力。 **任务启动** 请你阅读 `docs/ai-playbook/index.zh-CN.md` 了解项目背景、代码地图、协作规范等，现在有一个需求为"xxx"。 **工作方式** 请你深入阅读项目相关文档和代码，在充分理解的基础上，结合你丰富的经验和知识，请你系统性、周全的思考，多向我提问来澄清可疑点，然后输出分析结果和行动计划和我讨论，待我同意后实施。 --- **为什么这样写？** - **角色设定**：明确 AI 的专业身份和责任范围，避免它"不知道该以什么标准输出" - **任务启动**：强制 AI 先读 playbook，避免凭空猜测 - **工作方式**：把"计划先行"固化为工作流程，避免直接动手改代码 --- ## 业界对照：OpenAI 如何用 Codex 组织冲刺（外部佐证） OpenAI 在《我们如何使用 Codex 在 28 天内构建 Android 版 Sora》里总结了一套非常相似的工作模型： [**https://openai.com/index/shipping-sora-for-android-with-codex/**](https://openai.com/index/shipping-sora-for-android-with-codex/) 可以重点对齐这几个点（与本文的方法一一对应）： - 把 agent 当“新入职的资深工程师”：能力强，但需要明确架构/规范/限制条件 - 规则要外化：他们提到在代码库中创建并维护大量 `AGENTS.md` 很实用 - 实质性变更先做计划：计划像微型设计文档，先调试计划再调试代码 - 上下文续航：当达到背景窗口限制时，把计划写入文件供下一次会话继续 - 多会话并行：更像在“管理一个团队”，而不是使用单一工具虽然安卓开发与 web 开发领域不一样，但方法值得借鉴：**先把输入变好，输出自然会稳定**。 --- ## 可直接复制的最小目录结构 ```text AGENTS.zh-CN.md # 中文规则 AGENTS.en.md # 英文规则 AGENTS.md # 符号链接（git clone 后手动创建） docs/ ai-playbook/ index.zh-CN.md # 中文索引 index.md # 英文索引 code-map.zh-CN.md code-map.md flows.zh-CN.md flows.md collab-rules.zh-CN.md collab-rules.md ``` 如果你已经有文档但分散在各处：先做 index，把入口收束；然后再补 code-map/flows/模板即可。 --- ## 下一步行动 1. **立即开始**：复制最小目录结构到你的项目，从 `AGENTS.md` 开始 2. **参考实现**：访问 [**PrivyDrop GitHub**](https://github.com/david-bai00/PrivyDrop)，查看完整 AI Playbook 3. **给我反馈**：如果这套方法对你有帮助（或踩坑了），欢迎在 GitHub 提 issue 或评论区交流 4. **Star 支持**：如果觉得有价值，给 PrivyDrop 一个 star 🌟 --- ## 结语 AI 辅助开发不会减少严谨性要求，反而会增加。真正能把效率变成“可持续复利”的，不是更长的 prompt，而是更强的工程约束：规则外化、计划先行、流程固化、上下文续航。如果希望进一步工程化，这套方法也可以演进为“可复制的仓库脚手架”：包含 PR 模板、issue 模板，以及一份可直接用的 `AGENTS.md`/playbook 初始化内容。

标签: Codex

让 AI 不再跑偏：可落地的协作工程化方法（附模板）