AI Agent 核心文件解析：半年实践揭示的性能上限关键

过去半年，我为自己负责的每一个技术项目——包括中后台业务系统、底层框架、SDK和文档站点——都创建并维护了一份AGENTS.md文件。

尽管这些项目的技术栈和团队规模各不相同，但维护这份文件的核心方法论最终都收敛到了相似的实践模式。如今，业界更倾向于将这套实践称为「Harness Engineering」。

如何撰写一份真正有效的AGENTS.md？本文将分享我在实践中总结出的五个核心要点。

如果你正在使用Cursor、Claude Code、Qoder、灵码或Copilot等AI编码工具，却感觉它们始终无法真正“理解”你的项目，那么本文或许能帮你打破这层认知壁垒。

核心定义：AGENTS.md是面向AI的README

这一概念的演进脉络在过去一年中已十分清晰。

其雏形源于Anthropic的Claude Code——该工具在运行时会自动读取项目根目录下的CLAUDE.md文件，并将其内容注入到发送给模型的请求中。

方法直接，效果显著。你维护得越用心，AI的表现就越出色；AI表现越出色，你就越有动力持续优化。一个高效的正向循环就此建立。

随后，各家AI工具纷纷推出自己的配置文件标准，一度造成混乱：Cursor使用.cursorrules，Copilot使用.github/copilot-instructions.md，Gemini CLI使用GEMINI.md……团队不得不为不同工具维护多份内容雷同的文件，任何规则变更都需要同步多处，维护成本陡增。

转机出现在2025年5月。Sourcegraph的AMP率先倡议统一标准，采用AGENT.md（单数）。此后，OpenAI收购了agents.md域名，并提议使用复数形式的AGENTS.md，理由是多智能体可能共享同一份配置。AMP团队随即跟进并统一标准。最终，AGENTS.md成为事实上的行业规范，并由Linux Foundation旗下的Agentic AI Foundation负责托管。

截至2026年初，GitHub上已有超过6万个开源项目采纳此格式。Cursor、Kiro、Qoder、灵码、Copilot均已提供支持。Claude Code虽仍默认识别CLAUDE.md，但其内容完全通用，只需一行ln -s AGENTS.md CLAUDE.md命令即可实现兼容。

缺失AGENTS.md时，AI的“笨拙”体现在何处

谈谈我们遇到的实际痛点。在为中后台业务系统初次引入AI编码工具时，体验相当尴尬：工具到位了，但效率提升远不及预期。问题根源并非工具本身，而在于项目对AI极不友好。

首先，前后端上下文割裂。后端与前端分属两个独立的Git仓库。修改一个涉及联动的功能时，需要在两个编辑器窗口间反复切换。AI每次切换都会丢失上下文，迫使开发者反复重新描述背景，效率低下。

其次，AI无法识别私有组件。项目前端使用了一套公司内部封装的高阶组件库——基于React二次封装的表格、表单、操作栏等，均为闭源代码。这些组件不存在于AI的训练数据中，也无公开文档可查。尽管我们维护了部分使用文档供AI参考，但文档更新总是滞后于实现，导致AI生成的代码经常用错属性。

再次，AI不了解项目的“潜规则”。异常必须使用BusinessException、响应体由框架统一包装、Controller禁止绕过Service直接注入Repository——这些规则仅存在于团队成员的头脑中，AI对此一无所知。结果就是，AI产出的代码风格各异，每次都需要人工纠正，且下次仍会重犯。

最后，AI无法独立启动与自测。它完成代码修改后便停止工作，等待人工验证。这意味着AI的工作流是断裂的——它只能完成“编码”环节，后续的“构建→启动→验证→修复”全需人工驱动。指望Agent在夜间自主执行任务？这几乎不可能，因为它连项目都无法启动。

所有这些痛点的共同根源在于：项目的核心知识与规范存在于人脑之中，而非AI可直接读取的载体里。

核心原则：提供地图，而非手册

在动笔之前，必须确立一条核心原则——AGENTS.md应是一张“地图”，而非一本“手册”。

OpenAI Harness Engineering的首要原则便是“Map, not Manual”。AGENTS.md应是一份约200行的导航指南，告诉Agent“去哪里寻找什么”，而具体细节则存放在其链接的专项文档中。

Anthropic最新的博客也表达了相同观点：CLAUDE.md应存放“引用”，而非“手册全文”。

当所有内容都显得重要时，重要便不复存在。若将所有细节都塞入AGENTS.md，它会膨胀为一份数千行的庞然大物，严重稀释AI的注意力，导致那些真正关键的核心规则被淹没。

判断一条信息应置于AGENTS.md还是详细文档中，标准很简单：

• AI若不知此规则将产出错误代码 → 放入AGENTS.md。
• AI若不知此规则仅会导致代码不够优雅 → 放入详细文档，并在AGENTS.md中提供链接。

实践一：仓库聚合，为AI呈现全栈视图

解决前后端分仓问题最直接的方法，是将它们在物理上聚合。我们的项目从三仓分离逐步演进至monorepo模式。

什么是monorepo？简而言之，它将多个关联项目（前端、后端、SDK、文档等）置于同一个Git仓库中管理，而非每个项目独立成仓。Google、Meta、字节跳动等公司的核心代码库均采用此模式。其优势在于跨项目变更可单次提交、统一构建、共享工具链；代价是仓库体积增大，需要更完善的构建工具支持。与之相对的是polyrepo（多仓库），即各项目独立管理的传统模式，前后端分仓便是典型。

project-root/
    server/                      # 后端（Spring Boot）
    web/                         # 前端（React + TS）
    user-guide/                  # 用户手册（Markdown）
    reference-projects/          # 参考项目（git submodule）
    scripts/                     # 构建、启动、检查脚本
    docs/                        # 架构与设计文档

monorepo天然解决了上下文割裂问题——AI在同一个编辑器窗口中即可查看Controller接口定义及对应的前端API调用。团队现已不再严格区分前后端角色，而是在同一仓库内进行全栈开发。

将用户手册仓库纳入monorepo还带来一个额外收益：当前用户手册多由AI基于代码生成，功能代码修改后，可顺势让AI更新对应的用户手册，省去了单独的维护成本。

若存量项目重构成本过高，可采用折中方案——编写一个setup-repos.sh脚本，将前端仓库克隆至后端项目的子目录下，并将该子目录加入.gitignore。此举既不影响CI/CD流程，对不使用AI工具的同事也完全透明。

实践二：统一环境配置，让AI能够启动项目

每位开发者本地的环境配置方式各异——有人使用IDE的JVM参数，有人用export命令，有人写在.bashrc中。AI对此完全无从知晓，既找不到环境变量，也不知如何启动项目。

我们的解决方案是：将所有本地环境变量统一配置在~/._env文件中，启动脚本自动source此文件。将其置于用户家目录而非项目目录，是为了避免意外提交至Git。AI通过AGENTS.md即可知晓配置的存放位置。

同时，配套一个一键启动脚本，封装JDK检测、优雅关闭旧进程、健康检查等所有细节：

$ ./scripts/start-server.sh              # 构建+启动+健康检查
$ ./scripts/start-server.sh --quick      # 服务健康则秒返回
$ ./scripts/start-server.sh --skip-build # 跳过构建直接重启

AI无需理解这些脚本背后的复杂逻辑，只需调用一条命令。这正是AGENTS.md中“快速命令”章节的核心价值——将复杂的本地环境操作封装为简单指令，极大降低AI的认知负担。

实践三：构建验证闭环，代码修改后必须通过接口测试

这是令我感触最深的一环。Harness Engineering的另一条原则是“机械验证优于人工检查”，验证闭环正是此原则的具体落地。

我们在项目中制定了一套严格的curl验证规范：

• 每个curl命令独立执行——单条命令只完成一项操作，避免使用管道串联多个步骤。
• 使用临时文件传递数据——curl的输出写入/tmp/目录，后续由python3等工具独立解析。
• Token获取模板化——登录 → 结果写入文件 → 提取token → 后续请求携带。
• 排查路径明确——日志文件位置、数据库连接方式均在AGENTS.md中清晰说明。

为何如此严格？因为AI Agent在shell中执行命令时，常遇到兼容性问题。例如在zsh下，管道与方括号glob组合使用可能导致curl | python3 -c "print(data['key'])"这类命令直接报错。使用临时文件中转虽多一步，但稳定性显著提升。

# 步骤1：登录，结果写入文件
curl -s -X POST http://localhost:8080/auth/login \
    -H 'Content-Type: application/json' \
    -d '{"username":"admin","password":"admin"}' > /tmp/login.json

# 步骤2：提取token（独立命令）
python3 -c "import json; print(json.load(open('/tmp/login.json'))['data']['token'])" > /tmp/token.txt

# 步骤3：业务接口调用
TOKEN=$(cat /tmp/token.txt)
curl -s -X POST http://localhost:8080/api/items/list \
    -H "Authorization: Bearer $TOKEN" \
    -d '{"page":0,"size":10}' > /tmp/result.json

前端验证则使用Agent Browser。纯curl无法观察页面渲染、交互与布局问题。调试前端疑难时，我会利用AI工具自带的浏览器自动化能力（当前主流AI编码工具基本均已支持），让Agent自行打开浏览器、操作页面、截图对比。这比让AI猜测CSS问题高效得多。

建立了端到端的验证闭环后，Agent的产出质量截然不同。尤其在夜间执行场景下——睡前设计好Spec，让Agent自主执行任务，次日清晨验收结果——验证闭环是此类工作模式得以成立的前提。

实践四：实施自动化检查，确保规则具备执行力

AGENTS.md中定义的规则，若缺乏自动化检查，AI和开发者都可能违反。

以我们项目的分层规则为例：L0 entity层仅可依赖common，L4 service层是业务核心，L5 controller层仅能依赖service。仅将这条规则写入AGENTS.md远远不够，必须配备lint脚本扫描所有Java文件的import语句，一旦违规即输出可操作的错误信息：

✗ service/client/impl/SomeService.java 导入了 entity.SomeEntity
原因: 客户端实现禁止直接依赖业务Entity，须通过DTO传递
修复: 在编排层完成Entity→DTO转换，客户端只接收DTO

注意错误信息的格式：WHAT（违反了什么） + WHY（为何不允许） + HOW（如何修复）。这不仅面向开发者，也面向AI——AI读取此错误后，可直接依据HOW部分的指引进行修复，无需额外上下文。

通过Makefile提供统一入口：make lint-arch、make lint-format、make build、make test。AI修改代码后可自主运行这些检查，“修改 → 检查 → 修复”的闭环便自动完成。

实践五：引入参考项目，为AI提供充足上下文

私有组件、项目依赖的开源中间件、兄弟产品的代码——这些都是AI训练数据未能覆盖的盲区。试图通过编写文档弥补，成本高昂、覆盖不全且易过时。

后来我转变了思路——不写文档，直接引入源码。在项目中创建reference-projects/目录，通过git submodule引入相关项目的源码：

reference-projects/
    core-engine/              # 项目依赖的开源核心引擎
    config-center/            # 项目依赖的开源配置中心
    ui-components/             # 私有React组件库源码（TypeScript）
    sibling-backend/          # 兄弟产品的后端（Go）
    sibling-frontend/         # 兄弟产品的前端（React）
    open-portal/              # 一个相关的开源中后台门户系统

源码永不过时，它本身就是最准确、最权威的文档。

当AI不知如何编写私有组件时，可直接查阅源码中的TypeScript定义与实现；需要对接底层引擎时，可直接查看核心模块的实际代码。此改变之后，AI的代码质量实现了质的飞跃。

同时，为每个参考项目维护一份架构说明（docs/design-docs/ref-*.md）作为“地图”，帮助AI快速定位关键模块。这些参考文档本身也是AI基于参考项目源码生成的——这又是“AI基于代码撰写文档”的一个实例。

你或许会担忧：引入如此多的参考仓库，AI是否会无所适从？根据我的实际测试，完全不必担心。当前的大语言模型已足够智能，能够判断何时需从参考项目中寻找答案，何时应在当前项目代码中进行修改。它不会因参考项目增多而迷失方向，反而会因获得充足的上下文而产出更精确的代码。

AGENTS.md通用模板

将上述实践提炼后，AGENTS.md可参照以下骨架撰写：

建议将篇幅控制在200行以内。若超出，则考虑将细节拆分至docs/目录下的专题文档中。

如何开始：从/init起步，以bad case驱动迭代

切勿试图一次性撰写出完美的AGENTS.md。我推荐以下起步方式：

第一步，使用工具自带命令生成初始版本——Claude Code的/init、Qoder的qoder init均可自动扫描项目结构，生成一份覆盖项目概述与构建命令的初始版本。这是一个良好的起点。

第二步，以bad case驱动迭代。每当AI犯下一个错误——用错命名、出现跨层依赖、遗漏某项约定——便思考：“若在AGENTS.md中增加一条XX规则，AI是否就能避免此错误？”若是，则将其加入。这是最高效的迭代方式。

第三步，为重要规则配备自动化检查。优先级明确：可自动化lint检查的 > 写入AGENTS.md的 > 口头约定的。

AGENTS.md并非一份撰写完毕即锁定的文档，它需要伴随项目演进持续调整与优化。

总结与展望

回顾这半年的实践，AGENTS.md的本质是以最小的上下文成本，赋予AI工具对项目的最大理解。撰写它的关键不在于“多”，而在于“准”——堵住AI最易犯错之处，将AI最需的信息置于最易寻得之地。

AGENTS.md + 文档体系 + lint脚本 + 启动脚本 + 验证规范，本质上是在构建一个高效的反馈回路：AI读取AGENTS.md理解项目 → 编写代码 → 自动检查 → 启动验证 → 依据结果修正。人类的角色是设计并维护这个回路，而非在回路的每一步都亲力亲为。

还有一个意外收获——维护AGENTS.md的过程本身就是一种知识沉淀。过去团队的编码规范散落在Wiki、聊天记录与口头约定中，新人入职需耗费大量时间摸索这些“潜规则”。如今，它们被结构化地写入AGENTS.md及配套文档。虽然初衷是服务于AI，但团队成员同样从中受益。

某种意义上，为AI撰写AGENTS.md的过程，也是对团队知识进行一次彻底梳理的过程。这或许是它最被低估的价值。

若你尚未为项目创建AGENTS.md，现在即可开始——使用/init生成一份初始版本，随后在日常使用中，每遇到一个AI bad case，便补充一条规则。无需多久，你便能拥有一份真正实用的AGENTS.md。

来源：互联网