Coding Agent 不听 AGENTS.md 的 7 个原因

指令文件成了背景噪音：七个常见失败模式

一个 AGENTS.md 文件本该让编码智能体更安全、更高效。但很多指令文件最终变成了背景噪音：冗长、空泛、自相矛盾，或者根本无法验证。

以下是七个常见的失败模式——以及每种模式的最小修复方案。

1. 指令描述的是愿景，而非命令

Write clean, production-ready code.

Before finishing:
- run npm test
- run npm run lint
- do not modify generated files in src/generated/

智能体对可观测的规则比对形容词的反应更可靠。

2. 文件忽略了仓库边界

根级别的指令文件是有用的，但 monorepo 通常需要更细化的规则。把更专业的指导放在它所管理的代码附近：

/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── packages/
    └── database/
        └── AGENTS.md

根文件应定义共享策略。嵌套文件只应添加或覆盖那些真正不同的规则。

3. 命令无法直接复制使用

"运行测试"会产生歧义。哪些测试？从哪个目录？使用哪个运行时？

尽量使用精确的命令：

Validation from repository root:
1. npm ci
2. npm run typecheck
3. npm test -- --runInBand
4. npm run build

如果某个命令很慢或是可选的，要明确说明。

4. 没有完成定义

编码智能体需要一个退出条件。一个有用的验收清单可能是：

• 请求的行为已实现
• 现有的公共 API 保持兼容
• 相关的测试覆盖了此次变更
• lint、类型检查和构建均通过
• 不包含密钥、生制品或无关的重构
• 最终响应列出变更的文件和验证结果

这将一个模糊的请求转化为可检查的交付物。

5. 文件混入了永久策略和任务特定上下文

AGENTS.md 应包含持久的仓库指导：架构、命令、边界、约定和验证。

当前任务应放在 prompt 或独立的 brief 中：

## Objective
Add rate limiting to the public API.

## In scope
- middleware
- configuration
- tests

## Out of scope
- auth redesign
- database migration

## Acceptance criteria
- returns 429 after the configured threshold
- includes Retry-After
- existing API tests still pass

保持两个层次分离会让两者都更容易维护。

6. 缺少故障恢复策略

智能体需要知道当愉快路径被打破时该怎么做。

添加一个简洁的恢复规则：

If validation fails:
1. determine whether the failure predates your change
2. fix failures caused by your change
3. do not weaken or delete tests to make them pass
4. report any verified pre-existing failure with the exact command and error

这可以防止静默删除测试和模糊的"无法验证"式交接。

7. 文件太长，难以快速扫视

指令文件是操作性接口，不是公司手册。把最高价值的规则放在最前面：

• 仓库特有的编码约定
• 链接到更深入的文档而不是重复它

一个紧凑的起始模板

# AGENTS.md

## Repository map
- src/: application code
- tests/: automated tests
- docs/: user-facing documentation
- generated/: do not edit manually

## Working rules
- keep changes scoped to the request
- preserve public API compatibility unless explicitly requested
- follow the nearest existing pattern before adding a new abstraction
- never commit credentials or local environment files

## Validation
Run from the repository root:
- npm run lint
- npm run typecheck
- npm test
- npm run build

## Definition of done
- acceptance criteria are met
- relevant tests are added or updated
- validation passes
- final response summarizes changes and commands run

## Failure recovery
Do not bypass failing checks. Fix failures introduced by the change and clearly report verified pre-existing failures.

模板有意做得很小。价值来自于将它适配到仓库的真实命令、架构、风险和发布流程。

我发布了一个免费的 AgentBrief 起始模板，包含可复用的示例。如果你想要针对特定仓库的审计并在一日内交付定制 AGENTS.md，25 美元的 Fiverr 套餐是动手实操的选择。

在你的编码智能体工作流中，哪条指令带来了最大的改变？