ARTICLE · 1119299
三层MD文件:AI编程工具不告诉你的隐藏玩法
三层MD文件:AI编程工具不告诉你的隐藏玩法Claude Code 和 Codex 的 MD 文件，三个层级一次讲清 一、这些 md 文件是干嘛的 二、三个层级，从大到小 全局级：管你所有的项目 项目级：管当前这个仓库 目录级：管某个子目录 三、写法上记住四点 1 要短。AI 每次都要读，太长容易漏。全局和项目级压在 200 行内，目录级 30 行内。 2 写具体。写"npm test 跑测试"，别写"请高效地测试"。越具体 AI 越不会跑偏。 3 不重复。全局写过的，项目里别抄一遍。层级越低越只写增量。 4 用 @ 引用。内容太长就拆成几个文件，在入口里用 @文件名 导入。 四、三个层级，各一份能抄的例子 全局级 · ~/.claude/CLAUDE.md # 我的偏好- 回答用中文，注释用英文- 一行代码不超过 100 字符- 改代码前先解释思路 项目级 · 项目根目录 CLAUDE.md # 项目Vue3 + Vite 前端，Node.js 后端# 命令- 启动：npm run dev- 测试：npm test# 约定- 组件用 Composition API- 提交信息用英文 目录级 · services/CLAUDE.md # 本目录：services 层- 数据库访问只写在这里- 每个表一个文件，命名 xxxService.ts
你每次让 Claude Code 或 Codex 写代码，它都会先读一遍项目里的"说明书"，再照着干。这份说明书就是 md 文件：Claude Code 读 CLAUDE.md，Codex 读 AGENTS.md，内容都是 Markdown 纯文本，用记事本就能改。
它的价值就一条：把"每次都要重复说一遍的话"，变成"AI 每次都会自动读到的规则"。
文件放在全局目录，跟具体项目无关：Claude Code 放 ~/.claude/CLAUDE.md，Codex 放 ~/.codex/AGENTS.md。作用是你自己的通用习惯，任何项目打开都生效。这里只写"我"的偏好：回答用中文、注释用英文、一行代码别写太长。别放某个项目才用的东西。
在项目根目录放一个 CLAUDE.md 或 AGENTS.md。作用是这个仓库特有的规则，谁进这个仓库都生效。这里写"这个项目"的事实：启动命令、测试命令、目录结构、依赖说明。别人照着它，能把项目跑起来。
在子目录里再放一个 CLAUDE.md 或 AGENTS.md。作用更窄：只有 AI 读到这个目录里的代码时，才会用上这些规则。这里只写这一个模块的约定和边界，比如"这个接口只允许在 service 层调用"。
每份都短到能直接复制，改个路径就能用。
三个层级记一句话：全局写"我"，项目写"这个项目"，目录写"这个模块"。先把项目级写好，能解决八成的问题。