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

核心观点

本文围绕一个核心问题展开：怎么写好一份 AGENTS.md？ 作者以管控系统（Spring Boot + React前后端分离）为实例，结合半年多个项目维护经验，提出了一套完整的 AGENTS.md 方法论。核心理念用一句话概括：AGENTS.md 是地图，不是手册（Map, not Manual）——控制在200行的导航地图，告诉Agent"去哪找什么"，详细内容放在链接文档里。

AGENTS.md 前世今生

起源

概念最早由Anthropic通过Claude Code的CLAUDE.md普及——运行时自动加载当前目录下的CLAUDE.md注入请求。这形成正向循环：维护好→表现好→更愿意用→更愿意维护。

碎片化时代

统一标准

2025年5月Sourcegraph提议统一为AGENT.md，OpenAI买下agents.md域名提议复数形式AGENTS.md（理由：多Agent共用），AMP让步对齐。最终AGENTS.md成为事实标准，由Linux Foundation下属Agentic AI Foundation托管。截至2026年初，GitHub上超6万开源项目使用。Claude Code仍用CLAUDE.md但内容通用，ln -s AGENTS.md CLAUDE.md即可兼容。

没有AGENTS.md的四大痛点

1. 前后端上下文割裂

前后端分属不同仓库→AI只能打开一个仓库→切换丢失上下文→重新描述背景→效率低。

解决：monorepo，AI同一窗口看到Controller定义和前端API调用。团队不再区分前后端。

2. AI不认识私域组件

闭源组件库（ProTable/ProForm/ProAction）不在训练数据中，维护文档总滞后于实现。

解决：直接把组件库源码放进参考项目。源码永远不会过时，就是最准确的文档。

3. AI不知道项目规矩

异常用BusinessException还是RuntimeException、响应体统一包装还是手动构造、分层禁止跨层——AI不知道这些"潜规则"，每次人工纠正完下次还犯。

4. AI不会启动项目不会自测

每人本地环境配置方式不统一，启动命令散落各处。AI改完代码只能停下来等人验证，工作闭环断裂，夜间自主执行不可能。

共同根源：项目的知识和规范存在于人的脑子里，而不是存在于AI能读到的地方。

核心理念：渐进式披露

写进AGENTS.md的内容（仅两类）：

1. AI理解项目全貌的必要信息——技术栈、仓库结构、核心模块、分层架构
2. 违反会直接导致问题的硬性规则——编码规约、命名约定、禁止项

不写进去的内容：通过文档链接指向：

AGENTS.md（地图）
  → docs/architecture.md          分层架构详细说明
  → docs/development.md           开发环境搭建
  → docs/design-docs/ref-*.md     参考项目架构说明
  → docs/design-docs/*-patterns.md 组件使用模式

判断标准：AI不知道就会写出错误代码→放AGENTS.md；只是不够好→放docs/，AGENTS.md放链接。

五大实践

实践一：仓库聚合

从三仓分离→脚本聚合（frontend/ gitignore）→monorepo重构：

project-root/
  server/              # 后端（Spring Boot）
  web/                 # 前端（React + TypeScript）
  user-guide/          # 用户手册（AI基于代码生成）
  reference-projects/  # 参考项目（git submodule）
  scripts/             # 构建启动检查脚本
  docs/                # 架构文档设计文档

额外收益：AI可直接基于代码变更同步更新用户手册。

实践二：统一环境配置

所有环境变量统一配置在~/._env（纯KEY=VALUE），启动脚本自动source。配套一键启动脚本封装JDK检测/优雅关闭/健康检查：

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

实践三：验证闭环

curl验证规范（解决AI在shell中的兼容性问题）：

• 每个curl独立执行，禁止串联
• 用临时文件传递数据（避免zsh管道glob问题）
• Token获取模板化
• 排查路径明确

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

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

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

前端验证：Agent Browser能力（打开浏览器/操作页面/截屏对比）。

核心：写完代码不算完，自测过功能才算完——验证闭环是夜间Agent自主执行的前提。

实践四：自动化检查

分层依赖检查：shell脚本扫描Java import判断层级违规，输出WHAT+WHY+HOW格式：

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

质量检查命令矩阵：

lint-arch:    ./scripts/lint-deps.sh  # 分层依赖检查
lint-format:  mvn spotless:check      # 格式检查
format:       mvn spotless:apply      # 格式修复
build:        mvn package -DskipTests # 构建
test:         mvn test                # 测试

规则优先级：能自动化检查的 > 写在AGENTS.md中的 > 口头约定的

实践五：参考项目引入

通过git submodule引入：

reference-projects/
  higress/              # 开源网关内核源码
  nacos/                # 注册配置中心源码
  pro-components/       # 私域组件库源码
  other-product-*/      # 其他产品前后端
  himarket/             # 开源AI开放平台

配合每个参考项目的架构说明文档（docs/design-docs/ref-*.md）作为"地图"——ref文档AI基于源码生成。

AGENTS.md模板（建议≤200行）

# 项目概述（3-5行）
# 仓库结构（目录树+注释）
# 快速命令（构建/启动/测试/lint）
# 分层架构约束（禁止项+lint脚本路径）
# 编码规约（必须遵守的硬性规则）
# 文档引用（→ docs/下各专题文档）
# 参考项目（优先级+用途说明）

实施建议

1. 从/init或harness-creator开始：自动扫描项目结构生成初始版本
2. Bad Case驱动迭代：AI犯错→判断全局规则(AGENTS.md)还是模块细节(docs/)→补充
3. 规则要有执行力：重要规则必须有对应自动化检查
4. 团队共建：遵循"地图"原则，细节文档不塞进AGENTS.md
5. 标注读者：README给人、AGENTS.md给AI、scripts共用

关键引用

"什么都重要的时候，什么都不重要。"

"源码永远不会过时，它就是最准确的文档。"

"AI不知道这条信息就会写出错误代码→放AGENTS.md；只是不够好→放详细文档。"

"为AI写好AGENTS.md的过程，也是在为团队做一次知识梳理。"

关键概念

• CLAUDE.md
• Harness Engineering
• Context Engineering
• Agent
• All In Code
• 验证闭环

关联页面

• Harness Engineering-耗时一周AI Coding率提升至90
• Agent时代的生产力悖论-当协作本身成为最大的瓶颈
• 告别氛围编程-Harness治理与SDD团队级AI研发实践
• 深度解析Claude Code在Prompt_Context_Harness的设计与实践