AiRobotNews 人工智能机器人技术网

拆开 .claude/ 文件夹:CLAUDE.md、rules、hooks、skills、agents 各管什么

拆开 .claude/ 文件夹:CLAUDE.md、rules、hooks、skills、agents 各管什么

多数 Claude Code 用户把 .claude 文件夹当黑箱。知道它在,见过它出现在项目根目录,但没打开过,更没弄清里面每个文件干什么。

这是白丢的机会。

.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,你的私人改动进不了仓库。

CLAUDE.local.md 与主文件的合并关系

四、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 脚本每次都会跑,没有例外。

hooks 在工具调用前后的位置

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/,所有项目通用。

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/                  # 会话历史 + 自动记忆

十、从零开始的五步

白手起家的话,这个顺序好用:

  1. 在 Claude Code 里跑 /init。它读你的项目,生成一份起步版 CLAUDE.md,你再删到只剩必要的。
  2. 加 .claude/settings.json,按你的技术栈写 allow/deny。最低限度:放行你的运行命令,禁掉 .env 读取。
  3. 为最常做的工作流建一两个 command。代码评审和修 issue 是好的起点。
  4. 项目长大、CLAUDE.md 变挤之后,把指令拆进 .claude/rules/,该按路径限定的就限定。
  5. 加一份 ~/.claude/CLAUDE.md 写你的个人偏好,比如「先写类型再写实现」「优先函数式而非 class」。

95% 的项目到这真就够了。skills 和 agents 等到你有了值得打包的重复复杂工作流再上。

真正的要点

.claude 这套东西本质是一份协议:告诉 Claude 你是谁、你的项目在做什么、它该守什么规则。你定义得越清楚,花在纠正 Claude 上的时间越少,它做有用活的时间越多。

CLAUDE.md 是杠杆最大的那个文件,先把它弄对,其余都是优化。

从小处开始,边用边修,把它当成项目里任何一件基础设施——配好了,它每天都在还你利息。

原文地址

Anatomy of the .claude/ folder