案例分析一：Coding Agent 为什么明明“会修 Bug”，却总违反项目规则？

场景背景

项目根目录：

AGENTS.md
src/
tests/

AGENTS.md：

- Python 3.9
- 不允许修改 tests/
- 不允许新增第三方依赖
- 每次修改后运行 pytest

用户，“修复失败测试。”

第一版 Agent

Context：

System Prompt
+
User Task

模型：

读取 tests/test_api.py
发现断言失败
修改 test_api.py
pytest 通过

从“测试通过”看成功。

从项目规则看完全错误。

改造 ContextBuilder

加入：

System Prompt
Agent Rules
AGENTS.md
Current Task
Conversation
Tool Results

其中 Project Rules：

禁止修改 tests/

优先级高于当前任务内容。

新流程

Agent：

run pytest
 ↓
读失败测试
 ↓
读业务代码
 ↓
发现业务逻辑问题
 ↓
edit src/service.py
 ↓
run pytest
 ↓
通过

结果

最终不仅测试通过，而且符合项目约束。

把改造前后放在一起，会更直观地看到问题并不在“模型会不会写代码”，而在于它是否拿到了正确的项目上下文。缺少 AGENTS.md 时，Agent 可能用最直接但违规的方式让测试通过；加入项目规则后，它才会把动作约束在允许范围内。

这也是这一节最值得带走的工程结论之一：很多所谓 Agent 不听话，本质上是重要约束没有稳定进入每一轮 Context。 仅仅在某一轮 Prompt 里临时提醒，并不能替代正式的 Context Source。

复盘

这个案例特别能说明，很多 Agent “不听话”，不一定是 Prompt 里少写一句警告。

而是上下文架构里根本没有稳定注入项目规则。

把 AGENTS.md 当作正式 Context Source 后，项目规则才能成为每一轮持续可见的约束。

迁移

同样可以用于：

代码规范
部署限制
数据库规范
SQL 白名单
禁止新增依赖
必须运行某个验证命令

这些都应该成为明确 Context Source，而不是依赖模型“记得”。