
你在 Claude Code 里写过这种配置吗?
项目根目录一个 300 行的 CLAUDE.md,里面塞了构建命令、代码规范、部署流程、Review 清单、个人偏好——全堆一起。Session 一开,token 先烧掉一大截,Claude 还常常「知道很多、遵守很少」。
Anthropic 6 月 18 日发了一篇官方指南,把 Claude Code 里管 Agent 行为的 7 种配置拆清楚了:各自什么时候加载、压缩对话后还在不在、占多少上下文、该放什么内容。
对我这种天天用 Cursor / Claude Code / Codex 的人来说,这篇最有用的就一件事:别再把所有指令都扔进 CLAUDE.md。 下面是一张能直接对照的选型表,加 3 个最常见的放错位置。
一、7 种配置,一张表讲清
官方列了 7 种「给 Claude 下指令」的方式(CLAUDE.md 算一种,分根目录/子目录两种加载;下表拆开展示)。差别主要在三个维度:什么时候进上下文、压缩(compaction)后还在不在、占多少 token。
我的读法:前 5 种是日常主力;Output styles 和 CLI 追加是「改人设」级别的,别轻易动。
二、每种配置怎么用
1、CLAUDE.md:项目的「总索引」,别当垃圾桶
根目录 CLAUDE.md 在 Session 开始就加载,压缩后还会重读。官方建议:控制在 200 行以内,指定 owner,当代码一样 Review。
子目录的 CLAUDE.md(比如 app/api/CLAUDE.md)只在 Claude 读到该目录文件时才加载。Monorepo 里给每个团队目录单独放一份,别人用 claudeMdExcludes 跳过不相关的。
常见翻车:CLAUDE.md 越写越长,每个人往里加一条,没人删。结果每个工程师每个 Session 都背着几百行可能用不上的规范——token 白烧,该遵守的反而被稀释。
2、Rules:带路径的「精准约束」
Rules 放在 .claude/rules/,Markdown 格式。无路径规则 = 跟 CLAUDE.md 一样 Session 全程在;加 paths 字段才按需加载:
---
paths:
- "src/api/**"
- "**/*.handler.ts"
---
All API handlers must validate input with Zod before processing.
跨目录但非全局的约束(比如「migration 只能追加不能改」),用 path-scoped Rules 比 nested CLAUDE.md 更合适。
3、Skills:流程 playbook,别塞 CLAUDE.md
Skills 在 .claude/skills/ 下,每个 Skill 一个文件夹 + SKILL.md。Session 开始只加载 name 和 description;全文在 /code-review 这种 slash 命令或自动匹配任务时才加载。
部署流程、发布清单、Review 步骤——这种「按步骤走一遍」的内容放 Skill,别写进 CLAUDE.md。 之前写过 Skills 排行榜,这里不展开安装细节,格式和 Cursor / Codex 通用。
4、Subagents:隔离跑侧任务,主 Session 只看摘要
Subagents 在 .claude/agents/,YAML frontmatter + body。Claude 通过 Agent 工具调用,body 里的指令不会进主对话——子 Agent 在独立窗口跑,主 Session 只收到最终消息和 metadata。
适合:深度搜索、日志分析、依赖审计——中间过程你不会再引用,别污染主上下文。Skill 则是在主线程里一步步走,你能看见、能干预。
子 Agent 最多嵌套 5 层;动态工作流可以 orchestrate 几十上百个 background agent,中间结果存在脚本变量里,不堆进 Claude 的 context。
5、Hooks:要「一定发生」的事,别写 Prompt
Hooks 注册在 settings.json、策略配置或 Skill/Agent frontmatter 里。类型有 command、HTTP、mcp_tool、prompt、agent——前三种确定性执行,后两种靠模型判断。
典型用法:
-
文件改完自动跑 linter
-
任务完成 post 到 Slack
-
PreToolUsehook 检查工具调用,exit code 2 直接拒绝
配置活在上下文外,压缩对话不影响。之前 Loop Engineering 那篇讲过 hooks 是 Loop 的心跳之一——这里补一句:「每次 X 都 Y」写 Prompt 靠模型自觉,写 Hook 才靠代码执行。
6、Output styles 和 CLI 追加:改人设级别,慎用
Output styles 在 .claude/output-styles/,注入系统 Prompt,会覆盖 Claude Code 默认的编程助手指令——改代码范围、注释习惯、安全习惯、跑测试再收工,这些默认行为可能全丢。
官方内置 Proactive、Explanatory、Learning 三种,多数场景够用了。CLI 的 --append-system-prompt 是单次追加,不改默认人设,适合临时加格式偏好。
三、3 个最常见的放错位置
官方在文末给了「Quick tips」,我翻译成三个自查:
再加两条:
-
API 专用规则没加 paths → 跟写进 CLAUDE.md 一样全程加载,Docs Session 也背着
-
个人偏好写进项目 CLAUDE.md → 换仓库就污染团队;个人偏好放 user-level 配置
四、选型对照:你的指令该放哪儿
按「你想让 Claude 做什么」快速选:
配齐之后,可以打包成 Plugin 分享给队友——Skills + Subagents + Hooks + Output styles 一次带走。
五、我的判断
Anthropic 这篇本质上是在说:Claude Code 的 Harness 已经分层了,别再用一个 CLAUDE.md 打天下。
三个结论:
-
先审计你的 CLAUDE.md。 超过 200 行、里面有流程/自动化/个人偏好,该拆的拆——流程进 Skill,自动化进 Hook,偏好进 user-level。
-
「Never do X」别写 Prompt,写 Hook。 这是官方原话级别的建议,也是 Loop Engineering 里「确定性 vs 模型自觉」的分界线。
-
Subagent 和 Skill 别混。 要在主线程里看见每一步 → Skill;中间过程你不会再引用 → Subagent。
对我们用 Cursor / Claude Code / Codex 的人来说,Cursor 的 Rules、Codex 的 AGENTS.md 也是同一套思路——指令分层、按需加载、确定性的事交给代码。 官方把选型框架写清楚了,照着表对照一遍,比再堆 100 行 CLAUDE.md 管用。
参考链接
-
Anthropic — Steering Claude Code(官方博客):https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
-
Claude Code 最佳实践(官方文档):https://code.claude.com/docs/en/best-practices
-
CLAUDE.md 配置指南(官方博客):https://claude.com/blog/claude-md-files-customizing-claude-code-for-your-codebase
-
Hooks 配置指南(官方博客):https://claude.com/blog/how-to-configure-hooks