很多 agent 项目的失败，不是模型不会写，而是它每次开工都得重新猜一遍：测试怎么跑、哪些目录不能动、改完谁来确认、碰到危险命令怎么办。你在聊天框里说过一次，它下个会话就忘了；你把规则塞进长提示词，过几天自己也找不到。真正省心的办法，是把规则拆成三层：仓库说明负责“应该怎样做”，任务提示负责“这次做什么”，自动闸门负责“没达到条件就别算完成”。

Codex 官方把 AGENTS.md 定义为会自动进入上下文的开放格式说明文件，适合记录仓库结构、构建测试命令、工程约定、禁区和完成标准；更靠近子目录的文件可以覆盖上层规则。这很适合处理那些稳定但不值得每次重复念的事。不要写“保持高质量”这种空话，直接写命令和边界：改 API 前必须跑哪组测试，迁移文件必须人工确认，生成代码不能覆盖手写目录。规则短一点，反而更容易真的被遵守。[1]

先把“完成”写成机器能检查的话#

我会在仓库根目录放一份只够用的 AGENTS.md。它不是团队文化墙，更像给新同事的一张操作卡。下面这段可以直接改路径后使用：

# AGENTS.md

- 安装：pnpm install --frozen-lockfile
- 校验：pnpm lint && pnpm test && pnpm typecheck
- 可改：src/、tests/、docs/
- 禁止自动改：migrations/、infra/、package-lock.json
- 改 API 时：补充对应测试和 docs/api.md
- 完成前：列出改动文件、执行过的命令、未验证项

关键是最后一条。agent 说“已完成”没有意义，除非它能交出改动范围、实际跑过的命令和仍然未知的部分。Codex 的建议也是在提示或 AGENTS.md 中明确测试、lint、类型检查、最终行为确认与 diff 审查，而不是接受一段未经验证的代码。[1] 这份输出还是主 agent 或人类 review 的输入，出了问题能立刻定位到底是实现错、验证没跑，还是规则本身漏了。

Hooks 负责拦截，别负责讲道理#

有些规则不该依赖 agent 记住。Claude Code 的 hook 能在会话、回合和工具调用节点执行命令、HTTP 请求或提示；其中 PreToolUse 能在工具执行前阻止调用，PostToolUse 在成功调用后运行。[4] 这意味着“禁止直接删生产配置”应该写成 hook，而不是提示词里的礼貌提醒。

先从只记录、不阻断开始，观察一周再收紧。比如对写入操作做格式化和快速测试，对危险命令显式拒绝：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "if": "Bash(rm -rf *)",
        "command": ".claude/hooks/block-destructive.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{"type": "command", "command": "pnpm prettier --write $TOOL_INPUT"}]
    }]
  }
}

hook 的输入是 JSON，能带上工具名、参数、工作目录等上下文；在 subagent 内还会带 agent 标识，因此审计脚本可以区分是谁触发了动作。[4] 不过别把昂贵的全量测试挂到每一次编辑后。格式化、静态检查适合即时跑；集成测试放到一个明确的交付闸门，否则 agent 会把大半时间耗在重复验证上。

并行时，把写权限当稀缺资源#

subagent 的优势是把搜索、日志和探索留在独立上下文里，再给主会话回传摘要；Claude Code 也支持给它们单独配置工具和权限。[3] Codex 同样建议并行优先用于探索、测试、排障和总结，对同时写代码保持谨慎，因为冲突和协调成本会上升。[2] 所以一组实用分工是：两个只读 agent 分别找调用链和测试缺口，一个实现 agent 拿到唯一的写入范围，最后一个只读 reviewer 检查 diff 与验收输出。

还有一个容易漏掉的细节：把“谁可以编辑”与“谁负责验收”分开。实现 agent 可以只拥有 src/payments/ 的写权限，reviewer 则只读整个 diff；这样 reviewer 不会一边发现问题一边悄悄把证据改掉。主 agent 最后只接收两样东西：可复现的验证结果，以及明确列出的例外。这个分离会多一次交接，但比让所有人共享无限写权限便宜得多。

不要让每个 worker 都读完整 AGENTS.md 后自由发挥。任务里再补一张小卡：目标、可写路径、禁止项、验收命令、回报格式。稳定规则归文件，本次差异归任务卡，强制动作归 hook。三层各做一件事，出错时也知道该修哪里。

快速上手#

今天就挑一个最常返工的项目，先做这四步：

# 1. 让 agent 生成初稿，随后人工删到一页以内
codex /init

# 2. 把真实验证命令写进 AGENTS.md
printf '\n- 校验：pnpm lint && pnpm test\n' >> AGENTS.md

# 3. 先在本地验证命令本身
pnpm lint && pnpm test

# 4. 提交前让 agent 只读审查未提交改动
codex /review

/init 可以为当前目录搭出 AGENTS.md 初稿，[1] 而 Codex CLI 也提供专门的 review 流程来检查未提交改动、提交或基线差异，且不修改工作树。[2] 先只固化一条真正痛过的规则，例如“改鉴权必须跑回归测试”。等它连续救你两次，再加下一条。规则不是越多越安全；能被执行、被验证、被维护的规则才有用。

Sources#

[1] https://developers.openai.com/codex/learn/best-practices — OpenAI Codex Best practices [2] https://developers.openai.com/codex/cli — OpenAI Codex CLI [3] https://docs.anthropic.com/en/docs/claude-code/sub-agents — Claude Code Docs: Create custom subagents [4] https://docs.anthropic.com/en/docs/claude-code/hooks — Claude Code Docs: Hooks reference