Coding Agent 的常见误区

拆解 Coding Agent 使用中的常见误区：上下文与 session 管理、Rules 和 Skills 堆砌、模糊需求、验收证据、插件与模型选型。

上下文污染（Context Poisoning）

常见误区

• 以为“规则越多越好”：把各语言编码规范、依赖库使用说明等统统塞进上下文。
• 以为“AGENTS.md 越详细越好”：把各模块实现细节、注意事项全部写进 AGENTS.md / CLAUDE.md。
• 在单次对话里灌大量文件和日志：一次性粘贴大段 log、配置、代码，希望模型“全都记住”。
• 在一个会话里无限叠加功能：担心开启新会话后 Agent 不再了解项目背景，于是所有事都往一个 session 里堆。

这些做法直接导致的结果是：上下文被打满或长期处于接近上限的状态。

核心结论（有点反直觉）

• 上下文占用不是越多越好，塞入的内容越多，并不等于 Agent 越了解你的项目。
• 过大的上下文会让模型的推理质量明显下降，表现为答非所问、抓不住重点等。
• 模型存在“上下文召回率”问题：并不是所有放进去的内容都会被有效利用，被“看见”和被“用上”只是部分。

相关文章：

• Augment Blog | Your agent’s context is a junk drawer
• Fiction liveBench April 29 2025

把 /compact 当成无限续命工具

常见误区

• 只要上下文快满了就执行 /compact，然后在同一个 session 里继续塞新任务。
• 目标、分支或仓库已经改变，仍然认为旧对话越完整，Agent 越容易接着做。
• 多次压缩后出现事实丢失或前后矛盾，继续补充解释并再次压缩，不愿新开 session。

实际情况

/compact 做的是摘要，不是无损压缩。Anthropic 将 compaction 视为长任务保持连贯性的第一种手段，同时也明确指出：摘要取舍不当会丢失当时看似次要、后来却很关键的信息；在长时间任务中，compaction 本身也不足以保证后续 Agent 正确理解进度。Anthropic | Effective context engineering for AI agents Anthropic | Effective harnesses for long-running agents

压缩适合延续同一个连贯目标。任务目标、代码分支、仓库或资料集已经改变时，旧上下文大部分不再是资产，而是噪音。OpenAI 的 Codex 最佳实践也建议让一个 chat 对应一个连贯的工作单元，整个项目长期共用一个 chat 会让上下文膨胀并降低结果质量。OpenAI | Codex best practices

正确姿势

• 仍在解决同一个问题，只是历史命令输出太多时，可以执行一次 /compact 后继续。
• 目标已经改变、切换了分支或仓库、引入了另一组无关资料，或者多次压缩后 Agent 开始忽略已确认事实时，写交接记录并新开 session。
• 交接记录只保留下一位 Agent 真正需要的内容：目标、已确认事实、已完成改动、剩余任务、关键文件、验证命令和未决风险。
• 不要把完整聊天记录重新灌进新 session。让 Agent 从代码、Git 状态和交接记录恢复现场，缺什么再按需读取。

/compact 用来延续任务，不用来维持 session 的寿命。

Rules 全塞进 AGENTS.md

常见误区

• 每次 Code Review 发现一个问题，就往根目录 AGENTS.md 追加一条规则。
• 把某个目录、某个任务或某条命令的操作细节，也当成所有会话都必须知道的规则。
• 以为写进 AGENTS.md 就等于强制执行，连权限、密钥和部署保护也只靠自然语言约束。
• 把编程语言或框架的通用编码规范写进 Rules / AGENTS.md，担心不写模型就不知道。

实际情况

根目录 AGENTS.md 会成为每次任务的默认背景。它越长，越会挤占代码、任务和证据的上下文；规则互相矛盾或过期后，Agent 也很难判断哪条还有效。OpenAI 的实践是把 AGENTS.md 作为短小的目录，而不是百科全书，让 Agent 从稳定入口按需寻找资料。OpenAI | Harness engineering

不同 Agent 的加载规则并不完全相同。以 Claude Code 为例，CLAUDE.md 会在每个会话开始时进入上下文，官方建议控制在 200 行以内；多步骤流程应移到 Skill，特定路径的规则应使用按路径加载的 Rules。文本规则也不是强制配置，必须阻止的动作要交给 Hook、权限策略或 CI。Anthropic | How Claude remembers your project

主流模型本身已掌握大多数编程语言和框架的通用编码规范，项目也有 lint 与 format 工具做可执行校验。把这些内容重复写进规则通常没有收益。只有那些隐式、无法通过工具约束，并且模型在同类任务中反复犯错的约定，才值得写入 Rules / AGENTS.md。

正确姿势

• 根目录 AGENTS.md 只保留每次任务都成立的事实：构建和验证命令、仓库地图、少量全局约束，以及指向详细文档的链接。
• 与某个目录或文件类型相关的规则放到对应子目录，或使用 Agent 支持的路径作用域规则，让它在读到相关文件时再加载。
• 多步骤、可复用的操作流程放进 Skill；设计决策、领域知识和排障细节放进可检索的文档。AGENTS.md 只说明去哪里找。
• 对删除、发布、密钥、权限等不能出错的边界，使用 Hook、最小权限、CI 或平台策略验证。不要把“禁止”写在 Markdown 里就当作保护已经生效。
• 定期删除失效、重复或无法验证的规则。新规则应当来自重复发生的错误、Code Review 反馈或团队已经确认的约定，而不是一次性的临时提醒。

AGENTS.md 的职责是给 Agent 一张地图，不是让它背完整个仓库。

skills 不是越多越好

常见误区

• 见到一个有用的 skill 就全局安装，默认让 Agent 都能发现。
• 把一个完整领域拆成很多极细的 skill，比如为查文档、下载文件、改权限各装一个。
• 多个 skill 做相近的事，却没有写清触发边界，期待 Agent 自己选对。

实际情况

skill 不是免费的功能开关。支持按需加载的 Agent 通常会先读取 skill 的名称和描述，再决定是否加载完整说明。skill 越多，默认要处理的发现信息越多，语义重叠时还会让路由变得含糊。最终常见的结果是：该触发的没触发，或加载了一套不相关的流程。

OpenAI 在其 Coding Agent 的实践里把 AGENTS.md 定位为简短目录，而不是百科全书，并强调让 Agent 从小而稳定的入口逐步发现所需资料。skill 也该遵循同一原则：入口少，边界清楚，细节按任务展开。OpenAI | Harness engineering

正确姿势

• 一个 skill 对应一个稳定、可复用且边界明确的工作流或领域入口，不要为每条命令单独建 skill。
• 能归到同一领域的能力收成一个入口，正文只保留路由、核心约束和副作用边界；详细指南、案例和脚本等任务命中后再读。
• 写清楚“什么时候用”和“什么时候不用”。如果两个 skill 的触发条件说不清，就应该合并或删掉其中一个。
• 定期看真实使用频率。低频但必要的流程可以手动调用，长期不用的 skill 直接移除，别让历史试验一直占着发现空间。

放在哪里

• 放在用户目录 ~/.agents/skills/：跨项目都适用、与仓库无关的个人工作流。比如写作润色、通用代码审查、浏览器自动化，或某个外部服务的通用操作。内容必须不依赖项目路径、业务术语、私有配置和特定构建命令。
• 放在项目目录 ./.agents/skills/：只有这个仓库需要的工作流。比如项目的测试与发布流程、领域排障手册、内部 API 操作、架构约束和本地工具链。用相对路径，把它和代码一起提交、评审和更新。
• 如果拿掉仓库仍然说得通，放用户目录；如果必须先了解仓库才能正确执行，放项目目录。不要在两个位置保留同名、内容相近的 skill，避免 Agent 选错入口。

数量不是目标。Agent 能稳定找到正确入口，并在需要时拿到刚好够用的说明，才是 skill 设计的目标。

以为模糊 Prompt 能靠追问自动补全

常见误区

• 只给一句模糊想法，期待 Agent 自己补全目标、业务规则和验收标准。
• 在 brainstorming 或需求访谈中，把 Agent 给出的推荐选项当成标准答案。
• 自己并不理解问题和选项，为了让流程继续而盲选、乱答，最后直接批准生成的设计。

实际情况

Agent 可以帮助澄清需求，但不能替用户凭空补出真实意图和业务约束。OpenAI 的提示最佳实践建议为重要任务说明目标、相关上下文、输出要求和边界，并在信息缺失时明确标记，而不是猜测；Codex 的实践还会补充 Done when，让完成条件可以被检查。OpenAI | Prompting OpenAI | Codex best practices

这也是需求澄清 Skill 容易被误用的地方。Superpowers 的 brainstorming 会逐个提问、给出多个方案并推荐一个方向；Matt Pocock 的 grill-me 会调用底层的 grilling，后者同样每次只问一个问题，并为每个问题给出推荐答案。它还明确规定：可查证的事实应由 Agent 使用工具寻找，真正的决策必须交给用户回答。

这些流程的作用是暴露隐含决策，不是替用户获得产品判断和领域知识。如果用户不理解问题，却持续接受推荐项，模型提出的假设就会被一层层固化成需求、设计和计划。流程最终可能得到形式完整的“共同理解”，实际方向却已经偏离原始目标。

正确姿势

• 先把信息分成事实、决策和未知项。事实让 Agent 查代码、文档或权威来源；决策由真正承担结果的人确认；未知项保持未知，不要为了结束访谈随便选。
• 对推荐选项至少能解释两件事：为什么适合当前目标，以及放弃了什么。解释不了时，要求 Agent 补证据、给具体例子或缩小问题。
• 在进入设计前，让 Agent 复述目标、约束、关键假设和验收方式，并标出每项依据来自用户、代码还是外部资料。
• 把批准理解为对决策负责，不是确认自己点完了所有选项。重要需求仍需产品、业务或技术责任人复核。

澄清流程可以减少歧义，但不能替代判断。

误信「超级 IDE 插件」是银弹

代表工具: super claude、superpowers、oh-my-opencode，以及各种号称「一键扫仓库」「自动改代码」的 Coding Agent 插件。

常见误区

• 以为「装上插件 = 多了个高级 AI 搭档」，可以不做需求拆解和设计。
• 把「全仓库扫描」「一键重构」当成银弹，期待它像资深架构师一样一针见血。
• 默认接受长篇大论回答，把啰嗦解释误当成「全面、专业」。

实际情况

• 本质还是「聊天 + 代码索引」，上限由模型本身、索引质量和你的提问方式共同决定，远不是银弹。
• 默认输出往往很啰嗦：重复项目背景、解释常识、给一堆模糊建议。
• 仓库一大、约束一弱，就容易「泛泛而谈」——看起来很聪明，落地价值却不高。

额外风险：System Prompt / Prompt Cache 被插件污染

• 部分实现粗糙的插件（典型如 oh-my-opencode 这一类草台班子）会把「当前时间」「随机标识」甚至无关环境信息塞进 system prompt。
• 这些字段看似无害，实际上会导致 Prompt Cache 频繁失效：
  • 每次调用的 prompt 都略有不同（时间戳、UUID 等），缓存命中率接近 0。
  • 模型费用大幅上涨：同一类请求反复全量计费，完全吃不到缓存红利。
  • 响应时间明显变慢：本来可以从缓存秒回的请求，被迫每次都重新推理。
• 叠加前面说的上下文污染问题，结果就是：贵、慢、还啰嗦。

oh-my-openagent commit - 50112b9

正确姿势：用好内置的 plan → build 流程

• Claude Code / OpenCode / Codex 等主流 Coding Agent 的 plan mode 本身就是精心调教过的。
• 在大多数功能迭代场景里，遵循「先 Plan 再 Build」的标准流程，已经足够：
  • 先用 plan 模式收敛需求、列出改动点、拆分步骤。
  • 再按计划逐步生成代码，对单个文件或小范围改动进行验证。
• 相比把希望寄托在「超级插件能一口吃掉全仓库」上，有意识地驱动 plan → build 流程，更可靠也更可控。

使用建议

• 把超级插件当作「快捷入口 + 重复劳动加速器」，而不是替你做架构决策的上帝视角。
• 尽量了解插件的 prompt / 权限策略，避免被不透明的 system prompt 暗中带偏，尤其是要警惕那些每次都往 prompt 里塞时间戳、随机 token 的实现。
• 一旦发现回答异常啰嗦、费用异常上涨或响应明显变慢，优先排查：是不是插件在暗改上下文、导致 Prompt Cache 失效，而不是一味怪「模型不行」。

误把 Agent 的自述当成验收结果

常见误区

• Agent 回复“已经检查”“测试通过”或“功能已完成”，就认为任务可以交付。
• 只看最终总结，不看实际 diff、测试命令、错误输出和未验证范围。
• 单元测试通过就默认用户流程也正常，忽略运行时、集成和端到端行为。

实际情况

Agent 的完成声明只是对执行过程的描述，不是独立证据。Anthropic 在长时间编码实验中观察到两类典型失败：后续 Agent 看到已有进展便提前宣布整个任务完成；Agent 修改代码并运行单元测试或 curl 后，仍可能没有发现功能在真实用户流程中无法工作。明确要求使用浏览器自动化做端到端验证后，结果才明显改善。Anthropic | Effective harnesses for long-running agents

OpenAI 的 Codex 最佳实践也没有把“Agent 说完成了”当成终点，而是要求根据任务运行测试、lint、format 或 typecheck，确认实际行为符合请求，并检查最终 diff 中的缺陷、回归和高风险改动。OpenAI | Codex best practices

正确姿势

• 在任务开始前定义验收方式，让完成声明绑定到可检查的证据，而不是由 Agent 临时判断“看起来完成了”。
• 代码改动至少检查 diff 和相关测试；Bug 修复要重新执行复现步骤；UI 改动要在真实页面核对；文档和数据结论要回到原始来源。
• 要求 Agent 报告实际执行的命令、关键结果、未运行的检查和剩余风险。没有运行条件时，应明确写“未验证”，不能用静态阅读代替测试通过。
• 高风险改动仍需责任人或 CI 独立复核。让另一个 Agent review 可以增加线索，但不能代替确定性的测试和审批边界。

验收看证据，不看语气。

误判「Haiku 这种小模型都是垃圾」

常见误区

• 觉得“小模型= 智商低”，只要是 Agent 就必须上 Opus / GPT-5.4 这种超大杯大模型。
• 在一个 Agent 里既做探索、又做规划、又写代码，所有检索结果、文档、日志一股脑丢进 Main Agent 的 Context。
• 把「推理质量差」简单归因于“小模型不行”，而不是反思：是不是让它在一堆垃圾 Context 里工作。

实际情况

• 在 AI Agent 的探索阶段，如果直接让 Main Agent 去「到处乱翻」，很容易把大量无关信息一起塞进它的上下文，后续每一步推理都在「垃圾堆里找答案」，效果只会越来越差。
• 正确的做法是引入一个专门的 explore subagent：只负责「去各处探索 → 过滤噪音 → 收敛出一小块高价值 Context」，再把这块精炼后的上下文交给 Main Agent 做严肃推理。
• 在这个阶段，Haiku 这类小模型反而非常适合：
  • 推理速度快，可以高频试错、快速遍历多种检索路线和问题拆解方式。
  • 费用极低，可以大胆多开几个 explore subagent 做并行探索，而不用心疼 token。
  • 任务本身偏「筛选、归纳、剔除垃圾」，对极致推理深度的要求没那么高。

按任务档位选择模型

大杯、中杯、小杯描述的是任务档位，不是可以直接填入 Claude Code 的固定 Model name。先判断任务需要哪个档位，再核对 Provider、API format、模型映射和默认模型是否配置正确。

下面的模型仅用于理解各厂商产品线中的相对档位。实际可用模型和路由结果仍应以当前 Provider 配置及厂商官方目录为准。

核心结论

• 不是「Haiku 这种小模型是垃圾，狗都不用」，而是用错了模型的角色。
• 把 Haiku 放在 explore subagent 上做「广度探索 + 垃圾过滤」，再把干净的高价值 Context 交给 Opus / GPT-5.4 之类的大模型去深度推理，整体效果通常会比「全程一把梭大模型」更好、更便宜也更快。
• 真正的误区不是“小模型不行”，而是所有事情都丢给 Main Agent 和大模型做，既耗费上下文预算，又浪费钱。

免责声明(有问题就让 AI 背锅)：以上内容由人类提出想法，AI 员工(Dia Browser)帮忙整理成文。