AGENTS.md 編寫指南提供項目級與全域規則模板

2026-10-30 5

版权

本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。

我发现，我的学员们越来越容易忽略AGENTS.md和CLAUDE.md了。

大家都在研究怎么给Agent提需求，却容易把那些长期要遵守的规矩，散落在一次次聊天里。

老金觉得，这才是值得认真维护的核心文件。

支持这些文件的AI编程工具，会在会话开始时加载适用规则，后续按这些要求工作。

哪些写法要沿用、哪些操作需要确认，不用每次开工都从头交代。

正式文件名是大写、复数的AGENTS.md。

在Codex里，全局规则管通用习惯，项目规则管这个项目。

发生冲突时，项目规则优先，不冲突的全局规则继续保留。

一份完整的规则，要管哪些事

1、先交代项目做什么、用了什么技术栈。别让Agent一会儿换语言，一会儿换框架，解决问题之前，先把项目重搭了一遍。

2、把真实命令说明白。安装、启动、测试、检查和构建各用什么命令，在哪个目录执行，要从当前项目里确认，不能照抄别人的pnpm。

3、先找参考，不重复造轮子。先搜项目里的相似实现，本地没有合适的，再查官方文档或GitHub公开项目。

4、把改动范围和权限定清楚。已经授权的事情直接做，超出范围再问。不能顺手改无关模块，也不能把私有代码和内部数据带到公开网站。

5、别过度防御。一个小功能，不该为了理论上的极端情况堆出一套复杂系统。先讲真实风险和依据，再决定要不要增加复杂度，必要的安全检查不能省。

6、沿用项目里的好写法。命名、目录、错误处理和测试方式，都尽量和现有代码保持一致，不要每次任务都发明一种新风格。

7、卡住了要说清楚。缺了什么信息、尝试了什么、下一步准备怎么做，及时反馈，别悄悄绕远路，最后交出一大堆猜出来的改动。

8、完成要有实际验收。改了什么、跑了什么检查、哪里没通过，都要讲清楚。没运行的检查，就不能写成通过。

这些是长期约定，不需要每次重新叮嘱。

文件也别越写越臃肿，项目级可以先以50—100行、全局30—60行左右为参考。长流程放到单独文档里，规则文件留下入口。

项目定制版，填当前项目的信息

项目根目录，就是项目最外层的文件夹。

把定制规则放在这里的AGENTS.md里，方括号换成真实信息，不适用的条目删掉。

已有AGENTS.md就增量合并，别用模板覆盖旧约定。

# AGENTS.md

## 项目定位与技术栈
项目用途：[做什么，主要改动涉及哪些部分]
技术栈：[语言、框架、依赖管理工具和版本依据]

## 常用命令
执行目录：[真实目录]
安装依赖：[真实命令]
启动开发：[真实命令]
单文件或相关测试：[真实命令及参数]
全部测试：[真实命令及执行前提]
代码检查：[真实命令]
类型检查：[真实命令，不适用则删]
构建：[真实命令]

## 结构与代码模式
关键目录：[路径及用途]
参考实现：[1—2个真实文件及值得沿用的写法]
测试参考：[真实文件路径]
代码约定：[本项目最重要的几条约定]

## 项目边界与验收
受保护的文件或接口：[具体范围及原因]
需要特别确认的操作：[本项目的权限边界]
验收要求：[关键行为、检查范围和通过条件]

这份里有很多定制信息。

如果你不会填，或者懒得逐项找，让已经打开项目的Agent先分析，再帮你补全。

请扫描当前项目，完善项目级AGENTS.md。
先读已有AGENTS.md、CLAUDE.md及相关子目录规则，
再查README、依赖配置、锁文件、测试和构建配置。

按真实项目补全上面的定制项，保留原有有效约定。
每条命令注明来源、执行目录，以及是否实际验证。
找不到的信息列为待确认，不编造命令、路径或结果。
只返回扫描结果和增量合并方案，不改业务代码，
不安装依赖，不读取或输出密钥、凭证和私有数据。
我确认后，再写入规则文件。

全局通用版，老金已经填好

下面这份不留项目占位，你可以直接作为全局底稿。它把通用做法写完整，遇到不同项目时，先识别项目实际情况，再执行。

原生Windows版Codex的默认位置如下，把用户名换成自己的Windows用户目录名。

C:\Users\用户名\.codex\AGENTS.md

设置了CODEX_HOME，就放在该目录下的AGENTS.md。

用WSL，则放在Linux用户目录下的.codex中，不要混到Windows路径。

已有全局文件时，也只合并需要的内容。

# AGENTS.md

## 项目定位与技术栈
开工先读适用的项目规则、README和依赖配置。
弄清项目用途、改动范围、语言、框架及工具版本。
沿用现有技术栈，不擅自切换语言、框架或依赖管理工具。
全局与项目规则冲突时，遵循更具体的适用规则。

## 真实命令
从README、依赖配置、锁文件和脚本中确认实际命令。
查清安装、启动、测试、代码检查、类型检查和构建入口。
执行前确认工作目录、参数与前置条件，不凭习惯猜命令。
项目没有相应命令时如实说明，不编造，也不擅自补一套。
只在任务确有需要且已获授权时安装依赖或改变环境。
确认项目使用pnpm，且package.json脚本和参数写法匹配后，可用：
安装：pnpm install。启动：pnpm dev。
单测示例：pnpm test -- <真实测试文件>。全测：pnpm test。
检查：pnpm lint。类型：pnpm typecheck。构建：pnpm build。
没有对应脚本或参数不适用，就查项目真实入口，不照抄。

## 动手前先找参考
先查本项目的相似功能、组件、错误处理和测试。
本地没有合适参考，再查官方文档或GitHub公开项目。
选最相关的1—3个参考，说明采用哪种做法，不为凑数搜索。
外部检索只用通用关键词，不上传私有源码、日志或客户数据。
采用外部代码前，核对版本、适配性和许可证。

## 改动范围与权限
保持改动聚焦，不顺手重构无关模块，不覆盖用户未提交的改动。
新增依赖、删除、推送、发布或数据库变更前核对已有授权。
范围内直接执行，出现新风险或超出授权再确认。
不提交或泄露密钥、凭证、.env及私有数据。
不擅自修改已应用的迁移，不手改生成文件。
获准的依赖变更需要更新锁文件时，由项目原工具生成。
涉及生产环境或外部写入时，先确认目标、影响及授权。

## 不过度设计与防御
实现当前需求，不为假设中的未来需求增加抽象、配置和回退。
增加复杂方案前，说明具体失败场景、已有证据和维护成本。
风险或概率不知道就明确说，不编百分比或虚构代码量。
保留必要的权限检查、输入校验和数据一致性保护。
优先选择满足当前需求、便于验证和维护的简单方案。

## 代码模式
复用已有组件、工具函数、命名及错误处理方式。
参考附近的好实现和测试，保持目录与代码风格一致。
只添加有助于解释意图、约束或复杂逻辑的注释。
不通过删除测试、放宽断言或屏蔽错误来制造通过结果。

## 沟通与卡点
默认用中文交流，命令、代码和技术标识保留原样。
多步骤任务先给简短计划，有实质进展或阻塞时及时汇报。
缺少关键条件先查现有文件，仍不清楚就提出具体问题。
发现规则冲突、范围变化或更高风险时先说明，不猜着大改。

## 实际验收
按改动风险选择检查，优先跑覆盖本次改动的最小有效范围。
涉及公共接口、依赖、配置或跨模块行为时扩大检查。
高成本或有外部副作用的检查，先核对范围和授权。
报告实际修改、执行命令、结果和退出码。
区分新增错误、原有问题和环境阻塞。
未运行、未通过或仍未完成的部分如实说明，不虚报完成。

Claude Code也支持，按这样接入

新版Claude Code也支持AGENTS.md。

项目里已有CLAUDE.md的，在里面加下面这一行，就能导入同目录的这份规则，原来的有效内容保留。

@AGENTS.md

Claude的个人全局规则放在~/.claude/CLAUDE.md，不会自动读取Codex的全局文件。

改完后开一个新会话，用/context检查CLAUDE.md是否出现在Memory files列表里。

再做一个小任务，看看Agent有没有按规则执行。

写在最后

大家都在研究更强的模型、更复杂的工作流，却容易漏掉最基础的那份规则。

它看起来只是一个小文件，决定的却是 Agent 每次怎么开始、按什么要求做、什么时候才算完成。

老金觉得，越是这种不起眼、容易被忽略的东西，越值得先花时间把它做好。

谢谢你读我的文章。

如果觉得不错，随手点个赞、在看、转发三连吧🙂

如果想第一时间收到推送，也可以给我个星标⭐～谢谢你看我的文章。

开源知识库（实时更新交流群）：

https://my.feishu.cn/wiki/OhQ8wqntFihcI1kWVDlcNdpznFf