摘要每次使用 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.mdCodex 长期需要遵守的命令、边界和验收要求对应目录下的 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根目录可以规定全仓库使用 pnpmapps/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 neverSummarize the current instructions.如果想检查某个子目录的覆盖规则可以指定工作目录codex--cdservices/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 连接到手机端让本地环境和代码仍然留在电脑上人可以通过移动入口继续跟进会话。如果你正在比较不同方案可以继续看这几篇Linco Bridge 开源在手机端续接 Codex、Claude Code、Hermes 等本地 AI Agent手机端续接 Codex 实战从安装 linco-connect 到跑通第一个跨端会话cc-connect 已经很强了我们为什么还要做 Linco Bridge离开电脑后怎么继续跟进 Codex 任务国内用户的 5 种远程方案项目地址GitHublincotalk/linco-bridge。如果它刚好适合你的工作方式欢迎试用、提 Issue或者点一个 Star给我们一些鼓励。您真实的使用反馈会直接影响我们接下来优先完善哪些能力。参考资料OpenAICustom instructions with AGENTS.mdOpenAI CookbookModernizing your Codebase with Codex