--- title: Coding Agent 的常见误区 description: 拆解 Coding Agent 使用中的常见误区：上下文与 session 管理、Rules 和 Skills 堆砌、模糊需求、验收证据、插件与模型选型。 lastModified: 2026-07-26 --- ## 上下文污染（Context Poisoning） **常见误区** - **以为"规则越多越好"**：把各语言编码规范、依赖库使用说明等统统塞进上下文。 - **以为"AGENTS.md 越详细越好"**：把各模块实现细节、注意事项全部写进 AGENTS.md / CLAUDE.md。 - **在单次对话里灌大量文件和日志**：一次性粘贴大段 log、配置、代码，希望模型"全都记住"。 - **在一个会话里无限叠加功能**：担心开启新会话后 Agent 不再了解项目背景，于是所有事都往一个 session 里堆。 这些做法直接导致的结果是：上下文被打满或长期处于接近上限的状态。 **核心结论（有点反直觉）** - 上下文占用**不是越多越好**，塞入的内容越多，并不等于 Agent 越了解你的项目。 - 过大的上下文会让模型的**推理质量明显下降**，表现为答非所问、抓不住重点等。 - 模型存在"上下文召回率"问题：并不是所有放进去的内容都会被有效利用，被"看见"和被"用上"只是部分。 **相关文章：** - [Augment Blog | Your agent's context is a junk drawer](https://www.augmentcode.com/blog/your-agents-context-is-a-junk-drawer) - [Fiction liveBench April 29 2025](https://fiction.live/stories/Fiction-liveBench-April-29-2025/oQdzQvKHw8JyXbN87) ![](https://r2.unono.app/2026/05/f416781fe310cfab2567ae722450b6e0.png) --- ## 把 `/compact` 当成无限续命工具 **常见误区** - 只要上下文快满了就执行 `/compact`，然后在同一个 session 里继续塞新任务。 - 目标、分支或仓库已经改变，仍然认为旧对话越完整，Agent 越容易接着做。 - 多次压缩后出现事实丢失或前后矛盾，继续补充解释并再次压缩，不愿新开 session。 **实际情况** `/compact` 做的是摘要，不是无损压缩。Anthropic 将 compaction 视为长任务保持连贯性的第一种手段，同时也明确指出：摘要取舍不当会丢失当时看似次要、后来却很关键的信息；在长时间任务中，compaction 本身也不足以保证后续 Agent 正确理解进度。[Anthropic | Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) [Anthropic | Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) 压缩适合延续同一个连贯目标。任务目标、代码分支、仓库或资料集已经改变时，旧上下文大部分不再是资产，而是噪音。OpenAI 的 Codex 最佳实践也建议让一个 chat 对应一个连贯的工作单元，整个项目长期共用一个 chat 会让上下文膨胀并降低结果质量。[OpenAI | Codex best practices](https://developers.openai.com/codex/learn/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](https://openai.com/index/harness-engineering/) 不同 Agent 的加载规则并不完全相同。以 Claude Code 为例，`CLAUDE.md` 会在每个会话开始时进入上下文，官方建议控制在 200 行以内；多步骤流程应移到 Skill，特定路径的规则应使用按路径加载的 Rules。文本规则也不是强制配置，必须阻止的动作要交给 Hook、权限策略或 CI。[Anthropic | How Claude remembers your project](https://docs.anthropic.com/en/docs/claude-code/memory) 主流模型本身已掌握大多数编程语言和框架的通用编码规范，项目也有 `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](https://openai.com/index/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](https://developers.openai.com/codex/prompting) [OpenAI | Codex best practices](https://developers.openai.com/codex/learn/best-practices) 这也是需求澄清 Skill 容易被误用的地方。[Superpowers 的 brainstorming](https://github.com/obra/superpowers/blob/main/skills/brainstorming/SKILL.md) 会逐个提问、给出多个方案并推荐一个方向；[Matt Pocock 的 grill-me](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md) 会调用底层的 [grilling](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md)，后者同样每次只问一个问题，并为每个问题给出推荐答案。它还明确规定：可查证的事实应由 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](https://github.com/code-yeongyu/oh-my-openagent/commit/50112b97eacea074376978748d1f5b853feb83cf) ![](https://r2.unono.app/2026/05/c6d889193117b46c7c028cf299ba3cfe.png) **正确姿势：用好内置的 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](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) OpenAI 的 Codex 最佳实践也没有把“Agent 说完成了”当成终点，而是要求根据任务运行测试、lint、format 或 typecheck，确认实际行为符合请求，并检查最终 diff 中的缺陷、回归和高风险改动。[OpenAI | Codex best practices](https://developers.openai.com/codex/learn/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、模型映射和默认模型是否配置正确。 | 档位 | 适合的任务 | 不应承担的工作 | | --- | --- | --- | | 大杯 | 复杂 reasoning、architecture trade-off、疑难 debugging、高风险 change review | 自动批准 production operation 或跳过 validation | | 中杯 | 常规 coding、test 补充、明确 refactoring、technical documentation | 在缺少目标或 evidence 时扩大改动范围 | | 小杯 | file 与 log 筛选、classification、format conversion、简单 query | 复杂 root cause judgement、architecture decision 或不可逆操作 | 下面的模型仅用于理解各厂商产品线中的相对档位。实际可用模型和路由结果仍应以当前 Provider 配置及厂商官方目录为准。 | 厂商 | 大杯 | 中杯 | 小杯 | 官方目录 | | --- | --- | --- | --- | --- | | OpenAI | `gpt-5.6-sol` | `gpt-5.6-terra` | `gpt-5.6-luna` | [Models](https://developers.openai.com/api/docs/models) | | Anthropic | `claude-fable-5`
`claude-opus-5` | `claude-sonnet-5` | `claude-haiku-4-5` | [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview) | | 智谱 AI | `glm-5.2` | `glm-4.7` | `glm-4.7-flash` | [模型概览](https://docs.bigmodel.cn/cn/guide/models) | | DeepSeek | `deepseek-v4-pro` | / | `deepseek-v4-flash` | [Models & Pricing](https://api-docs.deepseek.com/quick_start/pricing/) | **核心结论** - 不是「Haiku 这种小模型是垃圾，狗都不用」，而是**用错了模型的角色**。 - 把 Haiku 放在 explore subagent 上做「广度探索 + 垃圾过滤」，再把干净的高价值 Context 交给 Opus / GPT-5.4 之类的大模型去深度推理，整体效果通常会比「全程一把梭大模型」更好、更便宜也更快。 - 真正的误区不是"小模型不行"，而是**所有事情都丢给 Main Agent 和大模型做，既耗费上下文预算，又浪费钱**。 --- 免责声明(有问题就让 AI 背锅)：以上内容由人类提出想法，AI 员工(Dia Browser)帮忙整理成文。