Code Agent不听话？一个文件让它乖乖按你的规矩来
Code Agent不听话？一个文件让它乖乖按你的规矩来
上周五下午4点，我让Claude Code给一个Python项目加个用户导出功能。它5分钟写完了，跑起来也没毛病。但我一看代码——全裸的except: pass，密钥直接硬编码在config.py里，日志一行没写。
我花20分钟把这些毛病改完，心想：下次它还会犯同样的错。
答案是会。而且每次都犯。
直到我在项目根目录扔了一个AGENTS.md文件，情况才彻底改观。
AGENTS.md到底是个啥
简单说，它就是一个放在项目根目录的规矩文件。Code Agent（Claude Code、Cursor、Copilot这类工具）启动时会自动读取它，然后按照里面的规矩干活。
不是README，不是文档，是规矩。
你写README.md是给新同事看的，告诉他们"这个项目是干嘛的"。你写AGENTS.md是给AI看的，告诉它"在这个项目里，你必须怎么做，绝对不能怎么做"。
为什么需要这玩意
我做了个实验。同一个任务——"给FastAPI项目加一个文件上传接口"，分别在有AGENTS.md和没有的情况下让Claude Code执行。
没有AGENTS.md的结果：
except Exception: pass（1处）有AGENTS.md的结果：
同一个模型，同一个提示词，差距就这么大。原因很简单：AI需要具体的、可执行的约束，而不是"写好代码"这种废话。
怎么写一个管用的AGENTS.md
我摸索了一个月，总结出一个模板。直接上干货：
# AGENTS.md
## 项目概述
这是[项目名]，一个[一句话描述]。技术栈：Python 3.11 + FastAPI + PostgreSQL。
## 核心规则（违反即打回）
### 1. 异常处理
- 禁止 `except: pass`、`except Exception: pass`
- 捕获具体异常类型，每种异常有对应的错误处理
- 关键操作必须有try/finally确保资源释放
- 所有异常必须记录日志
### 2. 输入校验
- 所有外部输入（API参数、文件、用户数据）必须校验
- 使用Pydantic模型做参数校验，不要手动if/else
- 文件上传必须校验：大小（<10MB）、类型（白名单）、扩展名
### 3. 日志规范
- 使用structlog，不用print
- 关键路径必须记录：请求进入、数据库操作、外部调用、异常
- 每条日志带request_id
- 日志格式：JSON，方便ELK收集
### 4. 代码风格
- 所有函数必须有类型标注
- 使用dataclass或Pydantic，不要裸dict传参
- 常量用大写，放config.py，禁止硬编码
- 数据库操作用SQLAlchemy ORM，禁止裸SQL
## 禁止事项
- 禁止在代码中硬编码密钥、密码、token
- 禁止用 `os.system()` 执行命令，用 `subprocess.run()`
- 禁止用 `from module import *`
- 禁止在生产代码中留 `TODO`、`FIXME`、`XXX`
## 文件结构src/
api/ # 路由层，只做参数接收和响应返回
services/ # 业务逻辑层
models/ # 数据模型
utils/ # 工具函数
tests/ # 测试文件，与src结构对应
## 测试要求
- 新功能必须写测试，覆盖率不低于80%
- 测试用pytest，放在tests/目录
- 测试命名：test_{功能}_{场景}_{预期结果}这个模板有几个关键设计：
1. 规则分层
"核心规则"是红线，违反就打回。"禁止事项"是底线，碰都不能碰。这种分层比一锅粥列20条规则有效得多——AI会优先关注标"禁止"的内容。
2. 具体到可执行
"写好代码"是废话。"禁止except: pass，捕获具体异常类型"是规矩。AI需要的不是方向感，是检查清单。
3. 跟项目绑定
每个项目的AGENTS.md应该不一样。FastAPI项目写FastAPI的规矩，Vue项目写Vue的规矩。通用模板可以共用，但技术栈特定的规则必须定制。
几个实战踩坑
坑1：规则太多反而没用
我一开始写了47条规则。结果AI要么漏掉几条，要么为了满足所有规则把代码写得巨复杂。
后来砍到15条核心规则，效果反而好了。原因：AI的上下文窗口有限，规则太多会稀释优先级。
经验：核心规则不超过20条，宁可少而精。
坑2：规则之间会冲突
我写过"所有函数不超过30行"和"每个错误路径必须有独立的处理逻辑"。结果AI为了把错误处理塞进30行，用了各种嵌套和跳转，代码反而更难读。
经验：写完规则后，自己假装是AI走一遍，看看有没有互相打架的。
坑3：AGENTS.md不是一劳永逸的
项目在变，规矩也得变。我现在的做法是：每次Code Review发现问题，就把对应的规矩加进AGENTS.md。相当于用Review经验训练AI。
# 我的迭代流程
# 1. Code Review发现AI犯了某个错
# 2. 把对应的规矩加进AGENTS.md
# 3. 下次AI就不会再犯同样的错坑4：不同目录需要不同规矩
大项目里，前端和后端的规矩肯定不一样。我的做法是用多层AGENTS.md：
project/
AGENTS.md # 全局规则
backend/
AGENTS.md # 后端专属规则（覆盖全局的同名规则）
frontend/
AGENTS.md # 前端专属规则Code Agent会自动合并这些文件，子目录的规则优先级更高。
效果量化
我在3个项目上跑了2个月，统计了Code Review的打回率：
指标无AGENTS.md有AGENTS.md下降幅度 异常处理问题12次/月2次/月83% 输入校验缺失8次/月1次/月87% 硬编码问题5次/月0次/月100% 日志缺失15次/月3次/月80% 总打回率40%8%80%打回率从40%降到8%。最直接的好处不是代码质量提升——那个是附带的——而是我花在Review上的时间从每周6小时降到了每周1.5小时。
跟其他方案的对比
你可能会想：Cursor Rules、.cursorrules、Copilot Instructions这些不也是干这个的吗？
是的，但AGENTS.md有一个优势：它是工具无关的。
.cursorrules只对Cursor生效，.github/copilot-instructions.md只对Copilot生效。AGENTS.md目前被Claude Code、Hermes Agent、Windsurf等多个工具支持，而且正在成为事实标准。
我在项目里只维护一份AGENTS.md，不管团队成员用什么AI工具，规矩都一样。
一个完整的实战案例
这是我最近一个真实项目的AGENTS.md，做的是内部的API网关：
# AGENTS.md - API Gateway
## 项目
内部API网关，处理请求路由、鉴权、限流、日志。
技术栈：Go 1.22 + Gin + Redis + PostgreSQL。
## 核心规则
### 性能
- 所有中间件必须在1ms内完成（不含下游调用）
- Redis操作必须设置超时，默认200ms
- 数据库查询必须有索引，禁止全表扫描
- HTTP客户端必须设置连接池：MaxIdleConns=100, MaxIdleConnsPerHost=10
### 安全
- 所有外部输入必须校验和清洗
- SQL查询必须用参数化，禁止字符串拼接
- 敏感数据（token、key）在日志中必须脱敏
- CORS配置必须白名单，不能用 `*`
### 可观测性
- 每个请求必须有trace_id，贯穿全链路
- 关键指标必须暴露Prometheus格式：请求量、延迟、错误率
- 日志必须包含：trace_id、method、path、status、latency_ms
### 错误处理
- 所有错误必须返回统一格式：`{"code": "ERR_XXX", "message": "..."}`
- 内部错误不暴露堆栈给客户端
- 超时必须有明确的错误码，不是500这个文件只有30行，但覆盖了API网关最核心的4个维度：性能、安全、可观测性、错误处理。AI每次生成代码时都会自动遵守这些规矩。
写在最后
AGENTS.md不是银弹，AI还是会犯错。但它把犯错的概率从"经常"降到了"偶尔"，把Review的重点从"基础规范"提升到了"业务逻辑"。
如果你现在每天花超过1小时在Code Review上纠正AI的基础错误，试试在项目根目录放一个AGENTS.md。花30分钟写规矩，能省你30小时的Review时间。
这笔账，怎么算都划算。
关注「安全值班室」公众号
每天一篇AI安全早报 + 实战攻防案例
浙公网安备 33010602011771号