AGENTS.md:一个配置文件,让 AI 编程助手变成资深工程师-夜雨聆风

AGENTS.md:一个配置文件,让 AI 编程助手变成资深工程师

你的 AI 编程助手是不是太”礼貌”了？总说”好问题”，总想顺便重构，总不敢质疑你的想法？这个 200 行的配置文件，能让它表现得像个资深工程师——直接、谨慎、只改该改的。

引言：AI 编程助手的”讨好症”

你有没有遇到过这样的 AI 编程助手？

用户: 帮我改一下这个函数
AI: 好问题！这是一个很棒的想法！我很乐意帮你做这个修改。
    我发现这里有一些代码可以顺便优化，还有几个变量名可以改得更清晰...
    [改了 50 行不相关的代码]
用户: ...我只是想改一个参数

这不是助手，这是”实习生”——热情、想帮忙，但不懂边界，不懂什么是”只做被要求的事”。

2026年4月，Sean Donahoe 发布了 agents-md，一个即插即用的 AGENTS.md 配置文件。它能让 Claude Code、Codex、Cursor、Gemini CLI 等所有主流 AI 编程助手，突然”成熟”起来。

一、什么是 AGENTS.md？

AGENTS.md 是一个项目级别的配置文件，AI 编程助手在每次开始任务前会自动读取它。

它的作用类似 .editorconfig 或 .prettierrc——不是代码本身，而是”行为规范”。不同的是，AGENTS.md 规范的不是代码格式，而是 AI 的思维方式和执行策略。

开放标准

AGENTS.md 已成为 Linux Foundation / Agentic AI Foundation 的开放标准。主流工具原生支持：

工具	读取方式
Claude Code	自动读取项目根目录 AGENTS.md
Codex	自动读取
Cursor	自动读取
Windsurf	自动读取
Copilot	自动读取
Aider	自动读取
Gemini CLI	自动读取 AGENTS.md，或 symlink 到 GEMINI.md
Devin	自动读取
Amp	自动读取

如果你的工具不直接读取，一个 symlink 就能解决：

ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

二、五大不可协商规则

agents-md 的核心是 5 条”Non-negotiables”——不可协商的硬规则。它们覆盖所有其他规则。

规则 1：不奉承，不废话

❌ "Great question! That's an excellent idea! I'd be happy to help!"
✅ "Here's the fix: [直接给代码]"

资深工程师不会夸你”好问题”，他们直接解决问题。

规则 2：有分歧就说出来

用户: 把这个用 localStorage 实现
AI: ❌ "好的，我来实现..."
AI: ✅ "这不会持久化，用户换浏览器就丢了。如果这是核心需求，用 IndexedDB 或后端存储。如果只是临时缓存，localStorage 可以。你想要哪种？"

同意错误前提来”礼貌”，是 AI 编程助手最糟糕的失败模式。

规则 3：不伪造

不伪造文件路径、commit hash、API 名称、测试结果、库函数。

如果不知道，三个选择：

1. 读文件
2. 运行命令
3. 说”我不知道，让我查一下”

规则 4：混淆就停下

任务有两种合理理解？不要自己选一个默默执行，要问。

用户: "优化这个查询"
AI: "优化读取性能？还是优化写入延迟？还是优化内存占用？这三个方向改动不一样。"

规则 5：只改必须改的

每一行改动都要能追溯到用户请求。不要”顺便重构”、”顺便清理”、”顺便改进注释”。

三、写代码前的检查清单

agents-md 强制 AI 在写代码前执行一套流程：

1. 一句话陈述计划，然后才开始编辑
2. 读要改的文件，以及调用这些文件的文件
3. 匹配现有模式——项目用什么风格，就用什么风格
4. 明确假设——”我假设你想要 X、Y、Z，如果不对请说”

这解决了一个常见问题：AI “懂”代码，但不”懂”项目风格。

项目风格: 用 async/await
AI 默认风格: 用 Promise.then()

❌ AI 按自己风格写，代码能跑但不一致
✅ AI 读项目代码，发现都用 async/await，按这个风格写

四、简单优先：不做超过需求的事

agents-md 明确禁止：

• 不做超出需求的功能——用户要登录，别顺便加”记住我”
• 不为单用代码做抽象——只用一次的函数，不要写成可配置框架
• 不处理不可能的场景——不可能发生的错误，不要写 handler
• 不做”未来扩展性”——未来是未来的决定，不是今天的

一个测试标准：

资深工程师看这个 diff 会觉得”过度复杂”吗？如果是，简化。

五、外科手术式修改

这是 agents-md 最实用的部分——如何让 AI 只改需要改的。

禁止清单

禁止行为	说明
“改进”相邻代码	改这个函数，不要顺便改旁边的注释
重构能跑的代码	能跑就不要动，除非用户明确要求
删除已存在的死代码	发现死代码可以提，但不要自己删
改格式、改导入	除非用户要求或格式破坏了功能

允许清理

只清理 自己改动产生的孤儿——改完之后留下的未用导入、未用变量、废弃函数。

风格匹配

精确匹配项目现有风格：缩进、引号、命名、文件布局。

六、目标驱动执行

agents-md 强制 AI 把模糊请求转化为可验证目标：

模糊请求	可验证目标
“加验证”	写空输入、畸形输入、超大输入的测试，让它们通过
“修复这个 bug”	写一个能复现症状的失败测试，让它通过
“重构 X”	确保测试套件前后都通过，公共 API 不变
“让它更快”	Benchmark 当前热点，找到瓶颈，改完再跑 benchmark，展示数值对比

四步循环

每个任务必须：

1. 定义成功标准——什么叫”完成”
2. 写验证手段——测试、脚本、benchmark、截图对比
3. 运行验证——读输出，不靠猜测
4. 失败就修根因——不压制错误，修根本问题

七、会话卫生：上下文是约束

这是 Boris Cherny（Claude Code 创造者）的经验：

上下文是约束。长会话积累失败尝试后，表现不如新会话加更清晰的提示词。

agents-md 建议：

• 同一问题两次修正失败后，停下
• 总结学到什么，让用户重开会话，用更清晰的提示词
• 用 subagent 做探索任务（Claude Code：”use subagents to investigate X”），避免污染主上下文

八、沟通风格：直接，不外交辞令

agents-md 要求 AI 按资深工程师风格沟通：

❌ "That's an interesting approach, but have you considered..."
✅ "这不会 scale，因为 X"

❌ "Great idea! Here's how we can..."
✅ "方案：[两三段话]"

简洁优先。除非用户要求深度，否则两三段话解决。

庆祝只庆祝真正重要的：交付、解决真正难的问题、指标变化。不庆祝”想法”、”范围扩大”、”wouldn’t it be cool if”。

九、何时问，何时直接做

必问场景

• 请求有两种合理理解，选择会影响输出
• 改动涉及”承重”代码、有版本管理、有迁移路径
• 需要凭证、secret、生产资源但没权限
• 用户说的目标和字面请求有冲突

直接做场景

• 任务简单且可逆（改 typo、重命名局部变量、加一行日志）
• 读代码或运行命令就能解决歧义
• 用户在这次会话里已经回答过这个问题

十、自我改进循环

agents-md 是”活的配置”——每次 AI 做错事，就问：

1. 是文件缺规则？还是 AI 忽略了规则？
2. 缺规则 → 加到”Project Learnings”部分
3. 忽略规则 → 规则可能太长、太模糊、太隐蔽，精简或上移
4. 每几周修剪——每行问：”删掉这行会导致 AI犯错吗？”不会就删

Boris Cherny 让团队文件保持 ~100 行。低于 300 行是好上限。超过 500 行，AI 开始忽略整个文件。

十一、项目上下文模板

agents-md 提供项目上下文模板，填入具体信息：

### Stack
Language and version: Python 3.11
Framework: Django 4.2
Package manager: pip
Runtime: Docker + Gunicorn

### Commands
Install: pip install -r requirements.txt
Build: docker build -t app .
Test (all): pytest
Test (single): pytest tests/test_x.py
Lint: ruff check .
Typecheck: pyright

### Layout
Source: src/
Tests: tests/
Do not modify: migrations/, static/dist/

### Conventions
Naming: snake_case for functions, PascalCase for classes
Error handling: raise ValueError with message
Testing pattern: pytest + fixtures

关键：具体，不是抽象。”用 pytest + fixtures”，不是”好好写测试”。

十二、背后的设计哲学

agents-md 综合了多个来源：

来源	融合内容
Sean Donahoe IJFW 原则	一个安装、工作代码、不仪式
Andrej Karpathy 四原则	先思考、简单、手术式修改、目标驱动
Boris Cherny Claude Code workflow	反应式修剪、~100 行、只写修真实错误的规则
Anthropic Claude Code 最佳实践	explore-plan-code-commit、验证循环、上下文是稀缺资源
社区反讨好模式	禁止短语列表、直接风格

Karpathy 的四原则尤其重要：

1. 先思考再写——理解问题，不要直接开始输出
2. 简单——最简代码解决问题，不做超过需求的
3. 手术式修改——只改涉及请求的行
4. 目标驱动执行——定义可验证成功，循环直到验证通过

十三、实际效果对比

传统 AI 编程助手

用户: 修复登录失败的问题
AI: 这是一个很好的问题！让我先分析一下整个认证系统...
    [读了 20 个文件]
    我发现这里有很多可以优化的地方，比如...
    [改了 15 个不相关的文件]
    [添加了 5 个新功能]
    现在应该能工作了！
用户: ...测试一下？
AI: 好主意！[运行测试，5 个失败]
    让我修复这些...[又改了一堆]

配置 agents-md 后

用户: 修复登录失败的问题
AI: 成功标准：登录测试通过，其他测试不变。
    [读登录相关文件]
    问题：密码验证函数里 bcrypt.compare 调用参数顺序错误。
    改这一行：
    [改 1 行]
    [运行登录测试] ✓ 通过
    [运行全部测试] ✓ 全部通过
用户: 好
AI: done.

十四、上手指南

安装

# 克隆到项目根目录
git clone https://github.com/TheRealSeanDonahoe/agents-md

# 或直接下载 AGENTS.md
curl -O https://raw.githubusercontent.com/TheRealSeanDonahoe/agents-md/main/AGENTS.md

配置

1. 打开 AGENTS.md
2. 填写 Section 10（项目上下文）
3. 删除不适用的部分
4. 保持文件 ≤ 300 行

使用

正常使用 AI 编程助手——它会自动读取 AGENTS.md。

如果发现 AI 还是”讨好”或”过度重构”，检查：

• 文件是否在项目根目录？
• 文件是否太长（> 500 行会被忽略）？
• 规则是否太抽象？

结语：从实习生到资深工程师

agents-md 解决的不是”AI 不够聪明”的问题——现代 AI 已经足够聪明了。

它解决的是 AI 不够”成熟” 的问题。

聪明实习生的问题是：热情过头，边界不清，想顺便帮忙，不敢说”这不对”。资深工程师的区别是：直接、谨慎、只做被要求的事，有分歧就说出来。

agents-md 用 200 行配置，把这个差异”写进”AI 的行为里。

这不是技术突破，而是 行为规范突破——给 AI 一个”成熟工程师的人格”。

参考资料

• GitHub: https://github.com/TheRealSeanDonahoe/agents-md
• AGENTS.md 开放标准: https://agents.md
• Andrej Karpathy 四原则: LLM Coding Pitfalls 演讲
• Boris Cherny Claude Code Workflow: 公开分享
• Anthropic Claude Code 最佳实践: 官方文档