我发现，我的学员们越来越容易忽略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 每次怎么开始、按什么要求做、什么时候才算完成。
老金觉得，越是这种不起眼、容易被忽略的东西，越值得先花时间把它做好。
谢谢你读我的文章。
如果觉得不错，随手点个赞、在看、转发三连吧🙂
如果想第一时间收到推送，也可以给我个星标⭐～谢谢你看我的文章。
开源知识库（实时更新 交流群）：
my.feishu.cn/wiki/OhQ8wq…
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
I found out that it was becoming easier for my students to ignore AGENTS.md and CLAUDE.md.
Everyone is looking at how to raise the demand for Agent, but it is easy to spread the long-standing rules in one chat.
King felt that this was a core document that deserved serious attention.
The AI programming tool, which supports these documents, will load the applicable rules at the beginning of the session and work on these requirements.
What is to be followed and what operations need to be identified and not to start from scratch.
The official document is AGENTS.md in capital and complex numbers.
In Codex, the global rules govern common habits and the project rules govern the project.
In the event of a conflict, the project rules take precedence and the non-conflicting global rules remain.
It's a complete rule.
1. What does the project do and what technology is used? Don't let Agent change his language, change the frame, reset the project before solving the problem.
2. Clarify the true order. What commands to install, start, test, check and build each are to be executed in which directory, to be confirmed from the current project, and not to copy another pnpm.
3. First look for reference and do not repeat wheels. Search for similar achievements in the project, which are not locally suitable, before checking official files or GitHub public projects.
4. Clarify the scope of the changes and permission. What has been authorized is done directly and beyond. Non-relevant modules cannot be changed and private codes and internal data cannot be brought to the public website.
5. Do not over-defensive. A small function should not create a complex system for theoretical extremes. The real risks and grounds before deciding whether to add complexity cannot be saved by the necessary security checks.
6. Follow the good writing in the project. Naming, cataloguing, error processing and testing are as consistent as possible with existing codes and do not create a new style for each assignment.
Seven, it's stuck. What was missing, what was being tried, what was next step going to do, what was to be done, what was to be done, what was to be done, what was to be done in time, what was to be done, what was to be done, what was to be done, what was to be done.
8. Completion requires actual acceptance check. Make it clear what's changed, what's gone, what's not passed. Without running a check, it cannot be written through.
These are long-term engagements and do not need to be repeated every time.
It is also important not to overwhelm the document by referring to lines 50-100 and around 30-60 at the project level. long pipeline is placed in a separate document, leaving an entry for the rule file.
Customized version of the project to fill in current project information
The root directory of the item is the folder at the outermost level of the item.
Put the custom rule here in AGENTS.md and replace the square brackets with real information and delete the entries that are not applicable.
AGENTS.md consolidates incrementally and does not overwhelm the old agreement with templates.
# AGENTS.md
# Project positioning and technology
Purpose of the project: [What to do, which parts of the main change are involved]
Technical warehouse: [language, framework, reliance on management tools and basis of version]
Common commands
Executing directory: [real directory]
Installation dependency: [real order]
Start development: [real order]
Single file or associated test: [real command and parameters]
All tests: [real command and execution prerequisites]
Code check: [real command]
Type check: [real order, not applicable, delete]
Build: [real command]
# Structure and code mode
Key Directory: [Ways and Purposes]
Reference Achieved: [1 - 2 authentic documents and writings worth following]
Test reference: [real file path]
Code engagement: [The most important treaties of this project]
# Project boundary with acceptance check
Protected documents or interfaces: [specific scope and cause]
Operations requiring special confirmation: [permission boundary of the project]
acceptance check requires: [Key Conduct, Scope of Inspection and Conditions for Adoption]
There's a lot of custom information in this.
If you don't fill it in, or you don't bother to look on each item, then you can get Agent to analyze the project and finish it.
Please scan the current project to improve the project level AGENTS.md.
We have already read the AGENTS.md, CLAUDE.md and its subdirectories.
Recheck README, rely on configuration, lock file, test and build configuration.
Complete the customization above with the real project and keep the original valid agreement.
Each order indicates the source, the directory of execution and whether it is actually verified.
Information not found is pending confirmation and does not create commands, paths or results.
Only the results of the scan and the incremental amalgamation programme are returned without changing the business code,
Do not install dependencies, read or output keys, vouchers and private data.
After I confirm, I will write to the rule document.
It's a universal edition. Kim's filled in.
The next item is not in place, and you can do it directly as the global floor. It completes the generic approach and, in case of different projects, identifies the actual status of the project before its implementation.
The default position for the original Windows version of Codex is as follows, replacing the user name with its own Windows user directory name.
C:\Users\username\.codex\AGENTS.md
Sets CODEX HOME, which is placed under AGENTS.md.
Use WSL, which is placed in the Linux user directory.codex, do not mix to Windows path.
When a global document is available, only what is required is consolidated.
# AGENTS.md
# Project positioning and technology
Start reading applicable project rules, README and dependency configuration.
Identify project uses, scope of changes, language, framework and tool versions.
Use the existing technology warehouse without any unauthorized switchover of language, framework or reliance on management tools.
In case of conflict between the global and project rules, more specific applicable rules are followed.
# True command
Confirms the actual command from README, dependent configuration, lock file and script.
Identification of installation, start-up, testing, code checks, type checks and construction portals.
working directory, parameters and prefixes are confirmed prior to execution and are not subject to customary guess orders.
The project is not properly described when the corresponding order is not made, nor is it built up without permission.
Reliance or environment change is only installed when there is a real need for the mission and when mandated.
Confirms that the project is pnpm and that the package.json script and parameter are matched by:
Installation: pnpm install. Launch: pnpm dev.
Single measure: pnpm test -- < Real test file>. Global: pnpm test.
Check: pnpm lint. Type: pnpm typecheck. Build: pnpm built.
If no corresponding script or parameters are not applicable, check the true entry of the project and do not copy it.
Let's find out
Check the similar functions, components, error processing and testing of the project.
There is no local reference for official documents or GitHub public projects.
Select the 1-3 references that are most relevant to indicate which approach is used and not for a compact search.
External searches are conducted using generic keywords only and do not include private source code, log or customer data.
Check the version, fit and license before using external codes.
# Change scope and permission
Maintain the focus of the change, not re-engineer the unrelated module and do not cover changes not submitted by the user.
Additional relying, deleting, pushing, publish or pre-database change check is authorized.
Direct execution within scope, with new risks or confirmation beyond delegated authority.
Do not submit or disclose keys, vouchers,.env and private data.
No unauthorized changes to applied migrations and no manual changes to generate documents.
The approved dependent changes are generated by the original project tool when they require an update of the lock file.
Targets, impacts and authorizations are identified when it comes to the production environment or external writing.
# But design and defense
To achieve current needs without adding abstraction, configuration and rollback to the hypothetical future needs.
The increase in complex programmes is preceded by a description of the specific failure scene, available evidence and maintenance costs.
Risk or probability is not known, and it is clear that no percentage or fictitious code volume is created.
Retain the necessary permission checks, input verification and data consistency protection.
Priority is given to simple options that meet current needs and facilitate validation and maintenance.
Code Mode
Reuses existing components, utility functions, naming and error handling.
Take reference to good realization and testing in the vicinity and keep the directory in code style.
Add only notes that would explain intent, constraint or complex logic.
The result is not produced by deleting tests, relaxing assertions or blocking errors.
# Communication and card points
By default, communicate in Chinese and keep the order, code and technical identifier as they are.
Multi-step tasks are planned briefly and are reported in a timely manner if there is substantial progress or obstruction.
The lack of key conditions to look at existing documents first remains unclear and specific questions are raised.
When a conflict of rules, a change in scope or a higher risk is identified, it is explained and no major change is assumed.
# Actual acceptance check
Select the screening on the basis of the risk of change and prioritize the minimum effective range to be covered by this change.
Expanded inspection when involving public interfaces, dependence, configuration or cross-module behaviour.
High-cost or external side-effect inspections, first checking scope and delegation of authority.
Report actual modifications, enforcement orders, results and exit codes.
Distinguishing between new errors, pre-existing problems and environmental barriers.
The parts that are not operational, have not been adopted or have not been completed are properly stated and are not overstated.
Claude Code also supports access.
The new version of Claude Code also supports AGENTS.md.
The CLUDE.md is already in the project, and the following line is added to it, which will allow the same directory to be imported and the original valid content to be retained.
@AGENTS.md
Claude's personal global rule is ~/.claude/CLAUDE.md and does not automatically read Codex's global file.
Starts a new session after the change, and checks CLAUDE.md for memory files.
Do another little job to see if Agent did it by the rules.
At the end.
People are studying stronger models, more complex workflows, and it's easy to miss the most basic rule.
It's just a little file, and it's Agent who decides how, what and when to start.
King felt that the more invisible and easily ignored the more worthwhile it would be to spend the first time doing it.
Thank you for reading my article.
If you think it's good, you can order it, read it, forward it.
If you want to get a delivery first, you can give me a sign. Thank you for reading my article.
Open-source knowledge base (real-time update exchange group):
my.feishu.cn/wiki/OhQ8wq…
Auto-fetched and translated by AI Atlas. All rights belong to the original author.