拆开 .claude/ 文件夹:CLAUDE.md、rules、hooks、skills、agents 各管什么
多数 Claude Code 用户把 .claude 文件夹当黑箱。知道它在,见过它出现在项目根目录,但没打开过,更没弄清里面每个文件干什么。
这是白丢的机会。
.claude 是 Claude 在你项目里行为方式的中控台:指令、自定义命令、权限规则,甚至跨会话的记忆都在这里。弄明白什么放哪、为什么放那,你就能把它配成团队要的样子。
下面从每天都会用的文件,讲到配一次就忘的那种。
一、两个 .claude,不是一个
先说个容易漏的点:.claude 目录有两个。
一个在项目里,一个在你的家目录:

项目级那份装的是团队配置,提交进 git,所有人拿到同一套规则、同一批自定义命令、同一份权限策略。
~/.claude/ 那份装的是你个人的偏好和本机状态,比如会话历史和自动记忆。
二、CLAUDE.md:给 Claude 的说明书
整个系统里最重要的文件。开一个 Claude Code 会话,它读的第一样东西就是 CLAUDE.md,直接加载进 system prompt,整场对话都记得。
说直接点:你在 CLAUDE.md 里写什么,Claude 就照做。
你让它先写测试再实现,它就先写测试。你写「错误处理别用 console.log,一律用自定义 logger 模块」,它每次都会照办。
最常见的是放在项目根目录。你也可以在 ~/.claude/CLAUDE.md 放全局偏好(跨所有项目生效),甚至放进子目录做目录级规则。Claude 会把它们都读进来合并。
该写什么
多数人的问题是写太多或者写太少。管用的是这些:
写进去:
- 构建、测试、lint 命令(
npm run test、make build之类) - 关键架构决策(「我们用 Turborepo 管 monorepo」)
- 不明显的坑(「TypeScript 开了 strict,未使用变量算错误」)
- import 约定、命名模式、错误处理风格
- 主要模块的文件和目录结构
别写进去:
- 该交给 linter 或 formatter 配置的东西
- 已经有链接可查的完整文档
- 长篇讲原理的段落
CLAUDE.md 控制在 200 行以内。超过这个长度开始吃掉太多上下文,而且 Claude 对指令的遵守度反而下降。
一个最小但管用的例子:
## Project: Acme API
## Commands
npm run dev # 启动开发服务器
npm run test # 跑测试(Jest)
npm run lint # ESLint + Prettier 检查
npm run build # 生产构建
## Architecture
- Express REST API,Node 20
- PostgreSQL,走 Prisma ORM
- 所有 handler 在 src/handlers/
- 共享类型在 src/types/
## Conventions
- 每个 handler 都用 zod 校验请求
- 返回形状永远是 { data, error }
- 永远不要把 stack trace 暴露给客户端
- 用 logger 模块,不要用 console.log
## Watch out for
- 测试用的是真实本地数据库,不是 mock,先跑 `npm run db:test:reset`
- TypeScript 严格模式:不许有未使用的 import
二十行左右。它给了 Claude 在这个代码库里干活需要的一切,不用一遍遍追问。
三、CLAUDE.local.md:只属于你的覆盖
有些偏好只属于你,不属于整个团队。比如你更习惯另一个测试运行器,或者想让 Claude 总是按某个模式打开文件。
在项目根目录建 CLAUDE.local.md。Claude 会把它和主 CLAUDE.md 一起读,而它会被自动 gitignore,你的私人改动进不了仓库。

四、rules/ 文件夹:能长大的模块化指令
CLAUDE.md 管单个项目够用。团队一大,就变成 300 行没人维护、所有人无视的 CLAUDE.md。
rules/ 解决这个。
.claude/rules/ 里每个 markdown 文件都会自动跟着 CLAUDE.md 一起加载。不是一个巨型文件,而是按关注点拆开:
.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md
每个文件保持聚焦、好改。管 API 约定的人改 api-conventions.md,管测试标准的人改 testing.md,谁也不踩谁的脚。
真正有用的是按路径生效的规则。给规则文件加一段 YAML frontmatter,它就只在 Claude 处理匹配文件时激活:
---
paths:
- "src/api/**/*.ts"
- "src/handlers/**/*.ts"
---
## API 设计规则
- 所有 handler 返回 { data, error } 形状
- 请求体用 zod 校验
- 不要把内部错误细节暴露给客户端
Claude 在改 React 组件时不会加载这个文件,只在 src/api/ 或 src/handlers/ 里干活时才加载。没有 paths 字段的规则,每次会话都无条件加载。
等 CLAUDE.md 开始显得拥挤,就该切这套了。
五、hooks:把「建议」变成「确定性」
CLAUDE.md 里的指令是好的,但它们是建议。Claude 大多数时候遵守,不是每次都遵守。你不能指望一个语言模型永远跑你的 linter、永远不执行危险命令、每次做完都通知你。
hooks 把这些行为变成确定的。它们是事件处理器,在 Claude 工作流的特定点自动触发,你的 shell 脚本每次都会跑,没有例外。

hook 配置全部放在 settings.json 的 hooks 键下面。Claude Code 在会话开始时对配置做快照,事件触发时从 stdin 收到一段 JSON,用退出码决定接下来怎么办。关键的一条:只有退出码 2 会拦住执行。
- 退出 0:成功;
- 退出 1:出错,但不拦;
- 退出 2:停掉一切,把你的 stderr 交给 Claude 自我纠正。
把退出 1 用在安全钩子上是最常见的错误——它只记一条错误日志,什么也没拦。
.claude/
├── settings.json # hooks 配置在这里,挂在 "hooks" 键下
└── hooks/ # 你的钩子脚本(约定,非必需)
├── bash-firewall.sh # PreToolUse:拦危险命令
├── auto-format.sh # PostToolUse:格式化被改过的文件
└── enforce-tests.sh # Stop:收工前确保测试通过
最常用的几个事件:
PreToolUse:任何工具运行前触发,你的安全闸门;PostToolUse:工具成功后触发,给 formatter 和 linter 用;Stop:Claude 收工时触发,做「测试必须全绿」这类质量门;UserPromptSubmit:你按下回车时触发,做提示词校验;Notification:桌面提醒;SessionStart/SessionEnd:注入上下文、清理。
工具类事件还有个 matcher 正则字段,用来收窄谁来触发。"Write|Edit|MultiEdit" 针对文件改动,"Bash" 针对 shell 命令,不写就匹配全部。
一份典型配置长这样——每改一个文件就自动格式化,同时拦住危险的 bash 命令:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-firewall.sh" }
]
}
]
}
}
bash firewall 从 stdin 读命令,对着 rm -rf /、git push --force main、DROP TABLE 这类模式检查,命中就退 2 拦下。
Stop 钩子同样有劲:一个跑 npm test、失败就退 2 的脚本,会让 Claude 在测试全绿之前说不了「做完了」。有个坑:一定要看 JSON 里的 stop_hook_active 标志。不看它,钩子拦住 Claude,Claude 重试,钩子又拦住,就死循环了。第二次尝试就放它停。
桌面通知的话,在 ~/.claude/settings.json 里挂一个用 osascript(macOS)或 notify-send(Linux)的 Notification 钩子,所有项目都能用。
几个要注意的地方:
- 钩子不会在会话中途热加载;
PostToolUse撤不了已经发生的事,要阻止某个动作得用PreToolUse;- 子 agent 的动作也会递归触发钩子;
- 钩子以你的完整用户权限运行,没有沙箱——所以 shell 变量要加引号、JSON 输入要校验、脚本引用用绝对路径。
六、skills/:按需上场的可复用工作流
skills 是 Claude 能自己判断时机调用的工作流:任务和 skill 的描述对得上,它自己就用。
每个 skill 一个子目录,里面一个 SKILL.md:
.claude/skills/
├── security-review/
│ ├── SKILL.md
│ └── DETAILED_GUIDE.md
└── deploy/
├── SKILL.md
└── templates/
└── release-notes.md
SKILL.md 用 YAML frontmatter 说明什么时候用它:
---
name: security-review
description: 全面安全审计。在审查代码漏洞、部署前,或用户提到安全时使用。
allowed-tools: Read, Grep, Glob
---
把代码库按安全漏洞过一遍:
1. SQL 注入与 XSS 风险
2. 泄露的凭据或密钥
3. 不安全的配置
4. 认证与授权的缺口
按严重程度报告发现,并给出具体修复步骤。
安全标准参见 @DETAILED_GUIDE.md。
你说「帮这个 PR 看看安全问题」,Claude 读到 description,认出匹配,就自动调用它。也可以显式用 /security-review 叫。
和 commands 的关键区别:skills 可以打包附属文件。上面那个 @DETAILED_GUIDE.md 会带进一个和 SKILL.md 放一起的详细文档。commands 是单个文件,skills 是一个包。
个人 skills 放 ~/.claude/skills/,所有项目通用。
七、agents/:专门的子智能体人格
任务复杂到需要一个专门角色时,可以在 .claude/agents/ 里定义子 agent。每个 agent 是一个 markdown 文件,自带 system prompt、工具权限、模型偏好:
.claude/agents/
├── code-reviewer.md
└── security-auditor.md
一份 code-reviewer.md 长这样:
---
name: code-reviewer
description: 资深代码评审。审 PR、查 bug、合并前验证实现时主动使用。
model: sonnet
tools: Read, Grep, Glob
---
你是资深代码评审,关注正确性和可维护性。
审查时:
- 指出 bug,不只是风格问题
- 给具体改法,不给模糊的「可以更好」
- 检查边界情况和错误处理的缺口
- 只在规模真的会有影响时提性能
Claude 需要一个代码评审时,会把这个人格放进它自己的隔离上下文窗口:干完活,压缩发现,回头汇报。主会话不会被几千 token 的中间探索塞满。
tools 字段限死它能干什么。安全审计只需要 Read、Grep、Glob,它没有写文件的业务。这种限制是有意的,值得写明白。
model 字段让你对聚焦型任务用更便宜更快的模型。大部分只读探索用 Haiku 就够,Sonnet 和 Opus 留给真需要它们的活。
个人 agents 放 ~/.claude/agents/,所有项目通用。

八、settings.json:权限与项目配置
.claude/ 里的 settings.json 决定 Claude 能干什么、不能干什么。hooks 也放这里,还有哪些工具能跑、哪些文件能读、跑某些命令前要不要问你。
完整文件长这样:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git status)",
"Bash(git diff *)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)"
]
}
}
各部分干什么:
$schema 那一行让 VS Code 或 Cursor 里有自动补全和行内校验,一定要带上。
allow 列表里的命令不用问就能跑。多数项目这么写就够:
Bash(npm run *)或Bash(make *),让它自由跑你的脚本;Bash(git *)给只读的 git 命令;Read、Write、Edit、Glob、Grep给文件操作。
deny 列表里的命令无论什么情况都被拦住。合理的写法是拦:
rm -rf这类破坏性 shell 命令;curl这类直接联网命令;.env和secrets/下的敏感文件。
两个列表都没有的命令,Claude 会先问你。这个中间地带是有意的:给你一张安全网,又不必提前把每种可能的命令都想一遍。
settings.local.json:个人的权限覆盖
思路和 CLAUDE.local.md 一样。不想提交的权限改动写进 .claude/settings.local.json,它同样自动 gitignore。
九、全局的 ~/.claude/
这个目录你不常碰,但知道里面有什么有用。
~/.claude/CLAUDE.md每次会话都加载,跨所有项目。适合放你的个人编码原则、偏好风格,或任何你想让 Claude 无论哪个仓库都记住的东西。~/.claude/projects/存每个项目的会话记录和自动记忆。Claude Code 干活时会自己写笔记:发现的命令、观察到的模式、架构上的领悟,这些跨会话保留,可以用/memory浏览和编辑。~/.claude/commands/和~/.claude/skills/放个人的命令和技能,所有项目可用。
这些一般不用手动管。但哪天 Claude 好像「记得」你没告诉过它的事,或者你想清掉某个项目的自动记忆重来,知道它们在哪就很有用。
全景
所有东西拼起来是这样:
your-project/
├── CLAUDE.md # 团队指令(提交)
├── CLAUDE.local.md # 你的个人覆盖(gitignored)
│
└── .claude/
├── settings.json # 权限、hooks、配置(提交)
├── settings.local.json # 个人权限覆盖(gitignored)
│
├── hooks/ # settings.json 引用的钩子脚本
│ ├── bash-firewall.sh # PreToolUse:拦危险命令
│ ├── auto-format.sh # PostToolUse:编辑后格式化
│ └── enforce-tests.sh # Stop:收工前确保测试通过
│
├── rules/ # 模块化指令文件
│ ├── code-style.md
│ ├── testing.md
│ └── api-conventions.md
│
├── skills/ # 自动调用的工作流
│ ├── security-review/
│ │ └── SKILL.md
│ └── deploy/
│ └── SKILL.md
│
└── agents/ # 专门的子 agent 人格
├── code-reviewer.md
└── security-auditor.md
~/.claude/
├── CLAUDE.md # 你的全局指令
├── settings.json # 全局设置 + hooks
├── skills/ # 个人技能(所有项目)
├── agents/ # 个人 agent(所有项目)
└── projects/ # 会话历史 + 自动记忆
十、从零开始的五步
白手起家的话,这个顺序好用:
- 在 Claude Code 里跑
/init。它读你的项目,生成一份起步版CLAUDE.md,你再删到只剩必要的。 - 加
.claude/settings.json,按你的技术栈写 allow/deny。最低限度:放行你的运行命令,禁掉.env读取。 - 为最常做的工作流建一两个 command。代码评审和修 issue 是好的起点。
- 项目长大、
CLAUDE.md变挤之后,把指令拆进.claude/rules/,该按路径限定的就限定。 - 加一份
~/.claude/CLAUDE.md写你的个人偏好,比如「先写类型再写实现」「优先函数式而非 class」。
95% 的项目到这真就够了。skills 和 agents 等到你有了值得打包的重复复杂工作流再上。
真正的要点
.claude 这套东西本质是一份协议:告诉 Claude 你是谁、你的项目在做什么、它该守什么规则。你定义得越清楚,花在纠正 Claude 上的时间越少,它做有用活的时间越多。
CLAUDE.md 是杠杆最大的那个文件,先把它弄对,其余都是优化。
从小处开始,边用边修,把它当成项目里任何一件基础设施——配好了,它每天都在还你利息。