AI Agent开发半年心得 决定成败的关键文件解析

过去半年，我为自己负责的多个项目——包括中后台业务系统、底层框架、SDK和文档站点——都补充了一份关键的AGENTS.md文件。

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

那么，一份真正有效的AGENTS.md究竟该如何撰写？本文将分享我实践下来最核心的五个心得，帮助你系统性地提升AI在项目开发中的理解和协作效率。

如果你正在使用Cursor、Claude Code、Qoder、灵码或GitHub Copilot等AI编程工具，却总觉得它们不够“懂”你的项目细节，那么这篇文章或许能帮你捅破这层窗户纸。

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

要理解AGENTS.md的价值，需要回顾近一年的发展脉络。

这个概念最初由Anthropic的Claude Code普及——它在运行时会自动读取项目根目录下的CLAUDE.md文件，并将其内容作为上下文注入给AI模型。

方法简单直接，效果却立竿见影。你维护得越用心，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，但其内容与AGENTS.md完全通用，仅需一行ln -s AGENTS.md CLAUDE.md命令即可实现软链接兼容。

痛点剖析：缺乏AGENTS.md时，AI为何表现“笨拙”

让我分享一些真实的痛点。在为中后台业务系统初次引入AI编程助手时，体验相当尴尬：工具虽在，效率提升却远不及预期。问题根源并非工具本身，而在于项目对AI极不友好。

第一，前后端上下文割裂。后端与前端分属两个独立的Git仓库。当需要修改一个前后端联动的功能时，开发者不得不在两个编辑器窗口间频繁切换。AI一旦切换上下文就会丢失关键信息，迫使你反复重新描述背景，效率大打折扣。

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

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

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

所有这些痛点的共同根源在于：项目的关键知识与规范仅存在于人脑之中，而非AI能够直接读取和理解的载体里。

核心理念：提供导航地图，而非操作手册

在动手撰写之前，必须确立一条核心原则——AGENTS.md应当是一张“导航地图”，而非一本详尽的“操作手册”。

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

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 + TypeScript）
    user-guide/                  # 用户手册（Markdown）
    reference-projects/          # 参考项目（git submodule）
    scripts/                     # 构建、启动、检查脚本
    docs/                        # 架构与设计文档

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

将用户手册仓库一并纳入还带来了意外收获：如今用户手册大多由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智能体在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编程工具基本均已支持），让智能体自行打开浏览器、操作页面、进行截图对比。这比让AI猜测CSS问题要高效得多。

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

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

写在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开始，以错误案例驱动迭代

切勿试图一次性撰写一份完美的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错误案例，便补充一条相应规则。无需多久，你便能拥有一份真正实用、高效的AGENTS.md。