好的AGENTS.md文件能显著提升代码生成质量，效果堪比模型升级；但糟糕的文档反而比没有文档更差。研究发现，多数AGENTS.md内容要么无效要么有害，有效模式具有特定性和可学习性。同一文件在不同任务中效果差异巨大：在简单任务中能提升25%最佳实践，在复杂任务中却会降低30%完成度。关键在于针对不同任务采用合适的内容模式。

优秀AGENTS.md是模型升级，糟糕的文档则不如不写

我们分析了代码库中数十份AGENTS.md文件对代码生成的影响。表现最佳的文档能使代码生成质量实现从"Haiku"到"Opus"级别的跃升，而最差的文档甚至会导致输出质量低于无文档状态。这一发现促使我们展开了系统性研究。

核心发现：

1. 渐进式披露优于全面覆盖
   最佳实践是将AGENTS.md视为技能手册：用主文件概述常见场景，细节则存入按需加载的参考文档。在约100个核心文件的中型模块中，100-150行的主文档配合少量参考文件能带来10-15%的全指标提升。

2. 流程化工作流显著提升完成度
   将任务分解为编号步骤的工作流效果最显著。例如某部署流程的六步指南使PR缺失文件率从40%降至10%，正确性提升25%，完整度提高20%。

3. 决策表消除歧义
   针对代码库中多种可行方案（如React Query与Zustand的状态管理选择），决策表能提前明确规范，使相关PR的"最佳实践"得分提高25%。

4. 真实代码示例促进复用
   3-10行的生产代码片段能有效提升模式复用率，但过量示例会导致模型错误匹配。

5. 警惕文档过度探索陷阱
   两大常见问题：

   • 过多架构概述导致代理加载数十万token的无用上下文
   • 未配套"应做"说明的"禁止"条款（如超过15条连续警告）会使代理过度保守验证

文档结构建议：

• 模块化文档效果最佳，中型模块配合100-150行主文档最理想
• 根目录超大文档表现较差，需注意周边文档环境（如500K字符的附属文档会削弱主文档效果）
• 确保关键内容必须通过AGENTS.md或其直接引用呈现（参考文档发现率达90%，而孤立文档发现率不足10%）

迁移现有文档策略：

• 可复用README.md但需大幅精简，删除纯人类阅读内容
• 保留高质量现有文档作为参考，但单文件引用不超过10-15条
• 配合语义搜索等补充发现机制

未覆盖领域：

本研究聚焦单次编码任务完成度，未涉及文档长期维护、运维任务或交互式场景，这些将在未来探讨。

（注：全文压缩至原篇幅的30%，保留所有关键数据点和实践建议，剔除重复说明和次要案例，优化中文表达符合技术文档规范）

以下是评论内容的总结：

1. AGENTS.md文件的作用与优化

   • 支持多AGENTS.md文件：verdverm认为在重要子目录中放置更多聚焦的AGENTS.md文件效果更好，可作为目录和速记（"multiple (good) AGENTS.md is even better... act as a table of contents and spark notes"）。
   • 文件需简洁优化：chickensong建议文件应精简，指导代理如何工作，并定期优化（"lean file that tells the agent how to work with the project... occasionally ask the agent to review"）。
   • 文件位置问题：forgotusername6指出代理可能忽略嵌套的agents.md文件，因此更关注代理技能而非文件嵌套（"agents.md files were occasionally missed... put me off putting too much effort into nesting"）。

2. 代理模型的局限性与改进

   • 模型需人工干预：themafia批评模型质量差，需提前规避错误（"The models are so terrible... This is coping behavior"）。
   • 抽象化与自反思：weiliddat建议抽象化工具以提高性能，并探索模型自反思能力（"harness should be abstracted... how well LLMs can self-reflect in a loop"）。
   • 项目结构的重要性：simonw认为若项目文档和测试完善，无需额外指导代理（"if the project itself is in good shape... you don’t need to tell the coding agent much"）。

3. 工具与生态系统的扩展

   • 结构化解决方案：thegagne提出ktext.dev项目，生成结构化上下文文件以优化AGENTS.md（"structured context file... can be validated and scored"）。
   • 工具链独立性：try-working强调工具链应独立于厂商，确保可移植性（"harness should live in your repo... don’t let OpenAI or Anthropic own your work"）。

4. 其他观点

   • 整体环境影响：bushido指出项目中的所有元素（技能、命令、记忆）均影响代理表现（"everything your harness looks at could be this... they all work towards improving or destroying productivity"）。
   • 对AI内容的质疑：therobots927质疑AI指南类内容的泛滥（"Will people ever get tired of writing AI how-to slop?"）。

总结呈现了关于AGENTS.md文件设计、代理模型优化及工具生态的多样化观点，既有具体实践建议，也有对技术局限的批评。