#AGENTS.md 项目指令

AGENTS.md 是 Codex（以及 Cursor、Gemini CLI 等）共同采用的 开放标准，用于在任务开始前注入持久、可版本化的项目规则。

#为什么需要 AGENTS.md？

纯靠聊天 Prompt 的问题：

• 每次会话都要重复「请跑 eslint」「测试命令是 pnpm test」
• 团队规范无法 Code Review
• Agent 容易在大型 monorepo 里读错目录

AGENTS.md 把 「新同事 onboarding 文档」 变成 Agent 的默认上下文。

#发现与合并规则

#加载顺序

1. 全局 ~/.codex/AGENTS.override.md 或 ~/.codex/AGENTS.md
2. 项目 从 Git 根 → 当前工作目录，每层最多一个文件：
   • AGENTS.override.md > AGENTS.md > 自定义 fallback 名
3. 拼接：根在前、子目录在后 → 越靠近 CWD 优先级越高

#大小限制

默认合并上限 32 KiB（project_doc_max_bytes）。超出会截断——这是刻意设计，迫使团队写 精炼 的规则。

#写什么、不写什么

适合写入：

• 构建 / 测试 / lint 命令（可复制粘贴的一行命令）
• 目录结构说明（「业务逻辑在 internal/，不要改 vendor/」）
• PR 与 commit 约定
• 安全红线（禁止提交密钥、禁止 git push --force 到 main）

不适合写入：

• 整本设计文档（放 docs/，在 AGENTS.md 里写 链接与路由）
• 经常变化的临时任务
• 与代码无关的长篇叙述

#示例：仓库根 AGENTS.md

# AGENTS.md

## 仓库概览
- Node 20 + pnpm monorepo
- 应用代码在 `apps/web`，共享库在 `packages/`

## 必跑命令
- 安装：`pnpm install`
- 测试：`pnpm test`
- Lint：`pnpm lint`

## 变更原则
- 先写测试再改实现（错误处理类 bug 除外）
- 公共 API 变更需更新 `packages/core/README.md`
- 不要修改 `pnpm-lock.yaml` 除非依赖确实变更

#嵌套目录 override

在 services/payments/AGENTS.override.md：

# services/payments/AGENTS.override.md

## Payments 服务
- 测试使用 `make test-payments`，不要用根目录的 `pnpm test`
- 涉及 API Key 轮换必须先通知 #security 频道

从该目录启动：

codex --cd services/payments "修复退款接口的幂等 bug"

会加载：全局 → 根 AGENTS.md → payments override。

#全局个人偏好

~/.codex/AGENTS.md 示例：

# ~/.codex/AGENTS.md

## 沟通风格
- 先给计划，再执行
- 完成时列出修改的文件清单

## 工具偏好
- 包管理默认 pnpm
- Python 项目优先 uv

#自定义 fallback 文件名

若团队已有 TEAM_GUIDE.md：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

#反馈闭环（重要）

当 Codex 重复犯同一类错误 时：

1. 在对话中纠正
2. 明确说：「把这条规则写进 AGENTS.md」
3. Code Review 合并进仓库

在 GitHub PR 中也可 @codex add this to AGENTS.md 委派 Cloud 任务更新。

配合 pre-commit、lint、typecheck，把软规则变成硬约束。

#验证加载结果

codex --ask-for-approval never "列出当前加载的 instruction 来源并摘要"

或启用日志：

codex -c log_dir=./.codex-log
# 查看 .codex-log/codex-tui.log

#故障排查

#下一步

• Agent Skills：可复用 SOP
• 架构与运行机制：指令链在 Agent 循环中的位置