摘要： 每次使用 Codex 都要重复说明项目命令、目录边界和验收要求？这些长期有效的规则，更适合写进 AGENTS.md。本文讲清它的作用范围、目录优先级和常见误区，并提供完整版模板、极简模板、自动生成提示词与验证方法。

关键词： Codex、AGENTS.md、AI 编程、项目规范、提示词、代码审查、开发工作流

很多人用 Codex 一段时间后，都会开始重复下面这些话：

这个项目使用 pnpm，不要改用 npm。
不要直接修改生成文件。
改完记得跑类型检查和测试。
数据库迁移先不要执行。
当前工作区里已有的改动不要覆盖。

这些提醒当然可以写在每次任务的提示词里，但新开一个会话又得重新说一遍。哪天忘了，Codex 可能就会按照常见习惯自己判断，而它的“常见做法”未必是这个项目的做法。

如果一条要求不是只针对今天，而是对这个仓库长期有效，就可以考虑把它放进 AGENTS.md。

这篇不打算只解释名词。我更想解决一个实际问题：怎样写出一份 Codex 真能执行、团队也愿意维护的 AGENTS.md。

AGENTS.md 到底解决什么问题？

可以把 AGENTS.md 理解成一份写给编码 Agent 的项目工作说明。

它不负责替代 README，也不需要把所有业务知识重新写一遍。它更适合记录这些内容：

  • 这个仓库应该使用什么安装、启动和测试命令；
  • 修改某类代码时，必须遵守哪些约定；
  • 哪些目录可以改，哪些是生成文件或历史兼容区；
  • 哪些操作需要先确认，不能直接执行；
  • 一个任务做到什么程度，才算真正完成。

README、任务提示词和 AGENTS.md 的作用并不相同：

信息载体 更适合放什么 有效范围
README 面向开发者的项目介绍、安装和使用方式 所有读者长期可见
当前提示词 本次需求、临时限制、这次要修改的范围 当前任务
AGENTS.md Codex 长期需要遵守的命令、边界和验收要求 对应目录下的 Codex 任务

一个简单判断方法是：

如果你发现同一句话已经对 Codex 说过三次，而且下次大概率还要说，它就值得被整理进 AGENTS.md。

Codex 是怎么找到这些规则的？

OpenAI 的官方说明里有一个很关键的机制：Codex 会在开始工作前读取 AGENTS.md，并从全局到项目、再到当前目录逐层组合规则。AGENTS.md 官方文档

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

常见的三个层级是：

1. 全局规则：~/.codex/AGENTS.md

这里适合放个人在所有项目里都希望 Codex 遵守的习惯，例如：

  • 添加新的生产依赖前先确认；
  • 不覆盖用户已有的未提交改动；
  • 修改后说明执行过哪些检查；
  • 遇到权限或外部服务问题时，不假装验证成功。

不要把某个项目专属的命令放到全局文件里，否则换一个仓库后，这些规则可能反而造成干扰。

2. 项目规则：仓库根目录的 AGENTS.md

这是最常用的一层，适合说明整个仓库共同遵守的规则，例如包管理器、通用测试命令、目录结构和提交前检查。

3. 子目录规则：更靠近代码的 AGENTS.md

当一个仓库包含多个应用或服务时，根目录规则通常不够具体。

例如：

project/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── payment/
        └── AGENTS.override.md

根目录可以规定全仓库使用 pnpm；apps/web/AGENTS.md 再补充前端测试方式；支付服务需要更严格的限制时，可以使用 AGENTS.override.md。

官方规则是从项目根目录向当前工作目录逐层读取，越靠近当前目录的说明越晚加入，因此能够覆盖更上层的通用规则。同一目录存在 AGENTS.override.md 时，会优先使用它。

这里不必一开始就设计得很复杂。普通单体项目先在根目录放一份就够了，只有不同子目录确实存在不同命令或风险时，再拆分局部规则。

一份真正有用的 AGENTS.md，建议写清这 7 类信息

第一类：一句话讲清项目和技术栈

不需要复制整段产品介绍，只要帮助 Codex 快速判断当前仓库是什么：

## Project overview

- This repository is a TypeScript monorepo managed with pnpm workspaces.
- `apps/web` is the React frontend.
- `services/api` is the NestJS backend.
- Shared types live in `packages/contracts`.

这几行的价值在于减少误判。比如看到多个 package.json 时，Codex 不会随手选择其中一个目录安装依赖。

第二类：给出经过确认的命令

“记得测试”太模糊。Codex 真正需要的是可以执行的命令，以及什么时候执行：

## Commands

- Install dependencies with `pnpm install` from the repository root.
- Start the web app with `pnpm --filter web dev`.
- Run targeted tests with `pnpm --filter <package> test`.
- Run `pnpm lint` and `pnpm typecheck` before finalizing code changes.

命令一定要以仓库真实脚本为准。文档里写的是 npm test，项目实际使用 pnpm，反而会把 Codex 带偏。

第三类：说明目录边界

陌生项目里，很多错误不是代码不会写，而是改错了位置。

可以明确告诉 Codex：

## Repository boundaries

- Do not edit files under `generated/`; regenerate them with `pnpm generate`.
- Do not modify vendored code under `vendor/`.
- Put shared API types in `packages/contracts`, not in app-specific folders.
- Keep database migrations under `services/api/migrations`.

如果存在历史兼容代码、自动生成目录或不能随意变化的公共协议，这部分尤其重要。

第四类：写工具检查不出来的代码约定

格式化、缩进、引号风格如果已经由 Prettier 或 ESLint 管理，没有必要在 AGENTS.md 里再写一大遍。

更值得写的是工具难以判断的规则：

## Coding conventions

- Preserve public API compatibility unless the task explicitly allows a breaking change.
- Reuse existing error types instead of creating package-local duplicates.
- Keep permission checks in the service layer, not only in the UI.
- Prefer the existing repository pattern over introducing a new abstraction.

这些规则会直接影响代码设计，而且只看格式化配置通常推不出来。

第五类：定义修改后的验证方式

不要只写“确保一切正常”。最好按修改类型说明最小验证：

## Validation

- For documentation-only changes, verify links and formatting.
- For frontend changes, run the affected package tests and typecheck.
- For API changes, run related unit tests and contract tests.
- If a required check cannot run, report the command, blocker, and unverified risk.

这样 Codex 完成任务时，不只是说“已经修改”，还要给出可以核对的验证证据。

第六类：划出高风险操作

涉及数据、密钥、发布和依赖的操作，不适合默认授权：

## Safety

- Never print or commit secrets, tokens, or `.env` contents.
- Ask before adding production dependencies.
- Do not run database migrations against shared environments.
- Do not delete data, force-push, or rewrite Git history.
- Preserve unrelated user changes in the working tree.

这部分不是为了让 Codex 什么都不敢做，而是把“可以自主完成”和“必须先确认”的边界提前讲清楚。

第七类：规定最后怎么交付

任务完成后的说明也可以统一：

## Completion checklist

- Summarize what changed and why.
- List the checks that were actually run and their results.
- Call out anything not verified.
- Mention follow-up work only when it is directly relevant.

如果团队评审最关心兼容性、数据迁移或截图，也可以把这些要求补进来。

一份可以直接复制的完整模板

下面这份模板适合大多数项目作为起点。复制之后不要原样提交，先把命令、路径和约束替换成自己仓库里的真实内容。

# AGENTS.md

## Project overview

- Briefly describe the project, primary language, and framework.
- List the main applications, services, or packages.
- Point to the most important entry points and shared modules.

## Before making changes

- Read the relevant README, package scripts, and nearby code before editing.
- Check the Git working tree and preserve unrelated user changes.
- Keep the change scoped to the requested behavior.
- Ask before installing dependencies or performing irreversible operations.

## Commands

- Install: `<replace with the real install command>`
- Development: `<replace with the real start command>`
- Build: `<replace with the real build command>`
- Lint: `<replace with the real lint command>`
- Typecheck: `<replace with the real typecheck command>`
- Tests: `<replace with the real test command>`

## Repository boundaries

- Do not edit generated files directly: `<paths>`.
- Do not modify vendored or third-party code: `<paths>`.
- Place shared types and utilities in: `<paths>`.
- Keep module-specific code inside its owning package.

## Coding conventions

- Follow existing patterns in the nearest related module.
- Preserve public API and protocol compatibility unless explicitly approved.
- Avoid introducing a new abstraction for a one-off use case.
- Add or update tests when behavior changes.

## Validation

- Run the smallest relevant checks first.
- Run `<required checks>` before finalizing.
- Do not hide existing failures or change tests only to make them pass.
- If a check cannot run, report the blocker and remaining risk.

## Safety

- Never expose secrets, tokens, credentials, or `.env` contents.
- Do not delete data, rewrite Git history, or force-push.
- Do not run migrations or release commands without confirmation.
- Preserve unrelated changes already present in the worktree.

## Completion checklist

- Summarize the files and behavior changed.
- List commands that were actually executed and their results.
- State what was not verified.
- Keep the final response concise and actionable.

项目比较小？先用这个极简版本

不是每个仓库都需要一份很长的说明。如果项目结构简单，可以先从 10 行左右开始：

# AGENTS.md

- Use `pnpm`; do not use npm or yarn.
- Run commands from the repository root.
- Do not edit files under `src/generated/` directly.
- Preserve unrelated changes in the working tree.
- Ask before adding production dependencies.
- Run `pnpm lint`, `pnpm typecheck`, and related tests after code changes.
- If a check cannot run, explain why instead of claiming it passed.
- Summarize changed files and validation results when finished.

先解决最常踩的坑。以后出现新的、反复发生的问题，再把规则补进去。这样比一开始写几十条“可能有用”的要求更容易维护。

不想自己整理？可以先让 Codex 生成草稿

这里有一个更省时间的做法：让 Codex 先以只读方式检查仓库，再生成 AGENTS.md 草稿。

可以直接复制下面这段：

请先不要修改任何文件，也不要安装依赖。

请检查当前仓库中的 README、CONTRIBUTING、包管理器锁文件、package scripts、CI 配置、测试配置和主要目录，然后为项目起草一份 AGENTS.md。

要求：
1. 只写能够从仓库中确认的命令和规则；
2. 每条关键规则注明判断依据来自哪个文件；
3. 区分全仓库通用规则和仅适用于子目录的规则；
4. 包含安装、启动、构建、测试、目录边界、安全限制和完成标准；
5. 不要复制大段 README，也不要编造不存在的脚本；
6. 无法确认的内容单独列为“待确认”，不要直接写入正式规则。

先把草稿和依据发给我审核，确认后再创建文件。

这一步最好保留人工审核。因为 Codex 能帮你从仓库里找线索，但“哪些操作必须先确认”“哪些兼容行为绝对不能破坏”，通常仍然需要项目维护者判断。

四种看起来很完整、实际没什么用的写法

1. 全是正确的空话

例如“保持代码高质量”“遵循最佳实践”“确保没有 Bug”。这些话没有明确动作，也无法验证。

可以换成具体规则：使用哪个命令、检查哪种行为、出现什么情况必须停止。

2. 把 README 整篇复制进来

Codex 本来就可以读取 README。重复内容只会占用指令空间，还容易产生两份文档不一致的问题。

3. 把临时需求写成长期规则

“这次只修改登录页”属于当前任务，不应该长期留在 AGENTS.md。否则下一个任务明明需要修改后台，Codex 仍然可能被旧规则限制。

4. 写了规则，却没有验证是否生效

文件放错目录、存在更高优先级的 AGENTS.override.md，或者启动 Codex 时工作目录不对，都可能让实际加载的内容和预期不同。

写完以后，怎么确认 Codex 真的读到了？

最直接的方式，是在新任务开始时让 Codex 复述当前生效的规则和来源。

使用 Codex CLI 时，可以在仓库根目录执行：

codex --ask-for-approval never "Summarize the current instructions."

如果想检查某个子目录的覆盖规则，可以指定工作目录：

codex --cd services/payment --ask-for-approval never \
  "Show which instruction files are active and summarize them."

重点检查三件事：

  • 是否读取了预期的全局与项目文件；
  • 子目录规则是否覆盖了根目录的通用规则；
  • 输出中有没有已经过时或互相冲突的要求。

官方文档还提到，Codex 会在每次运行开始时重新建立指令链。如果规则看起来没有更新，先确认当前目录和文件名是否正确，再重新启动对应会话。

AGENTS.md 不需要一次写到完美

真正有用的 AGENTS.md，往往不是坐下来一次设计出来的，而是在项目协作中慢慢补全的。

Codex 连续两次用错包管理器，就把正确命令写进去；有人误改了生成文件，就补充生成方式；某个服务的测试命令和全仓库不同，再在它的目录下增加局部规则。

它更像一份会跟着项目一起维护的工作约定。短一点没关系，关键是每一条都真实、具体、能够执行。

规则写清楚以后，怎么在离开电脑时继续跟进任务？

AGENTS.md 解决的是“让 Codex 在项目里按什么规则工作”。任务真正运行起来以后，还会遇到另一个问题：人离开电脑时，能不能继续查看进度、补充要求或者处理权限请求？

这也是我们开源 Linco Bridge 的原因。它尝试把运行在个人电脑上的 Codex、Claude Code、Hermes 等本地 Agent 连接到手机端，让本地环境和代码仍然留在电脑上，人可以通过移动入口继续跟进会话。

如果你正在比较不同方案，可以继续看这几篇：

项目地址：GitHub：lincotalk/linco-bridge。如果它刚好适合你的工作方式，欢迎试用、提 Issue，或者点一个 Star给我们一些鼓励。您真实的使用反馈，会直接影响我们接下来优先完善哪些能力。

参考资料

# 人工智能 # AIGC # github
Logo
亚马逊云科技技术品牌专区

更多推荐

cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！人工智能的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区
cover

别再只聊大模型！AI的下一场革命，藏在“身体”里

avatar 亚马逊云科技技术品牌专区