一个文件让 AI Coding 效率翻倍：AGENTS.md 实践指南

📌 一句话摘要

本文系统介绍了 AGENTS.md 的核心理念与实践方法，通过仓库聚合、统一环境配置、验证闭环和自动化检查等策略，构建「打开即理解、改完即验证」的 AI 辅助开发体验。

📝 详细摘要

文章围绕 AGENTS.md 这一给 AI 看的项目指令文件，从痛点分析、核心理念到具体实践进行了全面阐述。作者基于管控系统项目的半年实践，总结了 AGENTS.md 的五大实践：仓库聚合解决上下文割裂、统一环境配置让 AI 能启动项目、验证闭环确保功能可跑通、自动化检查保障规则执行力、参考项目引入为 AI 提供充足上下文。文章强调 AGENTS.md 应遵循「地图而非手册」的渐进式披露原则，控制在 200 行以内，核心规则直接写入，详细信息通过文档链接引用。同时提供了通用编写模板和实施建议，包括从 /init 自动生成开始、通过 bad case 驱动迭代、规则要有自动化检查等。文章最后指出，AGENTS.md 的维护过程本身就是一种知识沉淀，能让团队编码规范从散落状态变为结构化文档。

💡 主要观点

1. AGENTS.md 是给 AI 看的项目指令文件，遵循「地图而非手册」的渐进式披露原则。 AGENTS.md 应控制在 200 行以内，只包含 AI 理解项目全貌的必要信息和违反会直接导致问题的硬性规则，详细信息通过文档链接引用，避免上下文膨胀稀释关键规则。
2. 通过仓库聚合、统一环境配置和验证闭环，构建「打开即理解、改完即验证」的开发体验。 将前后端代码聚合为 monorepo 解决上下文割裂；统一环境变量配置和启动脚本降低 AI 认知负担；建立 curl 验证规范和自动化检查，让 Agent 能自主完成「改→构建→启动→验证」的完整闭环。
3. 引入参考项目源码比维护使用文档更有效，源码永远不会过时。 对于 AI 训练数据中不存在的闭源组件和内部项目，通过 git submodule 直接引入源码，配合架构说明文档作为「地图」，让 AI 在需要细节时直接读取源码，大幅提升代码质量。
4. AGENTS.md 的维护过程本身就是团队知识沉淀，让编码规范从散落状态变为结构化文档。 过去团队的编码规范散落在 Wiki、聊天记录、口头约定里，AGENTS.md 将这些知识结构化地写进文件和配套文档中，虽然初衷是给 AI 看的，但人也能从中受益。

💬 文章金句

• AGENTS.md 的第一原则是渐进式披露——它是一张地图，不是一本手册。
• 如果 AI 不知道这条信息就会写出错误的代码，放 AGENTS.md；如果只是写出不够好的代码，放详细文档，AGENTS.md 里放链接。
• 源码永远不会过时，它就是最准确的文档。
• AGENTS.md 的本质是用最小的上下文成本，让 AI 工具获得最大的项目理解。
• 人类的角色是设计这个回路，而不是在回路中的每一步都亲自操作。

📊 文章信息

阅读完整文章