夜雨聆风AI 编程助手最常见的翻车现场是什么？不是不会写代码，而是不懂你的项目：不知道构建命令、不知道代码规范、不知道哪些目录不能动，于是乱改文件、跑错命令、提交一堆"自作聪明"的改动。今天 Hacker News 热帖还在讨论要不要给 AGENTS.md 加官方支持，GitHub 上的"Agent 技能"类项目也在疯涨——AGENTS.md 正在成为 AI 编程时代的项目说明书标配。这篇文章用 3 步给你讲清楚。
AGENTS.md 是一个放在仓库根目录的 Markdown 文件，专门写给 AI 编程助手看：Claude Code、Codex、Cursor 等工具启动时会自动读取它，把里面的约定当作"项目背景"来理解你的代码。它解决的核心问题是：AI 助手没有长期记忆，每次都是新会话，你不想每次对话都把项目规则重复一遍。
第 1 步：创建 AGENTS.md 并写清四个板块
在项目根目录新建 AGENTS.md，按这个模板写：
# 项目概览一句话说明这个项目做什么、技术栈是什么。# 常用命令- 安装依赖: npm install- 本地启动: npm run dev- 跑测试: npm test- 构建: npm run build# 代码规范- 使用 TypeScript，禁止 any- 组件命名用 PascalCase，文件用 kebab-case- 提交信息遵循 conventional commits# 禁区（重要）- 不要修改 src/legacy/ 下的代码- 不要直接提交 .env 文件- 涉及数据库迁移必须先和负责人确认第 2 步：把"边界"写清楚，越具体越好
AI 助手最怕模糊指令。把约束写成"能机器判断"的规则，比如"测试必须通过才能提交"、"新增依赖需在 PR 描述里注明理由"。如果你希望 AI 在动手前先给方案，可以加一条：
# 工作方式- 修改超过 3 个文件前，先输出改动计划- 每次改动后运行 npm test 验证- 不确定的地方直接提问，不要猜测第 3 步：验证助手真的读到了
启动你的 AI 编程助手，直接问一句："这个项目怎么跑起来？"如果它能准确说出 npm run dev 和项目结构，说明 AGENTS.md 生效了；如果答得含糊，检查文件是否在仓库根目录、文件名是否拼写正确（区分大小写），以及助手是否开启了自动读取功能。改完规则后再问一次，确认新约束生效。
常见失败与处理
• 助手不读文件：确认 AGENTS.md 在仓库根目录；部分工具需要在设置里打开"读取项目文档" • 规则互相冲突：把最关键的约束放在文件最前面，AI 通常优先遵守靠前的指令 • 命令写错了：所有命令写完后，自己在终端跑一遍验证，别让 AI 照着错误命令执行 • 文件越来越大：超过 200 行就按模块拆成 docs/下的多个文件，在根目录 AGENTS.md 里引用
适合谁：任何在用或准备用 AI 编程助手的开发者——半小时的投入，换来的是每天少跟助手重复十次项目背景。验证成功的标准很简单：换一个新会话，助手还能准确说出你的项目规矩。
