让AI Coding效率翻倍：AGENTS.md实战指南（附模板）

一站式接入主流 AI 大模型，支持对话 · 生图 · 生视频，即开即用

ChatGPT Claude Gemini Grok DeepSeek 通义千问 Ollama

AI写代码时跨层调用、手动构造响应体、甚至直接抛出RuntimeException？问题不在模型不够强，而在项目知识散落在人的脑子里，而非AI能读到的地方。GitHub 6万+项目已采用的 AGENTS.md 它不是给人看的README，而是给AI看的项目指令集。

一、为什么需要AGENTS.md？

AI Coding的四大痛点

上下文割裂：前后端分属不同仓库，AI无法全栈理解
私域组件盲区：闭源组件库无训练数据，AI用错Props
规矩不透明：异常处理/分层架构等规范仅存于团队脑中
验证闭环断裂：AI改完代码不知如何启动验证

核心矛盾：项目的知识和规范存在于人的脑子里，而不是存在于 AI 能读到的地方。

二、AGENTS.md核心原则：地图，而非手册

渐进式披露（Progressive Disclosure）

写进AGENTS.md：

项目全貌（技术栈/仓库结构/核心模块）
硬性规则（违反即报错的编码规约）

通过链接指向详细文档：

模块开发规范 → docs/module-guide.md
私域组件用法 → reference-projects/components/

判断标准：

AI不知道就会

写错代码

→ 放AGENTS.md

只会

写得不够好

→ 放详细文档，AGENTS.md留链接

三、五大实战技巧（附代码模板）

技巧1：仓库聚合 —— 解决上下文割裂

方案：

存量项目：脚本聚合（setup-repos.sh克隆前端到后端子目录）
新项目：直接monorepo

project-root/
├── backend/       # Spring Boot
├── frontend/      # React
└── docs/          # 用户手册（AI同步更新）

效果：AI在单窗口实现全栈编码，自动同步更新用户文档。

技巧2：统一环境配置 —— 让AI能启动项目

方案：

环境变量统一存~/.myproject_env（避免误提交）
启动脚本封装复杂逻辑

### 快速命令
./scripts/start-server.sh  # 构建+启动+健康检查
./scripts/run-tests.sh    # 执行全量测试

关键：把复杂操作封装成单条命令，降低AI认知负担。

技巧3：验证闭环 —— 改完代码不算完

后端验证规范：

# Step1: 登录 → 写临时文件
curl -X POST /login -d '{"user":"test"}' > /tmp/login.json
# Step2: 提取token → 验证接口
TOKEN=$(python3 -c "import json; print(json.load(open('/tmp/login.json'))['token'])")
curl -H "Authorization: Bearer $TOKEN" /api/data | python3 validate.py

前端验证：

用Agent Browser能力（如Qoder的agent-browser）自动截屏比对

效果：AI产出从“能编译”升级为“能跑通”。

技巧4：自动化检查 —— 规则要有执行力

分层依赖检查脚本（scripts/lint-deps.sh）：

# 检查service层是否误引entity
if grep -r "import.*entity" backend/service/; then
  echo "✗ service/ 导入了 entity/ → 违反分层架构"
  echo "HOW: 将DTO放在common/，通过DTO传递数据"
  exit 1
fi

集成到Makefile：

lint-arch: ./scripts/lint-deps.sh
lint-format: prettier --check .

错误信息格式：WHAT + WHY + HOW → AI可直接修复。

技巧5：参考项目引入 —— 给AI喂够上下文

方案：

创建reference-projects/目录，git submodule引入私域组件源码
配套架构说明文档（docs/ref-components.md）

## 参考项目导航
- `reference-projects/pro-components/`：私域React组件库
  - 关键文件：`Table/index.tsx`（ProTable实现）
  - 使用规范：必须传`rowKey`，分页用`pagination`而非`pageSize`

为什么有效：源码永远不会过时，它就是最准确的文档。

四、AGENTS.md模板（200行内）

# AGENTS.md

## 项目概述
- 技术栈：Spring Boot 3.2 + React 18 + TypeScript
- 仓库结构：monorepo（backend/frontend/docs）
- 核心模块：auth（认证）、billing（计费）、monitor（监控）

## 硬性规则（违反即报错）
1. **异常处理**：必须抛`BusinessException`，禁止`RuntimeException`
2. **分层架构**：
   - Controller → Service → Repository
   - 禁止Controller直连Repository
3. **响应体**：禁止手动构造，使用`@ApiResponse`注解

## 快速命令
- `./scripts/start-server.sh`：启动全栈服务
- `make lint-arch`：检查分层依赖
- `make lint-format`：格式化代码

## 验证规范
- 后端：用`/tmp/`临时文件传递curl结果
- 前端：通过Agent Browser验证页面渲染

## 参考项目
- 私域组件：`reference-projects/pro-components/`
- 网关内核：`reference-projects/gateway-core/`

## 详细文档
- [分层架构详解](docs/architecture.md)
- [ProTable使用指南](docs/pro-table.md)
- [API设计规范](docs/api-design.md)