背景与动机
AGENTS.md 是给 Codex 这类 Agent 看的项目规则文件。它解决的问题不是“项目是什么”，而是“Agent 在这个项目里应该怎么做事”。
一个好的 AGENTS.md 能让不同会话、不同线程、不同 Agent 都遵守同一套边界。
应该写哪些内容
建议包含：
- 编码要求，例如 UTF-8。
- 修改前必须读取的文件。
- 搜索和排查流程。
- 目录规范。
- 测试和构建命令。
- Git 工作区保护规则。
- 不允许主动扩展需求。
- 完成前自检清单。
示例结构：
## Required
- Use UTF-8 for all generated files.- Read this file before project commands or edits.- Do not revert user changes.
## Search
- Use `rg` before assuming file locations.- For uncertain technical claims, verify with official docs.
## Test
- Run `pnpm check` after content or type changes.- Run `pnpm build` before final handoff when feasible.优先级要清楚
规则文件里最重要的是优先级。推荐顺序：
这样当默认习惯和项目规则冲突时，Codex 不会用“最佳实践”覆盖本地约束。
防止跑偏的规则
可以明确写：
- 不要为了更完整而扩大范围。
- 不要把局部任务变成系统性重构。
- 不要新增用户没要求的 UI、模块、抽象层。
- 如果准备偏离方案，先说明原因并等待确认。
- 完成前检查是否遗漏用户强调的边界。
这类规则看起来啰嗦，但对长会话非常有用。
常见反模式
- 只写项目介绍，不写执行规则。
- 把所有个人偏好都塞进去，导致规则太重。
- 规则互相矛盾，没有优先级。
- 写了测试命令，但没有说明什么时候必须跑。
- 忘记强调不要覆盖用户已有改动。
PDF 对照与延伸
这篇对应《Codex-Complete-Guide-zh-v2.0.1》的 §05 AGENTS.md：给 Codex 一张地图。PDF 里把 AGENTS.md 定位成 Codex 的项目规则入口，类似 Claude Code 里的 CLAUDE.md，但更强调多形态共用：CLI、App、Cloud、IDE Extension、Chrome 扩展都应该尽量共享同一套项目约束。
重点对照：
§05中关于AGENTS.md的项目规则、编码规范和执行边界。§01中“五种形态共享同一套配置和规则”的心智模型。§08中 Skills、MCP、Automations 与项目规则的分工。
这篇扩展了优先级规则。原因是 Agent 经常同时受到用户当前指令、项目规则、历史上下文和默认工程习惯影响。如果没有明确优先级，最容易出现“默认最佳实践覆盖项目真实约束”的问题。
适合放进 AGENTS.md 的规则片段
## Before Editing
- Read this file first.- Check `git status --short`.- Do not revert user changes.- Search existing implementations before adding new patterns.
## Content
- Use UTF-8.- Keep frontmatter consistent with nearby notes.- Do not add UI, routes, or components for content-only tasks.
## Verification
- Run `pnpm check` after Markdown or content schema changes.- Run `pnpm build` when adding new public pages.一句话总结
AGENTS.md 的价值是把项目协作规则显式化，让 Codex 在长任务和多线程环境里仍然稳定遵守边界。