AGENTS.md 最佳实践

AGENTS.md 是项目根目录（或子模块）下的规则文件，AI 编程代理（Codex、Claude Code、Cursor 等）会自动读取并遵守其中的约定。它是让 Agent 理解你的项目规范、架构约束和工作流程的核心手段。

当 Agent 反复写出不符合项目风格的代码时，问题往往不在 Agent，而在于你没有给它清晰的规则。

什么是 AGENTS.md

AGENTS.md 是继 README.md 之后，现代项目中最值得维护的文件。README.md 面向人类开发者，AGENTS.md 面向AI 代理。

它的作用是告诉 Agent：

这个项目用什么技术栈
代码应该怎么组织
有哪些约定和约束必须遵守
怎样运行、测试、构建

核心原则：保持简洁 + 分层 + 指向性

AGENTS.md 最容易犯的错误是往里塞太多规则。如果一份规范包含 Hono + oRPC 的完整定义、命名约定、错误处理、验证策略、OpenAPI 生成要求等，全塞进一个文件会带来几个问题：

上下文膨胀：Agent 每次加载整个文件，token 浪费，性能反而下降
维护困难：文件太长后容易自相矛盾或过时
可读性差：Agent 也难以高效提取关键信息

最佳实践是分层处理：AGENTS.md 只放最核心的高层指引，详细规则放在独立文档中，通过指向方式引用。

推荐结构

根目录 AGENTS.md（轻量高层指引）

# AGENTS.md

## 项目概述
这是一个使用 Hono + oRPC 的全栈 TypeScript 项目，强调端到端类型安全。

## 核心技术栈 & 强制约束
- **API 层必须使用 Hono + oRPC**，不允许直接用 Express/Koa 或原生 fetch 实现 RPC
- 所有路由通过 oRPC 定义 contract，确保 client/server 类型一致
- 详细规范见：`docs/conventions/hono-orpc.md`

## 重要命令
- 启动开发：`bun dev`
- 类型检查：`bun run typecheck`
- 测试：`bun test`
- 构建：`bun run build`

## 工作原则
- 任何 API 变更必须同步更新 contract
- 优先参考 `src/api/routes/` 中的现有示例

详细规范：docs/ 目录独立文档

在单独的文档中展开详细规则，AGENTS.md 通过路径引用指向它们：

docs/conventions/hono-orpc.md — API 完整规范（contract 定义、路由组织、错误处理、验证策略）
docs/examples/api/ — 代码示例（Good / Bad 对比）
docs/architecture/ — 架构决策记录

Agent 在处理具体任务时，会自动或通过 @文件名 引用这些文档。

各工具对 AGENTS.md 的支持

工具	主要规则文件	是否支持 AGENTS.md	推荐做法
Codex (OpenAI)	`AGENTS.md`	✅ 原生支持，自动加载	AGENTS.md + 分层文档
Claude Code	`CLAUDE.md`（优先）	✅ 也支持 AGENTS.md 作为 fallback	CLAUDE.md 为主
Cursor	`.cursor/rules/*.mdc`	⚠️ 有限支持	以 .cursor/rules/ 为主
Windsurf	各自规则 + AGENTS.md	✅ 有限支持	AGENTS.md 为主

如果你用 Codex

Codex 原生识别并自动加载项目根目录的 AGENTS.md（以及子目录的嵌套 AGENTS.md），这是它最稳定、最原生的规则机制。.cursor/rules/ 目录对 Codex 基本无效，所以应该把精力集中在：

AGENTS.md + 指向性文档（docs/ 目录）
Codex 支持 @文件名 主动拉取上下文
在 src/api/ 等子目录放置嵌套 AGENTS.md

如果你用 Claude Code

Claude Code 优先读取 CLAUDE.md，同时也支持 AGENTS.md 作为 fallback。两种方式二选一即可，不需要同时维护两份。

如果你用 Cursor

Cursor 推荐使用 .cursor/rules/*.mdc 目录，支持按文件 glob 自动附加（如 **/routes/** 自动加载 API 规则）。AGENTS.md 可作为补充。

高级用法

嵌套 AGENTS.md（Monorepo 友好）

在子模块目录放置独立的 AGENTS.md，根目录与子目录的规则分层组合（compose）而非简单合并。Agent 在处理文件时，会同时加载根目录的全局规则和最近的子目录规则，两者互补生效：

project/
├── AGENTS.md              # 全局规则（技术栈、命令）
├── packages/
│   ├── api/
│   │   └── AGENTS.md      # API 层专属规则（合约定义、错误处理）
│   └── web/
│       └── AGENTS.md      # 前端专属规则（组件规范、路由约定）
└── docs/
    └── conventions/
        └── hono-orpc.md   # 详细规范

组合逻辑：根 AGENTS.md 提供项目级上下文（"这是全栈 TypeScript monorepo"），子目录 AGENTS.md 提供模块级细节（"API 模块走 contract-first，错误处理用 error factory"）。子目录不需要重复全局信息，只写该模块的专属规则即可。两者不是覆盖关系，是不同层次的补充。

用代码层面做硬约束

除了 AGENTS.md 软约束，结合工具做硬约束效果更好：

ESLint + 自定义规则：自动检查命名、导入路径等
Zod / oRPC contract：类型系统本身作为强制约束
PR Template + Git Hooks：提醒人工 review 关键部分
定期维护：让 Agent 根据最新代码更新规范文档中的最佳实践