AI 写错代码？问题出在你的上下文

用了 AI 编码工具，产出还是一塌糊涂？ 不是模型不够强，是你没给它一张正确的地图。

AGENTS.md：导航地图，不是使用手册

很多团队犯同一个错误——把所有规则塞进一个文件。结果 AI 注意力被稀释，真正关键的规则反而被忽略。

判断标准只有一条：

AI 不知道就会写出错误代码 → 放 AGENTS.md；只是写得不够好 → 放详细文档，AGENTS.md 放链接。

控制在 200 行以内，告诉 Agent「去哪里找什么」，详细内容放在链接的文档里。结构清晰胜过内容详尽。

写进去的内容：

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

其他内容一律通过链接指向专题文档：

AGENTS.md
  → docs/architecture.md        # 分层架构详细说明
  → docs/development.md         # 开发环境搭建
  → docs/design-docs/ref-*.md   # 参考项目架构说明

仓库聚合：打破前后端的上下文割裂

把后端、前端、用户手册、参考项目全部收进同一个repo：

project-root/
  server/             # 后端（Spring Boot）
  web/                # 前端（React + TypeScript）
  user-guide/         # 用户手册（Markdown）
  reference-projects/ # 参考项目（git submodule）
  docs/               # 架构文档、设计文档

AI 在同一窗口就能看到 Controller 接口定义和对应的前端 API 调用，实现真正的全栈编码。

额外收益：用户手册也放进来，AI 改完功能代码后顺手更新文档，不再需要单独维护一份说明。

Agent 自动验证：跑通接口才算完

“代码写完” 不等于 “功能可用”。完整的验证闭环是：

改代码 → 构建 → 启动 → curl 验证 → 断言结果

curl 验证的本质不是"发请求"，是脚本化真实请求 + 结果断言。验证真正发生在断言这一步——返回字段存在、数据非空、状态码正确，缺一不可。

注意：curl 只是“请求”，验证真正发生在“断言”

这套验证流程直接接入 CI/CD：每次 commit 触发构建、测试、接口验证，问题在集成前暴露，不在生产环境爆炸。

# 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 调用业务接口
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
    
# Step 4：校验结果（关键步骤）
python3 -c "
import json
data=json.load(open('/tmp/result.json'))
assert data['code']==0
assert len(data['data']) > 0
"

CI/CD：把验证闭环接入自动化流水线

单次验证靠手动，持续质量靠 CI/CD。它是一套把「代码提交 → 构建验证 → 自动发布」全流程自动化的体系。
CI（持续集成）：保证代码始终可用
触发时机：每次 commit / merge，自动执行构建、测试、接口验证三步。本质是提前发现问题，避免集成后才爆炸。
CD（持续交付 / 持续部署）：保证变更能快速上线
两种形态按团队成熟度选择：持续交付在构建完成后自动部署到测试/预发环境，上生产需人工确认；持续部署则构建通过后直接发布到生产。本质是把上线发布变成标准化、可重复的操作。

完整流水线：

代码提交
   ↓
CI：构建 + 测试 + curl 验证
   ↓
CD：部署到环境（test / prod）
   ↓
运行验证（健康检查 / 监控）

自动化检查：让规则真正有执行力

架构分层规则写进文档没用，必须用脚本强制校验。错误信息要同时给人和 AI 看，格式必须包含三要素：

• WHAT：违反了什么规则
• WHY：为什么不允许
• HOW：怎么修复

AI 读到这条错误后，可以直接按照 HOW 的指引修复，无需额外上下文，一次到位。

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

---

AGENTS.md 编写模板

建议控制在 200 行以下。超过这个范围，考虑将细节拆分到 docs/ 下的专题文档。

## 1. 项目概述
一段话说清楚：项目是什么、技术栈、仓库结构。
前 10 行必须让 AI 建立项目心智模型。

## 2. 快速命令
构建、启动、格式化、质量检查的命令速查表。
环境变量配置说明（env 文件位置、启动脚本自动 source）。

## 3. 后端架构
包结构树（ASCII）+ 每个包的用途注释。
核心子系统的简要说明 + 详细文档链接。
前后端术语映射（如有差异）。

## 4. 前端架构
技术栈、路由方案、API 层约定、组件库规范。
详细文档链接。

## 5. 关键约定
5-10 条硬性编码规则（违反会直接导致问题的）。
每条规则附详细文档链接。

## 6. 本地开发及验证流程
「改 → 构建 → 启动 → 验证」的完整闭环。
curl 验证模板、Token 获取、日志路径。

## 7. 质量检查
lint、format、build、test 命令矩阵。

## 8. 参考项目约定
参考项目列表 + 优先级规则。

## 9. 文档导航
所有详细文档的索引表。

举例：

## 1. 项目概述
  一段话：项目定位、技术栈（Spring Boot + React）、monorepo 结构

## 2. 快速命令
  构建、启动、格式化、质量检查命令速查表
  环境变量配置：~/.<project>_env 优先级说明

## 3. 后端架构
  包结构树（ASCII）+ 每个包的用途注释
  核心子系统简要说明
  → 详见 docs/architecture.md

## 4. 前端架构
  技术栈、路由方案、API 层约定、组件库规范
  → 详见 docs/design-docs/frontend-architecture.md

## 5. 关键约定
  - 异常统一用 BusinessException，禁止直接抛 RuntimeException
  - 响应体由框架统一包装，禁止手动构造
  - 分层架构禁止跨层依赖（make lint-arch 自动检查）
  - 代码风格：Spotless + Google Java Format
  - 安全：无状态 JWT
  → 每条规则附详细文档链接

## 6. 本地开发及验证流程
  「改 → 构建 → 启动 → 验证」完整闭环
  curl 验证模板、Token 获取、日志路径
  → 详见 docs/design-docs/api-verification.md

## 7. 质量检查
  make lint-arch / lint-format / format / build / test

## 8. 参考项目约定
  参考项目列表 + 优先级规则

## 9. 文档导航
  所有详细文档的索引表（architecture / design-docs / ref-*

上下文质量决定 AI 产出质量。把"告诉 AI 该怎么工作"当成一个工程问题来做，收益远超换一个更强的模型。

你的项目有 AGENTS.md 吗？欢迎评论区分享你的实践。