先对照下面这张图看两类信息:通用能力说明告诉 Agent 大体会做哪些事,而项目合同约束它在这个仓库里应该怎样做。同样是修 Bug,换个项目,测试命令、依赖策略和允许修改的位置都可能完全不同。
![图片[1]-小节一:AGENTS.md 到底解决什么——它不是能力说明,而是“当前项目的合同”-大赛人网](https://www.dsrw.com/wp-content/uploads/2026/11/image-1738.png)
理解了这个区别,再看后面的 Runtime、Testing、Editing Rules 等条目,就不会误把它们写成放之四海而皆准的调试技巧。它们是当前项目对执行过程提出的具体要求。
很多人第一次看到 AGENTS.md,会觉得,“这不就是另一个 Prompt 文件吗?”
如果这样理解,就很容易和:
SKILL.md
System Prompt
Memory
混在一起。
我们先把边界说清楚。
Skill 解决什么?
Skill 解决,面对某类问题,一般应该怎么做。
例如:
python-debug
告诉 Agent:
先复现
看 traceback
最小修改
跑相关测试
这套方法可以跨项目复用。
AGENTS.md 解决什么?
AGENTS.md 解决,当前这个项目,必须遵守什么。
例如:
Python 3.9
不能修改 tests/
不能新增依赖
测试命令是 pytest -q
换另一个项目,这些规则可能完全不同。
System Prompt 解决什么?
System Prompt 解决,这个 Agent 的长期身份和底线。
例如:
你是 Coding Agent。
不得伪造执行结果。
必须遵守 Tool Middleware。
Memory 解决什么?
Memory 解决,过去已经确认过什么。
例如:
项目曾经决定继续使用 Python 3.9。
某次迁移方案已经被否决。
所以可以记住一句:
Skill
→ 通用方法
AGENTS.md
→ 项目规则
Memory
→ 历史事实
System Prompt
→ 长期角色和底线
为什么说 AGENTS.md 像项目合同?
因为它不是“建议”。
而是:
当前项目范围内的明确约束。
例如:
不允许修改 tests/
不是,“尽量不要改。”
而是,不允许。
如果 Agent 真要违反,应该:
停止
或请求用户明确覆盖规则
而不是悄悄忽略。
规则最好具有可验证性
差规则:
代码要写得优雅。
这个很难判断。
好规则:
不允许修改 tests/。
可以确定验证。
差规则:
尽量少改。
好规则:
修改文件数量尽量控制在 3 个以内;
若需要更多,先解释原因。
也更可执行。
一个实用 AGENTS.md 示例
# AGENTS.md
## Runtime
- Python 3.9
- 不允许修改 Python 版本
## Testing
- 使用 pytest
- 修改代码后必须执行相关测试
- 最终必须执行 `pytest -q`
## Editing Rules
- 不允许修改 tests/
- 不允许修改 migrations/
- 不允许删除已有公共 API
## Dependencies
- 不允许新增第三方依赖
- 不允许升级 requirements.txt 中已有版本
## Completion
只有满足以下条件才算完成:
- Bug 已修复
- 相关测试通过
- `pytest -q` 通过
- 未违反以上规则
这就比一句:
“请谨慎修改项目。”
© 版权声明
文章版权归作者所有,未经允许请勿转载。
THE END
















请登录后查看评论内容