.claude/ 文件夹解剖：Claude Code 的控制中心完全指南

本文基于 @akshay_pachaar 发布的权威指南《Anatomy of the .claude/ folder》，系统梳理 Claude Code 配置体系的完整架构，并结合实际工程实践经验进行深度解析。

为什么大多数人错过了最重要的功能

大多数 Claude Code 用户把 .claude 文件夹当成黑箱。他们知道它存在，也见过它出现在项目根目录，但从未打开看过，更别说理解里面每个文件的作用。

这是一个巨大的遗漏。

.claude 文件夹是 Claude 在你项目中行为表现的控制中心。它保存了你的指令、自定义命令、权限规则，甚至 Claude 跨会话的记忆。一旦你理解了什么东西放在哪里、以及为什么这样放，你就能把 Claude Code 配置成完全符合你团队需求的工具。

本指南将逐一解析文件夹的完整结构——从每天都会用到的文件，到那些设置一次就再也不用动的配置。

两个目录，而不是一个

CLAUDE.md：Claude 的指令手册

这是整个系统中最重要的文件。当你启动 Claude Code 会话时，它读取的第一件事就是 CLAUDE.md。系统会将它直接加载到系统提示词（system prompt）中，并在整个对话过程中持续参考它。

简而言之：你在 CLAUDE.md 里写什么，Claude 就会遵循什么。

如果你告诉 Claude 在实现之前始终先写测试，它就会这样做。如果你写”永远不要用 console.log 处理错误，始终使用自定义 logger 模块”，它每次都会遵守。

项目根目录的 CLAUDE.md 是最常见的配置方式。但你也可以在 ~/.claude/CLAUDE.md 里设置全局偏好（适用于所有项目），甚至在子目录里放 CLAUDE.md 来设置文件夹级别的专属规则。Claude 会读取所有这些文件并将它们合并。

什么内容应该写入 CLAUDE.md

大多数人要么写得太多，要么写得太少。以下是实践中真正有效的内容：

应该写：

• 构建、测试和 lint 命令（npm run test、make build 等）
• 关键架构决策（“我们使用 Turborepo 的 monorepo 结构”）
• 非显而易见的注意事项（“TypeScript strict 模式已开启，未使用的变量会报错”）
• 导入约定、命名模式、错误处理风格
• 主要模块的文件和文件夹结构

不应该写：

• 任何应该放在 linter 或 formatter 配置里的内容
• 你已经可以链接到的完整文档
• 解释理论的长篇大论

保持 CLAUDE.md 在 200 行以内。 超过这个长度的文件会占用太多上下文，Claude 对指令的遵循度实际上会下降。

以下是一个简洁而有效的示例：

# Project: Acme API

## Commands
npm run dev          # Start dev server
npm run test         # Run tests (Jest)
npm run lint         # ESLint + Prettier check
npm run build        # Production build

## Architecture
- Express REST API, Node 20
- PostgreSQL via Prisma ORM
- All handlers live in src/handlers/
- Shared types in src/types/

## Conventions
- Use zod for request validation in every handler
- Return shape is always { data, error }
- Never expose stack traces to the client
- Use the logger module, not console.log

## Watch out for
- Tests use a real local DB, not mocks. Run `npm run db:test:reset` first
- Strict TypeScript: no unused imports, ever

约 20 行代码。它给了 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 Design Rules

- All handlers return { data, error } shape
- Use zod for request body validation
- Never expose internal error details to clients

当 Claude 在编辑 React 组件时，这个文件不会被加载。只有在它处理 src/api/ 或 src/handlers/ 里的文件时才会激活。没有 paths 字段的规则则在每次会话中无条件加载。

这是 CLAUDE.md 开始变得拥挤时的正确应对模式。

hooks 系统：对 Claude 行为的确定性控制

CLAUDE.md 指令效果很好——但它们本质上是建议。Claude 大多数时候会遵循，但不是所有时候。你不能依赖语言模型始终运行你的 linter、永远不执行危险命令、或者每次完成任务后都通知你。

Hooks 让这些行为变得确定性。 它们是在 Claude 工作流特定时间点自动触发的事件处理器。你的 shell 脚本每次都会运行，没有例外。

Hooks 的配置结构

所有 hooks 配置都位于 settings.json 的 hooks 键下。Claude Code 在会话开始时加载配置，当事件触发时通过 stdin 接收 JSON payload，并根据退出码决定后续行为：

• 退出码 0：成功
• 退出码 1：错误，但不阻塞
• 退出码 2：停止一切，并将 stderr 发送给 Claude 用于自我纠错

⚠️ 将退出码 1 用于安全 hooks 是最常见的错误。它只是记录错误，什么都不阻止。安全门控必须使用退出码 2。

.claude/
├── settings.json              # hooks 配置在这里，在 "hooks" 键下
└── hooks/                     # 你的 hook 脚本（按惯例，非必须）
    ├── bash-firewall.sh       # PreToolUse: 阻止危险命令
    ├── auto-format.sh         # PostToolUse: 对编辑过的文件运行格式化工具
    └── enforce-tests.sh       # Stop: 确保测试通过后再结束

核心 Hook 事件

对于工具事件，matcher 正则字段可以缩小哪些工具触发 hook。"Write|Edit|MultiEdit" 针对文件更改；"Bash" 针对 shell 命令；省略则匹配所有工具。

实际配置示例

这是一个典型的 hooks 配置，自动格式化 Claude 触碰的每个文件，并阻止危险的 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 防火墙脚本从 stdin 读取命令，检查是否匹配危险模式（如 rm -rf /、git push --force main、DROP TABLE），并在匹配时以退出码 2 阻止执行。

Stop Hooks 的注意事项

Stop hooks 同样强大。一个运行 npm test 并在失败时以退出码 2 退出的脚本，将阻止 Claude 宣告”完成”，直到测试套件变绿。

一个关键注意点：始终检查 JSON payload 中的 stop_hook_active 标志。没有它，hook 会阻止 Claude，Claude 会重试，hook 再次阻止，你就陷入无限循环。在第二次尝试时让 Claude 停止。

其他注意事项

• Hooks 不会在会话中途热重载
• PostToolUse 无法撤销任何操作，工具已经运行完毕——需要阻止操作请用 PreToolUse
• Hooks 对子智能体操作也会递归触发
• Hooks 以你的完整用户权限执行，没有沙箱。始终用引号括住 shell 变量，验证 JSON 输入，并为脚本引用使用绝对路径

skills/ 文件夹：按需调用的可复用工作流

Skills 是 Claude 可以基于上下文主动调用的工作流——当任务与 skill 的描述匹配时，Claude 会自动判断并调用它，无需你明确指示。Skills 在观察对话，并在时机合适时采取行动。

每个 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: Comprehensive security audit. Use when reviewing code for
  vulnerabilities, before deployments, or when the user mentions security.
allowed-tools: Read, Grep, Glob
---
Analyze the codebase for security vulnerabilities:

1. SQL injection and XSS risks
2. Exposed credentials or secrets
3. Insecure configurations
4. Authentication and authorization gaps

Report findings with severity ratings and specific remediation steps.
Reference @DETAILED_GUIDE.md for our security standards.

当你说”检查这个 PR 的安全问题”，Claude 读取描述，识别到它匹配，并自动调用这个 skill。你也可以用 /security-review 显式调用它。

Skills 与 commands 的关键区别：skills 可以捆绑辅助文件。上面示例中的 @DETAILED_GUIDE.md 引用了一个位于 SKILL.md 旁边的详细文档。Commands 是单个文件；Skills 是包。

个人 skills 放在 ~/.claude/skills/，在你所有项目中都可用。

agents/ 文件夹：专属子智能体角色

当某个任务复杂到足以受益于专属的专业处理时，你可以在 .claude/agents/ 中定义一个子智能体角色（subagent persona）。每个 agent 是一个 markdown 文件，包含自己的系统提示词、工具访问权限和模型偏好：

.claude/agents/
├── code-reviewer.md
└── security-auditor.md

以下是 code-reviewer.md 的示例：

---
name: code-reviewer
description: Expert code reviewer. Use PROACTIVELY when reviewing PRs,
  checking for bugs, or validating implementations before merging.
model: sonnet
tools: Read, Grep, Glob
---
You are a senior code reviewer with a focus on correctness and maintainability.

When reviewing code:
- Flag bugs, not just style issues
- Suggest specific fixes, not vague improvements
- Check for edge cases and error handling gaps
- Note performance concerns only when they matter at scale

当 Claude 需要进行代码审查时，它会在独立的隔离上下文窗口中启动这个 agent。Agent 完成工作，压缩发现，然后报告给主会话。你的主会话不会被数千个 token 的中间探索过程所污染。

tools 字段限制了 agent 可以做什么。 安全审计员只需要 Read、Grep 和 Glob。它没有理由写文件。这种限制是刻意的，值得明确声明。

model 字段让你对专注任务使用更便宜、更快的模型。 Haiku 能很好地处理大多数只读探索工作；把 Sonnet 和 Opus 留给真正需要它们的工作。

个人 agents 放在 ~/.claude/agents/，在所有项目中都可用。

settings.json：权限与项目配置

.claude/ 内的 settings.json 文件控制 Claude 被允许和不被允许做什么。这也是你的 hooks 所在的位置，以及你定义 Claude 可以运行哪些工具、读取哪些文件、在运行某些命令前是否需要询问的地方。

完整的文件结构如下：

{
  "$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 列表：包含无需 Claude 询问确认即可运行的命令。对于大多数项目，一个好的 allow 列表覆盖：

• Bash(npm run *) 或 Bash(make *) 让 Claude 自由运行你的脚本
• Bash(git *) 用于只读 git 命令
• Read、Write、Edit、Glob、Grep 用于文件操作

deny 列表：包含被完全阻止的命令，无论如何都不会执行。一个合理的 deny 列表阻止：

• 破坏性 shell 命令，如 rm -rf
• 直接网络命令，如 curl
• 敏感文件，如 .env 以及 secrets/ 中的所有内容

如果某个命令不在任何一个列表中，Claude 在继续之前会先询问。这个中间地带是刻意设计的——它给你一个安全网，而无需预先考虑每一个可能的命令。

settings.local.json：个人权限覆盖

与 CLAUDE.local.md 相同的思路。创建 .claude/settings.local.json 用于你不想提交的权限更改。它会被自动加入 .gitignore。

全局 ~/.claude/ 文件夹

你不会经常与这个文件夹交互，但了解它里面有什么是有用的。

~/.claude/CLAUDE.md 会被加载到每个 Claude Code 会话中，跨越你所有的项目。适合放你的个人编程原则、偏好的代码风格，或者任何你希望 Claude 记住的内容——无论你在哪个仓库中工作。

~/.claude/projects/ 按项目存储会话记录和自动记忆。Claude Code 在工作时会自动向自己保存笔记：它发现的命令、观察到的模式、架构洞察。这些内容跨会话持久化。你可以用 /memory 浏览和编辑它们。

~/.claude/commands/ 和 ~/.claude/skills/ 保存跨所有项目可用的个人命令和 skills。

通常你不需要手动管理这些内容。但了解它们的存在很有用——当 Claude 似乎”记住”了你从未告诉过它的东西时，或者当你想清除某个项目的自动记忆并重新开始时。

完整结构总览

以下是所有内容组合在一起的样子：

your-project/
├── CLAUDE.md                  # 团队指令（提交到 git）
├── CLAUDE.local.md            # 你的个人覆盖（gitignored）
│
└── .claude/
    ├── settings.json          # 权限、hooks、配置（提交到 git）
    ├── settings.local.json    # 个人权限覆盖（gitignored）
    │
    ├── hooks/                 # settings.json 引用的 hook 脚本
    │   ├── 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/                # 专属子智能体角色
        ├── code-reviewer.md
        └── security-auditor.md

~/.claude/
├── CLAUDE.md                  # 你的全局指令
├── settings.json              # 你的全局设置 + hooks
├── skills/                    # 你的个人 skills（所有项目）
├── agents/                    # 你的个人 agents（所有项目）
└── projects/                  # 会话历史 + 自动记忆

从零开始的实践路径

如果你从头开始，以下是一个经过验证的推进顺序：

第 1 步：在 Claude Code 中运行 /init。它通过读取你的项目生成一个初始 CLAUDE.md。将内容精简到核心要素。

第 2 步：添加 .claude/settings.json，配置适合你技术栈的 allow/deny 规则。至少允许你的运行命令，并禁止读取 .env 文件。

第 3 步：为你最常用的工作流创建一两个 commands。代码审查和问题修复是好的起点。

第 4 步：随着项目成长和 CLAUDE.md 变得拥挤，开始把指令拆分到 .claude/rules/ 文件中。在合理的地方按路径作用域限定它们。

第 5 步：添加 ~/.claude/CLAUDE.md 写入你的个人偏好。比如”在实现之前始终先写类型”或”偏好函数式模式而非基于类的模式”。

对于 95% 的项目，以上就是你真正需要的全部。Skills 和 agents 在你有值得打包的反复出现的复杂工作流时才派上用场。

核心洞察

.claude 文件夹本质上是一个协议——用来告诉 Claude 你是谁、你的项目做什么以及它应该遵循哪些规则。你定义得越清晰，花在纠正 Claude 上的时间就越少，Claude 花在做有用工作上的时间就越多。

CLAUDE.md 是你杠杆最大的文件。先把它做好。 其他一切都是优化。

从小处着手，边用边完善，把它当作项目中的任何其他基础设施来对待：一旦正确设置，每天都会产生回报。

参考资源

• @akshay_pachaar: Anatomy of the .claude/ folder
• Claude Code 官方文档