Agent 工程化避坑指南——从实践看常见反模式

一、引言：为什么 Agent 工程化容易踩坑？

最近和几个做 Agent 开发的朋友聊了聊，发现一个有趣的现象：大家都在用 Agent，但很多人用不好。更常见的情况是：换了更贵、更强的模型，效果却没有明显提升；或者某个 Agent 本来跑得好好的，突然就开始出问题，修来修去也没找到根本原因。

这篇文章基于原文作者的实践总结，聚焦 Agent 工程化里最容易被忽视、但影响最大的几个方面。读完你会发现：很多时候问题不在模型能力，而在工程约束没立住。

简单说，本文要讲三件事：

八大常见反模式：哪些坑最常踩，怎么避开
五条黄金顺序：从零开始时应该按什么顺序建设
十个核心原则：形成可落地的行动清单

二、八大常见反模式与解决方案

1. 系统提示当知识库

问题表现：随着项目发展，系统提示越来越长，把所有知识、规范、教程都塞进去。一开始还好，越往后越不对劲：Agent 开始忽略一些规则，或者做出莫名其妙的决策。

后果：这就是典型的 Context Rot ------ 关键信号被噪声稀释了。Transformer 的注意力复杂度是 O(n²)，上下文越长，真正重要的信息越难被注意到。

解决方案：核心思路是分层管理，不要把所有东西都塞进系统提示。

分层管理：
- 常驻层：身份定义、项目约定、绝对禁止项，保持短、硬、可执行
- 按需加载：Skills 和领域知识，描述符常驻，完整内容触发时注入
- 运行时注入：当前时间、渠道 ID 等动态信息，每轮按需拼入
- 记忆层：跨会话经验写入 MEMORY.md，需要时才读取
Skills 按需加载 ：

系统提示只保留索引，完整知识按需加载。

以下代码展示了系统提示中 Skills 索引的写法：

javascript 复制代码

const systemPrompt = `
可用 Skills：
- deploy: 部署到生产环境的完整流程
- code-review: 代码审查检查清单
- git-workflow: 分支策略和 PR 规范
`;

Skill 描述要包含反例，否则路由准确率会从 85% 掉到 53%。有效的描述符是"何时该用我"，不是"我能做什么"。

实践方案：Obsidian + LLM Wiki
用 Obsidian 作为外部知识库，所有文档、规范、教程都存放在这里，通过 LLM 进行语义检索，按需查询相关内容。Agent 只需要描述"何时查询"，而不是把所有知识都塞进上下文。
方案缺点：需要额外的时间维护多版本的文档，并且定时清理维护结构也是一大耗时，随着文档数量增多，耗时会线性增长。
关键要点：系统提示应该保持短而稳定，只放必须的内容。

2. 工具数量失控

问题表现：工具越来越多，Agent 频繁选错工具或参数。有时候一个任务明明可以用一个工具完成，Agent 却调用了多个不相关的工具。

后果：工具定义本身会吃掉大量 token（仅 5 个 MCP 服务器就可能带来约 55,000 tokens 的工具定义开销），模型注意力被稀释，选择准确率下降。

解决方案：核心是 ACI（Agent-Computer Interface）原则。

什么是 ACI？

工具应该对应 Agent 的目标，而不是底层 API 操作。不要为每个 API endpoint 都建一个工具，而是让一个工具对应一个完整的目标动作。

以下对比了传统的 API 封装方式（差的做法）和符合 ACI 原则的设计方式（好的做法）：

javascript 复制代码

// 差的做法：粒度过细，Agent 需要协调多个工具
get_post(id)
update_content(id, content)
update_title(id, title)

// 好的做法：ACI 原则，面向 Agent 目标
update_yuque_post(post_id, title, content_markdown)

工具描述要说明"何时用、何时不用"，并给出调用示例。调试时优先检查工具描述，而不是先怀疑模型能力。

关键要点：工具质量 > 工具数量，5 个设计良好的工具优于 50 个粗糙的 API 封装。

3. 缺少验证机制

问题表现：Agent 声称"任务完成"，但没有可执行的验证标准。你说他完成了，怎么证明？你说他没完成，怎么判断？

后果：无法判断实际效果，改了也不知道是变好还是变坏。只能靠"感觉"判断优化效果，这本身就是问题。

解决方案：每类任务绑定可执行的验收标准。

代码评分器：字符串匹配、单元测试 pass/fail、结构比对、工具调用参数验证
模型评分器：按评分标准打分、两个答案对比选优、多个模型投票取共识
人工评分器：专家抽样审查、标注队列校准

优先级：代码评分器 > 模型评分器 > 人工评分器。

从第一个真实失败案例就开始建立评测体系，不要等积累了足够多案例再开始。

关键要点：没有验证机制，Agent 的成功与否只能靠"感觉"，这是不行的。

4. 多 Agent 无边界

问题表现：多个 Agent 之间没有明确隔离和协议，状态互相污染。出了问题不知道是哪个 Agent 出的错，也不知道该怎么修。

后果：故障归因困难，协作开销大于并行收益。多 Agent 的价值在于产出可持久化工件（PR、分支），而不是同时跑多个模型。

解决方案：明确边界，协议先行。

明确角色和权限：每个 Agent 有清晰的职责边界
Worktree 隔离：文件修改互相隔离，避免冲突
设置 maxTurns：防止单个 Agent 无限递归
协议先于协作：定义好通信协议（JSONL inbox）、任务图、依赖关系

子 Agent 只回传摘要，搜索和调试细节留在自己的上下文里。主 Agent 真正需要的只是结论。

关键要点：多 Agent 不是银弹，先有任务图和隔离边界再引入并行。

5. 记忆不整合

问题表现：长对话进行到第 20 轮后，Agent 决策质量明显下降。开始遗忘之前的约束，或者重复已经做过的操作。

后果：上下文窗口耗尽，早期重要信息被压缩掉，包括架构决策、约束理由、失败路径。

解决方案：监控 token 占用，超过阈值自动触发整合。

压缩时定义保留优先级：
1. 架构决策，不得摘要
2. 已修改文件和关键变更
3. 验证状态，pass/fail
4. 未解决的 TODO 和回滚笔记
5. 工具输出，可删，只保留 pass/fail 结论
压缩可回退：原始消息写入 archive/，避免整合失败丢失上下文
MEMORY.md + 按需检索：Agent 主动写入重要事实，需要时检索
实践方案：TencentDB-Agent-Memory

腾讯云的 Agent 记忆管理方案，支持结构化记忆存储与检索，替代手动维护 MEMORY.md。适合需要更强大记忆管理的场景。

关键要点：第 20 轮对话前必须建立记忆整合机制，否则长任务必垮。

6. 没有评测

问题表现：改了 Prompt 或换了模型，不知道是否变好还是变坏。只能凭感觉，或者看几个手动测试案例。

后果：可能引入回归而不自知。优化了半天，结果在其他场景变差了都不知道。

解决方案：从第一个真实失败案例立刻转成测试用例。

区分两个指标：

Pass@k：k 次至少一次正确 ------ 验证"理论上能不能做到"
Pass^k：k 次全部正确 ------ 验证"有没有被改坏"

评测系统先于 Agent 优化。看到评测分数下降，先查评测系统本身是否有问题：运行环境资源不足、评分器 bug、测试用例和生产场景脱节、只看聚合分数而漏掉某一类任务系统性变差。

关键要点：评测是判断"有没有变好"的唯一客观依据。

补充：个人可以简单使用交叉验证代替繁琐的评测，很多团队其实并没有资源建立完整的评测系统。

7. 过早引入多 Agent

问题表现：单 Agent 还没验证上限，就直接上多 Agent 并行。以为能提升效率，结果反而更复杂。

后果：协调复杂度过高，协作开销超过并行收益。

解决方案：先建任务图，验证单 Agent 上限后再扩展。

先建任务图：明确任务拆分和依赖关系
验证单 Agent 上限：确认单个 Agent 真的跑不动了再扩展
协议先于协作：先定义好通信协议、隔离边界，再引入并行
子 Agent 只回传摘要：搜索和调试细节留在自己的上下文里

关键要点：多 Agent 不是银弹，先用单 Agent 验证可行性。

8. 约束靠期望不靠机制

问题表现：规范写在文档里，期望 Agent 遵守，但没有强制机制。结果 Agent 可能选择性遵守，或者完全忽略。

后果：约束不可靠。一次写进去，到处生效 ------ 这应该是目标，而不是靠人工 Review。

解决方案：约束必须编码进可执行系统。

工具验证：参数校验、返回值结构化、错误给出修正建议
Linter：代码风格、架构分层靠 Linter 机械强制
Hook 机制：关键节点自动检查，不通过就不继续

OpenAI 的实践是：约束编码化而非文档化，架构分层靠自定义 Linter 机械强制，不靠人工 Review。

关键要点：从文档到代码，约束必须可执行。

三、工程实现的五条黄金顺序

为什么需要顺序？因为错误的顺序会导致后期返工，甚至推倒重来。这五条顺序来自实践验证，可以避免大量常见陷阱。

1. 单渠道先跑通

用户输入 → Agent 处理 → 结果返回。

不要第一版就抽象多渠道，先把一条完整链路跑通。渠道差异收敛在 adapter 层，Agent 核心代码不变。

2. 安全边界先于功能

工作空间隔离、白名单、参数验证，任何新功能之前就要到位。

开放 Shell 权限后，git push、rm、数据库写都可能被触发。安全边界要先于功能，三件事必须先到位：谁能用（白名单）、能在哪用（工作空间隔离）、做了什么可以追踪（审计日志）。

Prompt Injection 防护：标注外部内容边界，敏感操作显式确认。

3. 记忆整合要早做

不加整合，第 20 轮对话之后基本就垮了。

长任务中途崩溃，如果没有恢复机制，只能从头再来。把任务进度写到磁盘，重启后从断点继续。任务超过半小时，崩溃恢复是必选项，不是可选项。

4. Skills 先于新工具

领域知识用文档管理比加新工具更灵活。

Skills 延迟加载，按需注入，不破坏缓存。能用 Shell 处理的、只需静态知识的、更适合 Skill 的，都不需要新增工具。

5. 第一个失败就建评测

把第一个真实失败案例转成测试用例，不要等积累了足够多案例再开始建评测体系。

改了 Prompt，不知道是否变好；换了模型，也不知道是否退化。评测是判断"有没有变好"的唯一客观依据。

四、十个核心原则速查

1. Agent 核心循环

感知 → 决策 → 行动 → 反馈。循环本身稳定，新能力通过工具扩展、提示调整、状态外化实现。

2. Harness 决定收敛

验收基线 + 执行边界 + 反馈信号 + 回退手段。高质量自动化验证和清晰目标缺一不可。

3. 上下文工程防 Context Rot

分层管理 + Skills 延迟加载 + 压缩策略。Prompt Caching：稳定的大系统提示比频繁变动的小提示更省钱。

4. 工具设计 ACI 原则

面向 Agent 目标，而非底层 API。边界明确 + 参数防错 + 定义里直接给示例。

5. 记忆四层管理

工作记忆（当前任务）+ 程序性记忆+ 情景记忆（JSONL 历史）+ 语义记忆（MEMORY.md）。

6. 长任务状态外化

Initializer Agent 生成文件系统状态，Coding Agent 循环可重入，进度通过文件传递。

7. 多 Agent 协作

协议先于协作，子 Agent 只回传摘要。任务图 + 隔离边界 + 结构化通信协议。

8. 评测双指标

Pass@k 探边界：回答"理论上能不能做到"。Pass^k 保质量：回答"有没有被改坏"。

9. 可观测两层

Trace 记录：完整 Prompt、messages、工具调用、token 消耗。双层评分：人工标注校准 + LLM 自动打分。

10. 稳定靠工程

消息解耦 + 状态外化 + 分层提示 + 记忆整合 + 安全边界。不是更复杂的循环，而是这些工程细节。

五、总结与自查清单

核心要点回顾

Agent 工程化的关键不在模型，而在工程约束。更贵的模型带来的提升，很多时候没有想象中那么大，反而 Harness 和验证测试质量对成功率的影响更大。

八大反模式覆盖了最常见的陷阱：系统提示当知识库、工具数量失控、缺少验证机制、多 Agent 无边界、记忆不整合、没有评测、过早引入多 Agent、约束靠期望不靠机制。

遵循五条黄金顺序可以避免大量返工：单渠道先跑通、安全边界先于功能、记忆整合要早做、Skills 先于新工具、第一个失败就建评测。

十个核心原则形成可落地的行动清单。

读者可以从哪开始实践

已有 Agent 项目：对照八大反模式自查

系统提示是否过长？是否有 Skills 按需加载？
工具数量是否失控？是否符合 ACI 原则？
是否有验证机制？是否有评测体系？
记忆是否整合？多 Agent 是否有边界？

从零开始新项目：遵循五条黄金顺序

先跑通单链路
安全边界优先
记忆整合早做
Skills 优于新工具
首败即建评测

进阶优化：参考十个核心原则

检查上下文工程是否合理
检查工具设计是否符合 ACI
检查评测体系是否完善
检查可观测性是否到位

参考资料

参考文章：Agent 架构里几块最影响工程效果的内容
TencentDB-Agent-Memory