深色模式
24 · 反模式、FAQ 与术语表
长尾查阅件
📚 系列导航：这是《Agent 开发进阶》的第 24 篇（共 24 篇），收官篇。上一篇你交付了毕业项目，这一篇不教新东西——反模式、FAQ、术语表，一份日后随手翻的查阅件。延伸阅读：《06 Claude Code 进阶玩法》《07 Codex 进阶玩法》。
走到这里，正课讲完了。这一篇不必从头读到尾——它是查阅件：踩坑时来对反模式表，被人问住时翻 FAQ，团队黑话不齐时把术语表甩过去。压轴是我职业生涯最贵的一次翻车：一个跑了三个月才被发现的评测事故。这一篇只干一件事：把全课的坑、答疑和黑话浓缩成一页，供你随时回来对表。
看完这一篇，你会拿到：
- 12 条反模式速查表（症状/根因/解法）
- 高频 FAQ 的直给答案
- 21 条人话版术语表
- 一份评测集泄漏事故的时间线复盘
01 反模式 12 条
| 反模式 | 症状 | 根因 → 解法 |
|---|---|---|
| demo 驱动开发 | 演示挑最好一次 | 无基线 → 评测先行（19） |
| 框架崇拜 | 没懂循环就上框架 | 原理空心 → 先裸写（04） |
| 全自动执念 | 高危操作不过人 | 高估可靠性 → 审批分级（12） |
| 工具堆数量 | 接 20 个工具当能力 | 没测正确率 → 少而精（05） |
| 上下文囤积 | 什么都塞 system | 注意力稀释 → 分层注入（06） |
| 无熔断裸奔 | bug 空转烧一整夜 | 无上限 → 三件套（21） |
| 多 agent 起手式 | 上来就五个角色 | 复杂度虚荣 → 到天花板再拆（15） |
| 自然语言传话 | agent 间转述变形 | 无协议 → 结构化消息（17） |
| 无 trace 上线 | 出事靠猜复现 | 观测缺位 → trace 是门槛（20） |
| 评测集僵化 | 一年不更新照跑 | 脱离流量 → badcase 月更（19） |
| 同款模型自评 | 裁判分数虚高 | 自评自夸 → 裁判换家（19） |
| 安全事后补 | 上线后才想威胁 | 安全当补丁 → 威胁先行（21） |
💡 一句话总结：12 条的共性是跳过验证——大半解法都是把验证前置。
02 高频 FAQ
agent 和 chatbot 的界限？ 工具与循环——能调工具改变外部世界、按结果定下一步的才是 agent。 要不要等下一代模型？ 不等。工程债不会被模型升级偿还——评测、护栏、观测在任何模型上都值钱。 成功率多少能上线？ 看容错成本与降级设计：有人工兜底的 85% 可用，无兜底的 99% 也悬。 用框架还是裸写？ 学习期裸写懂原理，生产期看第 3 篇决策树，抽象层自己包一层。 多 agent 什么时候上？ 单 agent 摸到天花板、且收益覆盖通信与调试成本时——多数人远没到（15）。
💡 一句话总结：FAQ 的答案指向同一件事——先验证、有兜底，再扩张。
03 术语表：21 条人话版
循环与工具：agent 循环＝LLM+循环+工具；workflow 光谱＝固定流水线到自主循环的档位；工具 schema＝写给模型看的 API 说明书；结构化输出＝按 JSON 约定回话。 上下文与记忆：上下文窗口＝模型一次能看的上限；注意力稀释＝塞得越多每条越不被当回事；外置记忆＝该记的写进文件而非塞对话；RAG＝先检索再回答。 编排：编排者-工人＝派活汇总模式；handoff＝控制权整体移交；黑板模式＝共享公共状态板。 生产化：评测集＝带标准答案的考卷；轨迹评测＝还看过程步数与成本；LLM-as-judge＝模型当裁判（要换家）；trace＝每轮五要素轨迹；badcase 归因＝失败定位到轮与环节。 安全与成本：间接注入＝藏在数据里的指令攻击；数据非指令＝外部内容的隔离标记；权限最小化＝用不到的工具不挂；熔断＝token/费用/轮数硬上限；模型路由＝按难度分配模型；prompt cache＝稳定前缀只计一次。
💡 一句话总结：术语表的用途是团队对齐——立项会前过一遍，能省一半鸡同鸭讲。
04 完整翻车史：评测集泄漏进 prompt 的三个月
时间线：第 1 个月，成功率从 81% 跳到 92%，全组庆祝；第 2 个月，线上投诉率纹丝不动，我归因于"用户问题变难了"；第 3 个月，新同事重构 prompt 时发现——早前有人把 20 条评测样例连答案贴进了 prompt 当 few-shot。就像老师把期末考题连答案发给学生当复习资料：成绩单漂亮，学生什么都没学会。三条整改从此进规矩：评测集与 prompt 资产物理隔离；评测报告必附 prompt diff；成绩突然变好比变差更要查——变差你会追，变好你只会庆祝。
💡 一句话总结：评测的可信度先于分数——隔离、附 diff、异常上涨必查。
05 延伸路线
本课能力不止于做产品：《06 Claude Code 进阶玩法》《07 Codex 进阶玩法》把工具设计、上下文工程、编排反过来用在开发提效——你现在是能"驯服"coding agent 的人。要配更强外挂大脑，回《04 知识库开发入门》。
💡 一句话总结：下一站不是更大的 agent，是把能力反哺进你的工作流。
06 动手：全课自查
任务：① 拿 01 节的 12 条反模式逐条对照你的 agent 项目，命中就记一条整改项；② 按"影响 × 修复成本"排序；③ 输出整改 roadmap：命中条数、前 3 优先项、各自对应回看的篇目。
验收标准：一份整改 roadmap——命中清单 + 优先级排序 + 篇目索引，能直接当下个迭代的排期输入。
两种结果都正常：命中 ≤3 条——状态很好，设季度提醒复查；命中过半——很正常（我第一次自查命中 7 条），先修"评测缺位"和"无熔断"两条保命项，其余按排期来。
07 小结：收官
你现在应该能：手写 agent 循环、设计高质量工具、管理上下文预算、拿到结构化输出、装上规划记忆与知识库、设计审批门、对多 agent 做用/不用判断，并交付一个可评测、可观测、有护栏、成本可控的生产级 Agent。
课程到此收官。下一站《06 Claude Code 进阶玩法》《07 Codex 进阶玩法》：把这身本事反哺给你的开发效率。恭喜毕业。
📎 实战案例
某团队争论「要不要等下一代模型」。老工程师：不等——工程债不会被模型升级偿还，评测、护栏、观测在任何模型上都值钱。他们把 12 条反模式做成立项自检表，一年拦下 3 个「demo 驱动开发」式立项。
踩坑
- 评测样例连答案泄漏进 prompt，虚高的 92% 我们跑了 3 个月才发现——成绩突然变好比变差更要查。
- 我第一次拿反模式表自查，12 条命中 7 条——命中过半很正常，先修评测缺位和无熔断两条保命项。
- 我曾把术语表当装饰，半年后发现团队里「评测」一词有 3 种理解——立项会前对齐术语，能省一半鸡同鸭讲。