让仓库指令文件减少AI编码反复纠偏
文章介绍Claude Code和Codex CLI的项目指令文件，讨论配置位置、应保留的约束及应删去的冗余内容。目标是将包管理器、生成文件保护等重复要求沉淀为团队可共享的规则，并兼顾两个工具。
AI 深度解读
让 AI 每次都记住「用 pnpm」「别改生成代码」，靠反复提醒很累。作者给出的办法是维护 CLAUDE.md 或 AGENTS.md，把项目里那些无法轻易从代码看出来的约定，变成每次会话都会读到的说明。
但文件越长，并不代表约束越强。文章真正有用的部分，是区分哪些内容值得长期占用上下文、两种工具怎样加载规则，以及怎样让团队只维护一份事实来源。它更像一套配置经验，没有提供效果对照实验，部分加载行为也需要结合实际版本核对。
先搞清楚规则从哪里加载
按照原文，Claude Code 会合并多个位置的说明：~/.claude/CLAUDE.md 放个人偏好，仓库里的 ./CLAUDE.md 或 ./.claude/CLAUDE.md 放团队规则，./CLAUDE.local.md 放个人在当前项目的补充，并加入 .gitignore。
启动时，它读取当前工作目录及各级父目录里的文件，距离启动位置最近的最后读取。子目录文件不在启动时全部加载，而是在读取或编辑对应目录文件时加载。因此，packages/api/CLAUDE.md 适合放 API 包自己的约定。
Codex 的方式有所不同。全局文件默认是 ~/.codex/AGENTS.md，设置了 CODEX_HOME 就使用对应位置；同目录存在 AGENTS.override.md 时，优先使用后者。项目规则从项目根目录，通常是 Git 根目录，一直收集到当前工作目录，每层最多选一个文件，先检查 AGENTS.override.md，再检查 AGENTS.md。
原文强调，Codex 启动时不会继续向当前目录下面收集。因此，从仓库根目录启动，不能直接假定某个服务目录里的规则已经进入上下文。
它还会跳过空文件，受 project_doc_max_bytes 限制，默认总量为 32 KiB。Claude Code 则被建议把每个 CLAUDE.md 控制在 200 行以内。两者不能混为一谈：一个是收集上限，一个是篇幅建议。
说明文件提供上下文，不能代替权限控制。
原文明确提醒，CLAUDE.md 里的句子不保证执行。真正不能发生的操作，应交给权限规则或 hook。多层文件也要一起检查，不能指望模型替团队消除矛盾；原文转述 Anthropic 的提醒是，Claude 面对冲突可能任意选一条。
什么值得写进去，什么应该删掉
作者给的判断标准很实用：一个有能力的新同事，需要别人专门告诉他这件事，还是读读代码就能知道？
值得写的通常有六类：准确命令、关键目录位置、偏离常规的约定、踩过的坑、禁止修改的路径，以及完成任务的验收条件。例如，「测试一下」不如 pnpm test -- path/to/file 明确，「共享类型集中管理」不如指出 packages/types，再说明不要在各个应用里重复定义。
下面是原文给出的假想 TypeScript monorepo 模板，用来展示怎样把操作入口和项目约定压缩到一份短文件中：
## AGENTS.md
## Commands
- Install: `pnpm install` (never npm or yarn)
- Dev server: `pnpm dev --filter web`
- All tests: `pnpm test`
- One test file: `pnpm vitest run path/to/file.test.ts`
- Lint and types: `pnpm lint && pnpm typecheck`
## Layout
- `apps/web`: Next.js frontend
- `apps/api`: Fastify server; route handlers in `src/routes/`
- `packages/types`: shared types. Import from here, don't redefine.
## Conventions
- Return errors as `Result<T, AppError>` from `packages/types`; don't throw in route handlers.
- Use `zod` schemas in `src/schemas/` for all request validation.
- New UI components go in `apps/web/components/ui/`.
## Gotchas
- API tests need Redis running locally: `docker compose up redis`.
- Run database migrations from the repo root only: `pnpm db:migrate`.
## Do not touch
- `packages/api-client/generated/` (regenerate with `pnpm codegen`)
- `pnpm-lock.yaml`, except through `pnpm install`
## Before you finish
- `pnpm lint && pnpm typecheck && pnpm test` must pass.
留意 docker compose up redis 那一行：它补充了测试命令之外的运行前提，这类信息比介绍 Next.js 是什么更有价值。模板里的 Result<T, AppError>、zod 和目录路径都是示例项目的约定，不能照搬后就当成通用最佳实践。
应该删掉的，则是完整依赖清单、整棵目录树、框架常识和大段项目历史。模型可以读取 package.json 和文件系统，原文还提到 Claude Code 的 /doctor 会指出部分可从代码推导的内容。
密钥、token、密码，以及不适合进入 Git 历史的内部 URL，也不应放进去。可以说明凭据来自被 Git 忽略的 .env.local，不要直接写出凭据。
发布流程等偶尔才用到的长步骤，也没必要每次加载。原文建议 Claude Code 使用 skills 或 .claude/rules/ 中按路径生效的规则；Codex 使用嵌套 AGENTS.md，同时留意启动目录的影响。
一份规则给两个工具用，怎样更可靠
两种工具都有 /init。Claude Code 会分析仓库，生成包含命令和约定的 CLAUDE.md；Codex 会在当前目录生成 AGENTS.md 骨架。作者建议把它当初稿，真正需要人工补的是模型无法自行推断的信息。
团队同时使用两种工具时，原文列了三种共用方式。
第一种是直接让 Claude Code 读取 AGENTS.md。原文称，近期版本在当前目录及上级没有 CLAUDE.md 或 CLAUDE.local.md 时支持这一行为，但没有给出具体版本号。尤其要留意，新增 CLAUDE.local.md 默认也会阻止这条读取路径，可通过 /config 的 Project instructions 设置调整。
第二种是在 CLAUDE.md 首行导入共享文件：
@AGENTS.md
关键是这一行，Claude Code 会在启动时展开导入，后面再放 Claude 专属说明。作者认为这是最可预测的方案，并转述官方说明称，保留导入不会导致文件被重复读取。
第三种是执行 ln -s AGENTS.md CLAUDE.md。没有专属规则时很简洁，但原文提醒 Windows 上符号链接需要额外设置，Git 也可能将其检出为普通文本，因此更推荐导入。
配置完必须验证。Claude Code 用 /context 检查 Memory files；Codex 在仓库根目录执行 codex --ask-for-approval never "Summarize the current instructions."，检查返回内容是否包含预期规则。
共用文件解决的是维护分叉，不会自动消除上下文成本。原文指出，@imports 虽能整理结构，被导入的内容仍会在启动时加载。Claude Code 会剥离块级 HTML 注释，可用来留下维护者说明；需要模型遵守的规则则不能藏在注释里。
我的判断
我认同作者把说明文件定位成「反复纠错的记录」。对前端和 Node 项目而言，包管理器、单测入口、生成目录、测试服务依赖，往往比一段架构愿景更能减少无效操作。
但「更短就更好」不能成为删掉必要约束的理由。200 行是原文转述的建议，不是效果保证；32 KiB 是容量限制，也不是建议写满的目标。更合理的取舍，是让每条常驻规则都有明确用途。
文章没有提供文件长度与遵循率、任务成功率或 token 消耗的对照数据。「同一错误出现两次再补规则」属于维护经验，不能当作经过实验验证的阈值。作者还披露自己开发了 $15 的 Mac 菜单栏应用 TokenBar，用来查看 Claude 和 Codex 的用量与费用。这说明了其关注成本的动机，并不能替代效果证据。
与 README 相比，这类文件更适合放 AI 执行任务时需要立即知道的约束；与 CI、权限配置相比，它又缺乏强制性。两者应该配合使用。至于近期版本的兼容行为，原文没有说明最低版本，团队落地时应实际检查加载结果。