小节一:AGENTS.md 到底解决什么——它不是能力说明,而是“当前项目的合同”

先对照下面这张图看两类信息:通用能力说明告诉 Agent 大体会做哪些事,而项目合同约束它在这个仓库里应该怎样做。同样是修 Bug,换个项目,测试命令、依赖策略和允许修改的位置都可能完全不同。

图片[1]-小节一:AGENTS.md 到底解决什么——它不是能力说明,而是“当前项目的合同”-大赛人网

理解了这个区别,再看后面的 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
喜欢就支持一下吧
点赞7 分享
评论 抢沙发
头像-大赛人网
欢迎您留下宝贵的见解!
提交
头像-大赛人网

昵称

取消
昵称

    请登录后查看评论内容