AGENTS.md 是什么？如何给 Codex 写一份项目说明书

原创 已于 2026-08-18 15:49:08 修改 · 195 阅读 · 6 ·
本内容遵循CC 4.0 BY-SA版权协议
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
GEO检测
于 2026-08-18 15:48:00 首次发布

AGENTS.md 是什么？如何给 Codex 写一份项目说明书

如果你已经开始把 Codex 用进真实项目，迟早会碰到一个问题：

同样是“帮我看一下这个仓库”，为什么有时候 Codex 很顺，有时候却像没接住你的意思？

答案往往不在模型本身，而在你有没有把项目规则讲清楚。

这时候，AGENTS.md 就很有用了。

OpenAI 官方把它定义成给 Codex 的项目指导文件。Codex 会在开始工作前读取 AGENTS.md，把它作为持续存在的项目上下文；官方也建议把它当成给 agents 用的开放式 README，写那些你和团队希望 Codex 每次都遵守的规则。Customization / AGENTS.md

这篇我想把它讲得更像“项目说明书”，而不是概念解释。

一、AGENTS.md 到底是什么

你可以把 AGENTS.md 理解成：

专门写给 Codex 看的项目说明书。

它不是给人看的产品文档，也不是需求文档。
它更像一份“项目运行手册”，告诉 Codex：

  • 这个仓库是干什么的
  • 怎么启动、怎么测试
  • 哪些地方可以改
  • 哪些地方不要乱动
  • 代码风格和提交流程是什么
  • 这个仓库有哪些特殊约定

官方文档里提到，一个好的 AGENTS.md 通常会覆盖这些内容：

  • build 和 test 命令
  • review 期望
  • 仓库特定约定
  • 目录级别的说明Best practices

换句话说，它不是让 Codex “更聪明”，而是让它“更懂你这个仓库的玩法”。

二、为什么要写 AGENTS.md

很多人一开始觉得没必要，觉得自己每次直接在 prompt 里说清楚就行了。

短期看好像可以。
但一旦你开始重复做这些事情，AGENTS.md 的价值就出来了。

1. 不用每次重复同样的话

比如你每次都要对 Codex 说：

请先跑测试。
不要改生产配置。
提交前先看 diff。

当这种提示词开始重复出现，最适合把它挪进 AGENTS.md。
OpenAI 官方的 best practices 也明确说过：当某个 prompting pattern 已经稳定有效，就不要每次手动重复，把它写进 AGENTS.md。Best practices

2. 让每次任务从同一套规则开始

Codex 会先读这个文件，再开始干活。
这样不管你今天让它改登录页，还是明天让它修 bug，它都能从同一套仓库规则出发。

3. 适合团队协作

如果不是你一个人用，而是几个人一起用 Codex，AGENTS.md 可以帮大家统一口径：

  • 怎么命名
  • 怎么测试
  • 怎么 review
  • 怎么提交
  • 哪些目录优先保护

这比口头约定稳定得多。

三、AGENTS.md 里应该写什么

我建议你按“从通用到具体”的顺序写。

1. 项目简介

先让 Codex 知道这是什么项目。

## Project Overview

This is a React + Node.js project for internal dashboard management.
The frontend lives in `web/`, the backend lives in `api/`.

2. 启动和测试命令

这个最重要。
Codex 要干活，得先知道怎么验证结果。

## Build and Test

- Install dependencies: `npm install`
- Start frontend: `npm run dev`
- Run tests: `npm test`
- Run lint: `npm run lint`

如果你的项目不是 npm，也可以写成 Python、Go、Rust、Java 的对应命令。
重点不是格式，而是让 Codex 知道“怎么确认改动没把项目弄坏”。

3. 代码风格和约定

这部分很适合写那些你不想每次重复讲的规则：

## Conventions

- Prefer small, focused changes.
- Do not rename public APIs unless necessary.
- Keep file and folder names in English.
- Follow the existing formatting style.
- Use existing utilities before creating new helpers.

4. review 规则

如果你常常让 Codex 帮你看改动，可以把 review 规则也写进去。

## Review Expectations

- Check for regressions first.
- Flag behavior changes explicitly.
- Mention if tests are missing.
- Call out risky changes to auth, config, or production paths.

5. 特殊目录说明

有些目录最好单独写清楚，比如：

## Directory Notes

- `scripts/` contains helper scripts and should not be rewritten casually.
- `docs/` should remain documentation-only.
- `config/` may affect production behavior and needs extra care.

这类说明很实用。
Codex 看到以后，会更容易知道哪些地方是“能改”、哪些地方是“要谨慎”。

6. 不要做什么

这一段也很重要，最好直接写清楚。

## Do Not

- Do not modify secrets or `.env` files.
- Do not change deployment settings without asking.
- Do not rewrite generated files unless needed.
- Do not introduce unrelated refactors.

四、一个适合新手直接抄的模板

如果你现在就想在仓库里放一个，可以先从这个简版开始。

# Project Overview
This repository contains a web app for internal use.

## Build and Test
- Install: `npm install`
- Start: `npm run dev`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- Keep changes small and focused.
- Follow existing code style.
- Prefer reusing existing utilities.
- Avoid unrelated refactors.

## Review Expectations
- Check for regressions.
- Mention any risky behavior changes.
- Point out missing tests.

## Do Not
- Do not modify secrets or `.env` files.
- Do not change deployment settings without asking.
- Do not touch unrelated files.

这个版本不复杂，但已经够 Codex 用了。

五、写 AGENTS.md 时最容易犯的错

1. 写得太长

AGENTS.md 不是项目百科。
它越长，Codex 越不容易一眼抓住重点。

官方也建议把它保持得小而精。Customization

所以我的建议是：

  • 先写最重要的 5 到 10 条
  • 后面真的有重复问题，再慢慢补
  • 不要把所有制度都一股脑塞进去

2. 写得太空

像这种就没什么用：

请认真开发。
请注意代码质量。
请保证不要出错。

这种话人看着都对，Codex 看了也很难执行。

更好的写法是：

- Run tests before finishing.
- Keep changes limited to the requested files.
- Report any failed commands explicitly.

3. 把 README 当成 AGENTS.md

README 是给人看的项目说明。
AGENTS.md 是给 Codex 看的工作规则。

两者可以内容有交集，但目的不一样。
README 讲“这个项目是什么”，AGENTS.md 讲“Codex 应该怎么在这个项目里做事”。

4. 忘了写测试和 review

这是最可惜的。

Codex 最需要知道的不是“项目宣传语”，而是：

  • 怎么验证
  • 哪些文件重要
  • 哪些地方别乱动
  • 出现问题该先看什么

六、AGENTS.md 和普通提示词有什么区别

可以简单理解成：

方式作用特点
普通提示词单次任务说明临时、一次性、灵活
AGENTS.md仓库级规则持久、自动加载、适合重复执行

如果你今天只改一次，普通提示词就够了。
如果你会反复在这个仓库里让 Codex 干活，AGENTS.md 就非常值。

七、我建议的写法顺序

你可以按这个顺序来写：

  1. 项目简介
  2. 构建和测试命令
  3. 代码风格
  4. review 规则
  5. 特殊目录说明
  6. 不要做什么

这个顺序最符合 Codex 实际使用场景。

因为 Codex 最先需要的是：

  • 这是什么项目
  • 怎么验证
  • 哪些地方有边界

而不是一上来先读一堆背景故事。

八、什么时候应该更新 AGENTS.md

下面这些情况，建议顺手更新：

  • 新增了测试命令
  • 构建方式变了
  • 仓库结构调整了
  • 某些目录的约定变了
  • Codex 反复在同一个地方犯错
  • 你们团队开始固定一个 review 流程

它不是写一次就不动了。
它应该跟着项目一起长。

九、一个很实用的小习惯

我现在更喜欢把 AGENTS.md 当成“项目里的低配操作手册”。

每次 Codex 在这个仓库里出错，我都会问自己：

这个错误是提示词没说清，还是规则文件没写清？

如果是后者，就把它补进 AGENTS.md。

这样下次就不用再手动重复同一句话了。

十、总结

AGENTS.md 其实不神秘。

它就是一份专门写给 Codex 的项目说明书，核心目标是把重复规则固化下来，让每次任务都从同一套仓库规范开始。

如果你记不住太多东西，只要记住这句话就够了：

当你发现自己总是在重复同样的提示词时，就该把它写进 AGENTS.md 了。

这会比一次次手动提醒 Codex 稳得多，也更适合长期维护项目。

参考资料

  • Customization: https://learn.chatgpt.com/docs/customization/overview
  • AGENTS.md: https://developers.openai.com/codex/agent-configuration/agents-md
  • Best practices: https://developers.openai.com/codex/learn/best-practices
标签
#chatgpt #AI编程 #ai
MaaaaaaX_
关注
Codex 的 AGENTS.md 到底怎么写？前端、后端两套实战模板，照抄就能用
篮球界最会写bug的人；程序猿中打球最菜的人。
08-09 429
文件名是大写AGENTS.md，放在项目根目录构建、测试、类型检查命令都是可直接复制执行的只写了 Agent 从代码里推断不出来的约定红线规则用了明确的否定句式（禁止/不要/Never）标注了自动生成目录和禁止修改的模块写清了交付要求（改动清单 + 验证命令 + 风险说明）没有任何密钥、密码、连接串整体一页能看完，核心要点 10 条以内每一条都能通过"删掉会不会更容易犯错"的测试一份短小精准的 AGENTS.md，比一份充斥模糊规则的长文件有用得多。
AGENTS.md 到底怎么写？给 Codex 一份真正有用的项目说明书
lrt369805210的博客
07-31 320
每次使用 Codex 都要重复说明项目命令、目录边界和验收要求？这些长期有效的规则，更适合写进 `AGENTS.md`。本文讲清它的作用范围、目录优先级和常见误区，并提供完整版模板、极简模板、自动生成提示词与验证方法。
Codex 里的 AGENTS.md 到底怎么用？新手先把这份说明书写好
u011635002的博客
06-16 464
如果你项目里已经有别的文件名，比如，官方支持在这样 Codex 也会把这些文件当成项目规则来读。AGENTS.md这样最稳，也最不容易搞混。很多人用 Codex，前面已经会写 Prompt 了。它有时候太能改有时候又忘了你的规则你总在重复说同样的话把这些长期规则写进AGENTS.md。你不用一开始就写很长。优先最小改动不要重构无关代码修改后列出改动文件修改后补充验证步骤只要这几条先写进去，Codex 的稳定度通常就会明显高很多。说到底，AGENTS.md。
AGENTS.md 越写越长，Codex 反而越用越笨?
cjm_success的博客
03-22 797
如果一个团队现在的AGENTS.md已经很长了，最不值得做的事情，就是继续往里补。更值得做的，反而是四件事：• 把AGENTS.md缩回入口页• 把真正重要的事实拆进docs/• 把关键取舍补成版本化决策记录• 给仓库补一个一键真正让 Codex 变强的，很多时候不是更会写 prompt。而是更会整理项目。这可能才是下一阶段 AI 编程真正的分水岭。不是谁的提示词更长。而是谁先把自己的代码库，整理成了一张真正可用的地图。
【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目
热门推荐
a18792721831的博客
01-09 1万+
本文详细介绍了CLAUDE.md和AGENTS.md这两个AI编程助手的配置文件。CLAUDE.md是Claude Code的专属配置文件，用于让AI了解项目上下文，包括构建命令、代码风格、项目架构等；AGENTS.md则是通用AI编程代理的开放标准配置文件。文章对比了传统README.md与AI配置文件的区别，解释了CLAUDE.md的文件位置优先级和内容规范，并提供了完整的配置示例。这些文件能帮助AI生成更符合项目规范的代码，提高开发效率。
【 Codex AGENTS.md 与 Claude CLAUDE.md：配置差异、使用方法和本质】
云小逸的博客
05-13 1208
AGENTS.md和CLAUDE.md的区别，不是文件名的区别，而是上下文组织方式的区别。AI 编程代理进入项目时，如何获得稳定上下文。始终相关 -> AGENTS.md / CLAUDE.md任务相关 -> Skills权限相关 -> .rules执行相关 -> Hooks角色相关 -> 多智能体当你理解这套分层后，Codex 和 Claude Code 就不再只是两个“聊天式编程工具”，而是可以被配置、复用、审计和持续改进的工程系统。
Codex 保姆级使用教程！零基础从入门到精通
冰冻三尺非一日之寒
05-22 1万+
Codex是一款AI编程助手，它不仅能像ChatGPT一样回答问题，更能直接操作项目文件、执行任务。与ChatGPT不同，Codex可以分析项目结构、修改代码、生成内容并运行命令，最后将改动展示给用户确认。它支持多种使用方式，包括CLI命令行、桌面客户端和IDE插件，适合网页开发、脚本编写、文档生成等多种场景。Codex具有计划模式、权限控制、Git集成等功能，能确保操作安全可靠。用户可以通过AGENTS.md文件为项目制定规则，指导AI的工作方式。这款工具特别适合开发者用来提高工作效率，既能处理简单任务，
Deepseek harness的 subAgent机制（chatgpt）
Code_LT的博客
08-19 341
SubAgent = 一个可以替换 Provider 的 Agent delegation Service。DeepSeek Harness SubAgent 是一套以 Durable Session 为身份、以 Activation 为运行实例、以 Inbox 为通信队列、以 Provider 为执行后端、以 Event/Session Log 为生命周期事实的轻量 Agent Runtime。≈ 外部 Agent Runtime Adapter这三个模式，被统一成了同一个能力面。
智谱GLM-5.3 API上线定价持平、豆包推虚拟桌面操控Windows、OpenAI发布青少年版ChatGPT | 8月19日 AI日报
最新发布
08-19 194
智谱上线GLM-5.3 API，定价与GLM-5.2持平，聚焦编程与自主任务并在智能体榜登顶；豆包推出虚拟桌面，可在Windows上像人一样操作电脑推进跨软件任务；OpenAI面向13-17岁推出青少年版ChatGPT，强化安全与学习功能，AI能力与场景适配正同步深化。
一边暂停下一代Astra训练、一边紧急推出ChatGPT青少年版：OpenAI同一天的两张脸
Tech_deer的博客
08-19 202
一边暂停下一代Astra训练、一边紧急推出ChatGPT青少年版：OpenAI同一天的两张脸
ChatGPT一直转圈不回答怎么办？发送失败、网络错误与页面卡住排查
L773014954的博客
08-18 204
ChatGPT一直转圈、不回答、消息发送失败或页面卡住怎么办？本文从当前对话、网络连接、浏览器扩展、设备环境、大文件和复杂任务等方面，整理一套ChatGPT卡顿与发送异常的快速排查方法。
ChatGPT、Claude Code、Codex 能直接控制泵阀吗？AI Agent 液路监测的正确架构
alysblmd
08-17 288
AI Agent 进入实验室和 IVD 液路是值得关注的趋势，但第一步不是让大模型直接控制设备，而是先建立可靠的压力、气泡、阀位和执行日志数据，再用确定性规则守住边界，最后让 AI 参与分析与规划。本文由 FOREACH 工程团队整理，用于技术讨论。文中 Python 阈值和示例数据仅用于展示方法，不构成产品性能承诺、医疗建议或可直接部署的安全控制方案。FOREACH 目前不宣称已经与上述 AI 平台完成产品级集成。
ChatGPT上传文件后读不完整怎么办？PDF、Word、Excel读取遗漏排查
L773014954的博客
08-18 542
ChatGPT上传PDF、Word、Excel后出现内容读取不完整、总结遗漏或数据分析缺失怎么办？本文从扫描版PDF、复杂Word排版、Excel多Sheet、大文件任务范围和长对话干扰等方面，整理一套文件读取遗漏排查方法。
ChatGPT、Codex实战：从Claude Code / Cursor迁移到Codex怎么做？/import最容易漏掉哪些配置？
lb654509656的博客
08-14 553
从Claude Code或Cursor迁到Codex，Import成功不等于迁移完成。重点检查Instructions、Skills、MCP、运行环境、历史Context和权限这6个容易漏掉的地方。
AI 引荐流量报告：哪些独立产品正在从 ChatGPT 获客？
weixin_47042983的博客
08-19 195
我们统计了 Turbo0 收录的全部独立产品在 Similarweb 上的 AI 平台引荐数据，发现 3295 个有流量数据的产品里，只有 164 个真正从 ChatGPT、Gemini、Claude 或 Perplexity 获得了访问量。这些产品是谁，它们又做对了什么？
告别手拷数据：怎么把平板电脑上ChatGPT的表格导出来？详解“AI导出鸭”平板版底层逻辑
jianwuhuang82的博客
08-18 393
文章摘要： “AI导出鸭”平板版解决了ChatGPT等AI工具在平板上导出表格时格式错乱的痛点，通过本地化“轻量化格式网关”技术，将AI输出的Markdown、LaTeX等语法智能转换为Word/Excel可编辑文档，保留表格结构、数学公式（OMML对象）、代码缩进及流程图（矢量图）。支持批量导出历史会话，兼容主流AI平台与文档格式，大幅提升科研、办公效率。其核心技术包括DOM解析、异步加载优化，实现秒级响应与隐私保护，现提供免费体验3次。（150字）
生成word文档的ChatGPT格式乱码终结者：AI导出鸭横向测评与工程化架构解析 摘要
aisxz的博客
08-17 877
本文探讨了AI生成内容（如ChatGPT）导出至Word文档时的格式失真问题，提出五种解决方案的横向测评。数据显示，传统方法（直接复制、WPS转换等）存在公式丢失、表格错位等缺陷，而AI导出鸭通过三层架构（语义解析、映射转换、样式保真）实现100%格式保真，支持LaTeX公式可编辑、嵌套表格完整保留及代码高亮。该工具覆盖多平台，本地处理保障隐私，成为解决AI内容工程化落地的优选方案。
AI大模型提示词技巧
qq_51470789的博客
08-14 217
AI大模型提示词技巧
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值