别让Coding Agent把论文全写进代码

Coding Agent 的问题不是不会写，而是不知道该停在哪里

**截至 2026 年 7 月 29 日，一则关于 Coding Agent“过度实现”的工程复盘正在开发者社区引发讨论。**一位开发者原本搭建了“目标拆解—资料研究—规格生成—代码实现”的完整流水线，Agent 能找到相关论文，也能生成看似详尽的技术方案，但最终写出的代码仍然不对：如果五篇论文给出五种可行方法，它可能把五种方法全部塞进项目，而不是根据真实需求选出一种。

**过度实现是指 Coding Agent 在缺少明确决策边界时，把相关知识、备选方案和未来扩展同时转化为当前代码。**这种代码通常不是语法错误，也未必无法运行；它的问题是接受了多余输入、引入了不必要的抽象、叠加了重复机制，并让维护者无法回答“为什么这里需要这一层”。

这次复盘最值得注意的判断是：**研究应该指导实现，但研究本身不能直接成为实现。**检索到五种方法，只能说明候选空间里存在五种方法，不代表工程需求要求同时采用五种方法。人类工程师会在阅读后做取舍，LLM 却倾向于把“我读到了”误解为“我应该实现”。

一条看似完整的流水线，为什么仍会失控

**传统的 Agent 流水线把信息处理步骤列出来了，却没有把决策责任固定下来。**原始工作流大致如下：

1. Goal：描述工程目标；
2. Decompose：把目标拆成若干问题；
3. Research：为每个问题检索论文、文档和现有实现；
4. Specification：生成实现规格；
5. Implementation：修改代码并执行测试。

**这条链路缺少的不是更多上下文，而是从“候选事实”到“已批准决策”的状态转换。**Research 阶段产出的内容往往混合了三类信息：可以直接采用的事实、值得比较的替代方案，以及当前任务明确不需要的扩展方向。如果 Specification 阶段只是把研究摘要改写成技术文档，模型就会默认所有内容都获得了实现许可。

**LLM 的生成偏好会进一步放大这一问题。**对于模型而言，覆盖更多检索结果通常显得更“完整”，多写一个适配器、多留一个扩展接口、多接受一种输入格式，也比明确删除某个候选方案更容易解释。于是，模型可能同时实现多种解析器、回退策略和缓存层，然后用“增强鲁棒性”包装这些额外工作。

**这不是单纯换一个更强模型就能解决的问题。**更强的模型可能更擅长发现方法之间的冲突，也可能写出更漂亮的抽象，但只要执行边界仍然模糊，它依旧有机会把更多“合理内容”变成更复杂的代码。这里暴露的是 Agent Harness，也就是智能体外部控制框架的缺陷，而不只是模型智力不足。

研究门：先证明“知道了什么”，不要急着写

**研究门是位于资料检索与方案决策之间的检查点，用于把证据、候选方法和未知项整理成可审查的研究产物。**它的核心职责不是评价代码，而是阻止未经筛选的资料直接进入实现阶段。

**一个合格的研究产物必须区分事实、推断、候选方案和未解决问题。**例如，论文证明某种索引结构在特定数据集上降低了查询延迟，这是事实；它适合当前项目，则只是需要验证的推断。另一个方案在理论上更先进，也不代表它满足当前团队的依赖、许可证、部署环境和维护能力。

研究门至少应要求 Agent 交付以下内容：

• **每项结论都要能够追溯到来源。**来源应精确到论文、官方文档、仓库文件或具体实验，而不是一句“业界通常这样做”。
• **每个候选方法都要说明适用条件。**条件包括输入规模、运行环境、依赖项、复杂度、硬件要求和失败模式。
• **替代方案必须保持互斥状态。**在作出选择前，方案 A、B、C 都只是候选项，不能同时进入待实现清单。
• **未知项必须显式保留。**无法确认的接口行为、性能假设和数据格式，应进入验证列表，而不是由模型自行补全。
• **研究阶段不得修改生产代码。**它可以阅读仓库、运行只读分析或建立临时实验，但不能把“顺手修复”混入研究结果。

**研究门的通过标准应该是“问题空间足够清楚”，而不是“资料足够多”。**如果检索结果已经能回答约束、候选方案、关键风险和待验证假设，继续搜索更多论文往往只会扩大上下文并增加选择噪声。对 Coding Agent 来说，停止研究本身就是一种需要外部控制的能力。

规格门：把选择写成合同，而不是写成愿望清单

**规格门是实现前的最终检查点，用于把已选方案转换成可测试、可拒绝和不可随意扩张的工程合同。**研究阶段可以保留五种方法，规格阶段则必须回答：本次采用哪一种、为什么采用、其余四种为什么不做。

一份可执行规格的重点不是篇幅，而是边界。“实现一个灵活、可扩展的解析模块”几乎等于允许 Agent 自由发挥；“只支持 JSONL 输入，每行必须包含 id 与 text，遇到缺失字段立即返回结构化错误，本次不支持 CSV 和自动字段推断”才是能够约束实现的规格。

规格门应固定以下字段：

| 规格字段 | 必须回答的问题 | 缺失后的典型后果 | |---|---|---| | 目标 | 这次改动解决哪一个具体问题 | Agent 顺手重构无关模块 | | 已选方案 | 最终采用哪一种方法 | 多种论文方案被同时实现 | | 选择理由 | 为什么它符合当前约束 | 无法审计技术取舍 | | 明确非目标 | 哪些功能本次绝对不做 | 输入格式和抽象层不断膨胀 | | 输入与输出 | 接口接受什么、拒绝什么 | Agent 擅自增加兼容模式 | | 不变量 | 哪些既有行为不得改变 | 修复局部问题却破坏旧接口 | | 验收测试 | 什么结果代表完成 | 以“代码已生成”代替完成 | | 资源预算 | 文件数、依赖、延迟或内存上限 | 用复杂基础设施解决简单问题 | | 回滚条件 | 出现什么情况必须停止或撤回 | Agent 在错误方向上持续迭代 |

**明确非目标通常比罗列目标更能约束 Coding Agent。**模型知道“要实现缓存”之后，仍可能加入分布式缓存、多级淘汰、指标采集和后台刷新；如果规格同时写明“不增加外部服务、不实现跨进程一致性、不新增配置项”，实现空间才真正收窄。

**规格门还必须禁止模型自行批准自己的扩展提议。**Agent 可以提出“建议未来支持 CSV”，但这项建议只能进入待办列表，不能因为模型认为它有价值就自动升级为当前任务。否则，所谓审批只是让同一个概率系统换一种语气确认自己。

三种阶段产物不能混在一起

**研究报告、决策记录和实现规格是三种不同的工程对象。**把它们合并成一个长文档，看起来节省步骤，实际上会让“论文提到过”“团队决定采用”和“代码必须完成”失去边界。

| 阶段产物 | 核心问题 | 允许包含什么 | 不允许做什么 | |---|---|---|---| | 研究报告 | 有哪些事实和候选方法 | 证据、比较、风险、未知项 | 宣布所有候选都要实现 | | 决策记录 | 当前约束下选哪一个 | 选择、理由、被拒方案 | 用“都不错”回避取舍 | | 实现规格 | 代码具体要做到什么 | 接口、非目标、测试、预算 | 引入未经批准的新设计 | | 实现结果 | 是否按规格完成 | 变更、测试结果、偏差说明 | 反向修改规格来迎合代码 |

**阶段隔离的价值在于让每一次信息升级都有责任人。**某种方法从研究报告进入决策记录，需要一次选择；从决策记录进入实现规格，需要一次约束；实现偏离规格，则需要重新审批。只要把这些状态保存在结构化产物中，Agent 就不能用一段流畅叙述悄悄跨越边界。

真正有效的门，必须由确定性控制器执行

**门只有在外部控制器能够拒绝下一步时才是真正的门。**如果提示词只是写着“请先认真研究，再谨慎实现”，模型仍然可以在同一轮输出中完成研究、批准方案并开始改代码，这更像路标，而不是闸机。

**确定性控制器是用程序化状态机负责阶段切换、权限分配、重试次数和终止条件的 Agent 外层组件。**LLM 可以负责生成候选内容，但是否允许调用写文件工具、是否进入下一阶段、是否超过修改范围，应由可重复执行的规则决定。

一套更稳妥的流程可以设计为：

1. 目标被转换为范围、约束和完成定义；
2. 研究 Agent 只能读取资料并提交研究报告；
3. 研究门检查来源、候选方案、未知项是否齐全；
4. 决策步骤只允许选定一个主方案，并记录拒绝理由；
5. 规格 Agent 生成接口、非目标、测试与资源预算；
6. 规格门执行结构校验，并由人或独立评审 Agent 审批；
7. 实现 Agent 只获得已批准规格和必要仓库上下文；
8. 验证器运行测试，并检查改动是否超出文件与依赖预算；
9. 任何偏差都退回规格阶段，而不是让实现 Agent 临场扩展需求。

**写权限应当随着阶段逐步开放。**研究阶段只读，规格阶段只能写计划文件，实现阶段才能修改目标目录，验证阶段则再次切回只读。权限隔离比“不要修改无关文件”的自然语言提示更可靠，因为后者仍然依赖模型自觉。

上下文越多，不一定越懂项目

**Coding Agent 的另一个误区是把仓库全文和所有研究资料一次性塞进上下文。**更多 Token 并不自动等于更准确的决策；当论文方法、历史讨论、废弃接口和当前需求混在同一个窗口里，模型更难判断哪一项具有执行优先级。

**仓库结构应当先被压缩成地图，再按任务逐步展开。**2026 年 6 月公开的 SeeRepo 研究探索了让多模态 Coding Agent 通过文件层级、类、函数和依赖关系的可视化地图理解代码库；其论文页面报告，在保持或提升问题解决准确率的同时，输入 Token 消耗最多降低了 26%。这一结果说明，Agent 不一定需要读取更多文本，更重要的是先知道代码在哪里、依赖如何连接，以及哪些区域与任务无关。

**研究门和仓库地图解决的是同一个信息治理问题。**前者压缩外部知识，把论文和文档整理为候选决策；后者压缩内部代码，把整个仓库整理为任务相关结构。两者都在避免模型把“看见的全部内容”当成“必须处理的全部内容”。

多 Agent 不会自动带来治理，反而可能放大错误

**把研究、规格和实现拆给多个 Sub-agent，并不天然等于建立了研究门和规格门。**如果研究 Agent 输出十种方案，规格 Agent 不加筛选地全部接收，实现 Agent 又忠实落地，多 Agent 只是把一次过度实现拆成了三次。

**多 Agent 系统需要共享协议，而不是只共享上下文。**每个角色应拥有不同的输入、输出和权限：研究者提交证据，不提交代码；架构评审者做选择，不扩展需求；实现者执行规格，不重新研究；验证者检查偏差，不替实现寻找借口。国内开发者围绕 Claude Code Sub-agent 团队的工程实践也反复强调“先搭组织，再写代码”，但组织只有配合明确的准入条件才有意义。

**独立评审 Agent 也不能被当作绝对可靠的裁判。**如果评审者与实现者使用相同上下文、相同提示框架和相同模型，它们可能共享相同偏差。更实际的做法是让评审过程依赖明确检查表、测试结果、变更预算和结构化字段，而不是要求另一个模型泛泛地评价“这个方案是否合理”。

一套可以直接落地的检查清单

**团队不必一开始就建设复杂的多 Agent 平台，也能用两道门显著降低盲目实现。**最小可用版本可以从 Pull Request 模板、任务规格文件和工具权限三处改造。

研究门检查项

• 每个关键结论是否带有可追溯来源；
• 是否列出了至少一个被拒绝的备选方案及理由；
• 是否区分事实、假设与建议；
• 是否写明适用条件和已知失败模式；
• 是否存在尚未验证却会影响架构的假设；
• 研究过程中是否保持生产代码只读。

规格门检查项

• 是否只选定一个默认实现路径；
• 是否写明非目标与禁止增加的能力；
• 输入、输出、错误语义是否明确；
• 是否规定允许修改的目录、文件和依赖；
• 每项需求是否有对应验收测试；
• 是否设置性能、Token、时间或变更规模预算；
• 出现新需求时，是否强制退回规格阶段。

实现后检查项

• 新增功能能否逐条映射到已批准规格；
• 是否出现规格未要求的公共接口；
• 是否增加不必要的抽象层和第三方依赖；
• 是否接受了规格明确拒绝的额外输入；
• 是否修改了无关文件；
• 测试是否验证行为，而不只是验证代码能够运行。

不要把门做成新的文档官僚主义

**研究门和规格门的风险是从“模型乱写代码”滑向“模型乱写文档”。**如果每个小修复都要求几十页研究报告，团队只会得到更多 Token 消耗和更慢的交付速度，并不能获得更好的决策。

**门的严格程度应当与变更风险匹配。**修改文案或调整局部样式，可以使用简化规格；涉及数据库迁移、身份认证、公共接口、跨模块重构和性能关键路径，则应要求完整研究证据、决策记录、回滚方案与人工审批。门控不是固定流程，而是一种风险分级机制。

**衡量这套方法是否有效，应该看返工和越界，而不是看文档长度。**团队可以追踪规格外新增文件数、非必要依赖数、被拒绝的自动扩展提议数、首次验收通过率、回滚次数和从需求到合并的总时长。如果文档增加了 50%，返工却没有下降，说明门控设计只是增加了流程摩擦。

结论：让模型生成，让系统做决定

**这次社区讨论揭示了 Coding Agent 落地中的一个关键分界：生成能力可以交给模型，执行权限不能只靠模型自律。**研究、规划、规格和代码都可以由 LLM 辅助产生，但从候选方案到正式决策、从规格到写权限的转换，需要外部规则、结构化产物和明确责任人。

**研究门解决的是“哪些知识值得进入决策”，规格门解决的是“哪些决策被允许进入代码”。**两道门之间如果缺少选择，Agent 就会把论文综述变成产品路线图；规格门之后如果缺少权限与验证，Agent 又会把建议功能变成既成事实。

**对当前的 Coding Agent 而言，最稀缺的能力不是再多写几百行代码，而是拒绝那些看似合理、实际没有被要求的代码。**一个成熟的智能体工程系统，不应该只奖励“做了什么”，还必须能够稳定回答“为什么做”“为什么现在做”以及“为什么其他方案没有做”。

参考来源

• Reddit：My LLM kept implementing every method it found, so I added research and specification gates：本文讨论的开发者复盘，描述了 LLM 将多种研究方法同时实现的问题。
• Hugging Face Papers：LLM Agents Can See Code Repositories：SeeRepo 论文页面，介绍利用仓库可视化结构辅助 Coding Agent，并报告最高 26% 的输入 Token 降幅。
• 知乎：用 Claude Code 打造一套可落地的 Sub-agent 团队工程体系：关于 Sub-agent 角色划分、协作流程与工程组织方式的中文实践参考。