AGENTS.md 到底怎么写?给 Codex 一份真正有用的项目说明书

发布时间:2026/11/12 14:00:19

AGENTS.md 到底怎么写?给 Codex 一份真正有用的项目说明书 摘要每次使用 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
延伸阅读

更多相关文章

2026/11/13 3:11:07

ESP32 ADC引脚详解:硬件架构、软件配置与精度提升实战

1. 项目概述:ESP32 ADC引脚深度解析如果你正在玩ESP32,无论是用它做环境传感器、电池电量监测,还是音频信号采集,ADC(模数转换器)功能几乎是你绕不开的一环。但很多朋友在初次接触ESP32的ADC时,…

2026/11/12 20:05:16

开源磁盘清理工具全解析:从原理到Python实战开发

在日常开发工作中,磁盘空间不足是开发者经常遇到的痛点问题。项目编译产生的临时文件、日志积累、缓存数据等会快速占用大量存储空间,手动清理既耗时又容易误删重要文件。本文将介绍几款优秀的开源磁盘清理工具,从基础使用到高级功能全面解析…

2026/11/6 9:04:24

京东商品API实战:如何抓取全网最优价?

前言:价格监控的“掘金”时代在电商竞争白热化的今天,商品价格瞬息万变。对于消费者而言,如何在海量商品中锁定“史低”价格是一门学问;对于商家、数据分析师或开发者而言,实时、准确地抓取全网最优价,则是…

2026/11/13 3:06:53

如何查电工证是否报名证全国通用吗

电工证怎么查是否报名?含金量高的证书你别乱报 你是不是也遇到过这种情况,手里有个电工证,但不知道是不是已经报名,怕被中介坑了钱又白忙活?现在市面上太多培训机构打着“包过”的旗号,你要是不了解清楚,很容易上当。尤其是这个电工证, 含金量…

2026/11/13 3:06:53

工地太忙根本没时间复习考试,电工证纸和卡到底值不值得考?

工地太忙根本没时间复习考试,电工证纸和卡到底值不值得考? 工地太忙根本没时间复习考试,但电工证纸和卡是 上岗必备 的证件,没有它,连入场都成问题。尤其是许昌的建筑工人,越来越多的项目开始强制要求持证上岗,不考的话,不仅工资受影响,甚至可能被…

2026/11/13 3:06:53

光伏行业电工证标准千万别踩坑,外省证转过来有讲究

光伏行业电工证标准千万别踩坑,外省证转过来有讲究 之前考的证在外省能不能转过来?这是很多在光伏行业打拼的朋友们最关心的问题,尤其是那些从外地转岗或者跨省工作的电工。别急,今天咱们就来聊聊这个【光伏行业电工证标准】到底值不值得考,外省证怎么转…

2026/11/13 3:06:53

初级电工证视力要求官方回应:实操考试心里没底怕挂科?

初级电工证视力要求官方回应:实操考试心里没底怕挂科? 你是不是也担心自己视力不达标,根本不敢报名初级电工证?别急,官方回应来了,明确说明视力要求并不像你想象的那么苛刻。今天就带你从头梳理一遍初级电工证的视力要求、考试流程、备考技巧,还有信阳…

2026/11/13 3:01:53

在校考高级工电工证怎么考?郑州报考避坑指南全解析

在校考高级工电工证怎么考?郑州报考避坑指南全解析 你是不是也担心学历不高,根本考不上高级工电工证?别急,这正是本文要解决的问题。针对郑州及河南省内广大应届毕业生,尤其是准备考取【在校考高级工电工证】的你,本文将从政策、流程、避坑点、电子证书…

2026/11/12 20:35:13

电工证丢失还能补吗?千万别踩坑,丢了证等于失业

电工证丢失还能补吗?千万别踩坑,丢了证等于失业 你正在找工作,但手里的电工证突然丢了,这下怎么办?别急,先别慌, 电工证丢失还能补吗 ?答案是肯定的,但 千万别踩坑 ,补办流程如果不了解,可能会耽误你上岗、甚至影响到你的收入。…

2026/11/13 0:01:06

办上海高压电工证良心建议:别被中介坑了,自己看这篇就够了

办上海高压电工证良心建议:别被中介坑了,自己看这篇就够了 你是不是也像我一样,第一次听说“高压电工证”这个名词,就感觉一头雾水?其实很多人都跟我一样,不知道去哪报名、怕被中介坑,结果花了冤枉钱还考不上。今天我就从一个在商丘培训过的学员角度,…

2026/11/13 0:01:06

黎里考电工证在哪里值不值得考

黎里考电工证在哪里值不值得考 之前考的证在外省能不能转过来?这是很多在外地工作、准备回老家发展的朋友最关心的问题。特别是在黎里地区,很多从事电力相关工作的朋友,都面临这样一个难题: 外省的电工证能否在本地使用?值不值得考?…

2026/11/13 0:01:06

毕节哪里考电工证 怎么报名学历不高也能上手

毕节哪里考电工证 怎么报名学历不高也能上手 你是不是也和我一样,学历不高,想着考个电工证,但又担心自己条件不够,怕报不上名?其实不然,只要符合条件,学历不高也能考电工证。今天就来聊聊【毕节哪里考电工证】这个问题,还有怎么报名,让你一步到位不…

2026/11/12 22:10:13

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/12 9:51:42

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑