其实，

前言

现在很多公司都全面推行使用 AI 辅助开发项目了我们公司现在就是全员 AI 辅助开发。公司给了每个月固定的额度来让我们使用。

我发现很多同事在使用 AI 工具比如 Codex 开发的过程中，基本上都是这两种方式：

接下来开发过程中就很容易遇到各种问题：

很多同事觉得是因为使用的模型不对导致的原因。虽然说模型选择确实有一定的影响，但我觉得很大一部分原因是没有把 AGENTS.md 这个文件真正去合理运用管理起来。

呢？

在讲 /init 之前，我还是要先把 AGENTS.md 再简单理解一下。

AGENTS.md 是个开放标准

可以把 AGENTS.md 视为代理的 README一个专门的、可预测的地方。用于提供上下文和说明，以帮助 AI 编码代理在我们的项目中工作。

它支持的工具包括 OpenAI Codex、GitHub Copilot、Cursor、Aider、Zed、JetBrains、Claude Code 等等。

一份文件，我们就可以在多个 Agent 里面通用。

一个比较简单的 AGENTS.md 大概是这样的

# 项目规则
## 建立和测试
- 建立：npm run build
- 测试：npm test
- 格式化：npm run lint
## 编码规范
- api 入参统一用 XxxParams 命名
- 响应统一用 XxxResponse 包装
- 不要用 console.log。统一用 logger
## 禁止事项
- 不要手动修改 generated/ 目录
- 不要提交 .env 文件
- 不要往 packages/core 添加新依赖
## 联动规则
- 改了 api 接口，同步更新 docs/api.md 和对应测试
- 改了命令入口，同步 src/cli.ts + 测试 + README

虽然不多，但是基本上是够用了。

为什么我们常把它当成普通 README 使用？

很多人都不怎么用或者只是把它当成 README 文件来使用。但其实它跟我们常见的 README.md 根本不是一个东西哦。

• README.md 是给人看的
• AGENTS.md 是给 agent 看看的

那么 AGENTS.md 是怎么被加载的呢？

Codex 的加载逻辑概览

1. Coding 如何发现指导？

• Coding 启动时会建立指令链；先读全局作用域（.codex/AGENTS.md)；其实，再从项目根目录向下遍历到当前工作目录；每个目录查找 .codex/AGENTS.override.md → .codex/AGENTS.md → fallback 文件名

2. 制定全局指导方针：

• Coding 主目录创建全局默认设置；放通用规则在 .codex/AGENTS.md ;临时覆盖全局规则时用 .codex/AGENTS.override.md

4. Sizing 限制：

• Coding 会跳过空文件，并在文件总大小达到限制后停止添加文件。超过限制可提高上限或将覆盖文件放在专门工作的地方附近.

Codex 的加载顺序就是这样：

全局配置 → 项目根目录 → 当前工作目录. 后面的优先级高于前面的.

举个例子。假设我们的项目结构是：

my-monorepo/
├── AGENTS.md # 全局项目规则
├── frontend/
│ └── AGENTS.md # React 相关规则
├── backend/
│ └── AGENTS.md # Java/Spring 相关规则
└── infra/
└── AGENTS.md # 部署相关规则

Coding 在 frontend/ 启动时会先读全局 .codex/AGENTS.md，再读 my-monorepo/AGENTS.md，最终读 my-monorepo/frontend/AGENTS.mdx. 若在 backend/ 启动，则顺序相同但最终拼接的是 backend 的内容。所有这些内容会被拼接成最终指令链.

大小限制提醒与实际经验:

• Tiny rule set works well;if you exceed default KiB limit you may notice that some rules are truncated and ignored by agent.
• Avoid bloated rules;instead keep m concise and focused on most critical constraints.

为什么还需要维护？ 老实说，

因为 /init 能生成一个初始模板，却无法捕捉团队长期习惯与历史痛点。例如“改完代码必须先让我审核”或“不要直接提交到 master”。如果每次新开会话都需要手动提醒，这既浪费时间又容易漏掉。 将这些高频、高风险规则写进 AGENTS.md。 可让 agent 在任何时候自动遵循，从而显著降低 bug 与返工成本。

---

问题拆解与痛点

同事遇到的问题列表

痛点	原因	后果
Token 超支	上下文臃肿。频繁重述	月度额度不足
Bug 多	缺乏明确规范与持续验证	重工成本高
回退困难	无法实时更新规则	新功能上线后需手动调整

使用者痛点

• 对话窗口变得臃肿，导致思路混乱。
• 每次提交前都需人工检查，可预防错误却被忽略。
• 在不同工具间切换时需要重复编写一样的信息。怎么说呢，

---

如何有效维护 AGENTS md

写什么？

• 明确可执行动作。
• 排除模糊指令。
• 确保只包含长期必需且团队共识一致的约定。

写多少？

• 不要过度——指令越多agent越难记住。
• 删减已记录在 Memory 中且已迁移至 AGENTS 的条目。

何时更新？

• 稳定阶段当项目结构基本稳定后再执行 /init 并补充细节。
• 新增关键流程如引入 CI/CD 或新的依赖管理脚本。

---

多工具协作—Claude Code 与 Codex 共存方案

文件类型	用途	是否共享
AGENTS.yml	通用项目规范	✔︎ Git 提交共享
CLAUDE.yml / CLAUDE.json	Claude 专属配置	✔︎ Git 提交共享
Memory/MEMORY*.md	本地经验草稿本	✘ 本地仅存

常用方法: 1. 在仓库 root 放通用 /agents.yaml> 并通过 @agents.yaml> 引入到 CLAUDE 配置中。2. 保持 CLUE 特有配置最小化，只补充技能与 hook 设置。

---

从 Prompt 到 AGENTS md 的沉淀流程

text Prompt → Memory → Agent ⟶ 自动读取 ⟶ 实施行动

每当你发现自己在 Prompt 中重复某条指令 ≥ 2 次即考虑将其写进 AGENTS md。话说回来，

---

小结 & 行动清单

1. 创建并初始化 /agents.yaml> 并让团队同步提交至 repo。
2. 定期审查 所有 Tool‑specific 配置是否冗余或过期。
3. 每次遇到 “重复提醒” 就记录到 Memory，再决定是否迁移至 Agents 文档。
4. 避免过度堆砌指令，保持简洁明了。说起来，

这样做能显著降低 Token 消耗。提高交付质量，并为团队提供一个可维护且易于 的 AI 开发环境。

---