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

• 让 AI 修复一个 bug，结果它把不相关的代码也改了，最后还得手动回滚
• 写了一堆 prompt，AI 还是找不到正确的文件位置，只能靠"猜"
• 对话进行到一半，AI 开始遗忘之前的约束，输出质量断崖式下降

• AGENTS.md：项目级硬约束（红线、默认值、验收方式）
• docs/ai-playbook/index.md：一页式索引入口（高信噪比导航）
• docs/ai-playbook/code-map.md：代码地图（去哪改）
• docs/ai-playbook/flows.md：关键流程（怎么跑）
• docs/ai-playbook/collab-rules.md：协作规则 + 变更计划模板（怎么协作）

Step 0：先定义边界与 Done（不要从 prompt 开始）

1. 边界（Boundary）：哪些事永远不能做（隐私/架构红线、协议兼容、关键参数护栏）
2. 范围（Scope）：一次只做一个目标，禁止“顺手修复”
3. 验收（Done）：构建/测试/手测回归点，必须写出来

目标明确、单一主题、先交计划再动手；不得越过隐私/架构红线；完成必须可构建并列出回归点。

常见反模式：别踩这些坑

1. 直接让 AI "改代码"，不要计划
   • 后果：改了 10 个文件，最后发现方向错了，回滚成本巨大
   • 正确做法：先让 AI 输出变更计划，你批准后再动手
2. 把所有文档都塞给 AI
   • 后果：上下文爆炸，AI 反而抓不住重点（连"入口文件在哪"都找不到）
   • 正确做法：用 index + code-map 提供高信噪比导航
3. 让 AI "顺手优化"其他代码
   • 后果：一次 PR 混杂多个目标，code review 成本翻倍，出 bug 难回滚
   • 正确做法：单一主题，一次只解决一个明确目标

Step 1：写 AGENTS.md（项目级硬约束，强制稳定复用）

• 计划先行：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 — Repo Rules

最重要的原则

- Plan-first：任何改动先交变更计划，获批后再写代码
- Single-scope：一次只解决一个目标，禁止顺手修复
- Redlines：隐私/架构/协议/关键参数不得突破
- Docs-sync：涉及流程/入口/接口变更必须同步更新 playbook
- Validation：必须给出构建/测试/关键手测回归点

多语言支持

• 创建 AGENTS.zh-CN.md 和 AGENTS.en.md
• 每个协作者首次 clone 仓库后，根据语言选择创建符号链接：

  # 中文用户
  ln -s AGENTS.zh-CN.md AGENTS.md
  
  # 英文用户
  ln -s AGENTS.en.md AGENTS.md
  

• 在 .gitignore 中添加 AGENTS.md，避免符号链接冲突

核心洞察
AI 协作的本质不是"写更好的 prompt"，而是"把约束变成代码库的一部分"。AGENTS.md 让规则可复用，AI Playbook 让上下文可延续。

Step 2：写 docs/ai-playbook/index.md（高信噪比入口索引）

• 30 秒读完：只放"项目快照 + 链接索引"
• 一键跳转：把读者/AI 带到 code-map / flows / collab-rules

# 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 个候选文件，再深入读

常见需求定位

- 新增页面/SEO：frontend/app/\*\*/page.tsx + metadata.ts
- i18n 文案：frontend/constants/messages/\*
- 博客：frontend/content/blog/\* + frontend/lib/blog.ts

• 初版：让 AI 基于对整个代码库的理解，先做一次“目录 + 关键入口文件”的梳理，目标是帮助定位而不是追求完备。
• 迭代：把它当作活文档维护。每次有实质性改动时，让 AI 根据本次变更（PR/commit/文件清单）做增量更新，避免一次性重写。

Step 4：写 flows.md（怎么跑：关键流程 + 调试要点 + 微方案模板）

• 把时序与不变量写清楚，AI 就不需要"凭感觉改"
• 你可以把"历史上踩过的坑"压缩为调试要点，直接复用

1. 关键流程/时序（必要时给 Mermaid）
2. 调试要点（哪些日志/状态最关键）
3. 微方案模板（让 AI 先写计划再动手）

• 初版：让 AI 先复述“端到端流程 + 关键时序 + 不变量”，你负责校正（尤其是边界/红线/不变量），再把结果沉淀进文档。
• 迭代：同样按增量维护。每次流程/接口/时序变化，优先更新 flows，而不是让它慢慢过时。

Step 5：把“计划先行”工程化（计划 = 迷你设计文档）

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: <列出关键用例与回归点>

1. 读 playbook 的 index + code-map + flows（只读，不动代码）
2. 用自己的话复述现状与约束（你纠正一次）
3. 再产出变更计划（你批准后才允许写代码）

避坑指南
计划阶段先纠偏，避免写完再推倒重来；单一主题让回滚成本变低，合并也更容易。

Step 5.1：上下文续航（对话变长就"存档换对话"）

# 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 及时更新）

• 计划阶段先纠偏，避免写完再推倒重来
• 单一主题让回滚成本变低，合并也更容易
• flows 把历史坑浓缩成 checklist，减少重复踩坑

• 本 PR 是否包含变更计划链接/摘要？
• 是否更新了 docs/ai-playbook/*（如涉及入口/流程/接口）？

实战提示词样例

• 角色设定：明确 AI 的专业身份和责任范围，避免它"不知道该以什么标准输出"
• 任务启动：强制 AI 先读 playbook，避免凭空猜测
• 工作方式：把"计划先行"固化为工作流程，避免直接动手改代码

业界对照：OpenAI 如何用 Codex 组织冲刺（外部佐证）

• 把 agent 当“新入职的资深工程师”：能力强，但需要明确架构/规范/限制条件
• 规则要外化：他们提到在代码库中创建并维护大量 AGENTS.md 很实用
• 实质性变更先做计划：计划像微型设计文档，先调试计划再调试代码
• 上下文续航：当达到背景窗口限制时，把计划写入文件供下一次会话继续
• 多会话并行：更像在“管理一个团队”，而不是使用单一工具

可直接复制的最小目录结构

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

下一步行动

1. 立即开始：复制最小目录结构到你的项目，从 AGENTS.md 开始
2. 参考实现：访问 PrivyDrop GitHub，查看完整 AI Playbook
3. 给我反馈：如果这套方法对你有帮助（或踩坑了），欢迎在 GitHub 提 issue 或评论区交流
4. Star 支持：如果觉得有价值，给 PrivyDrop 一个 star 🌟

结语