大多数 Claude Code 用户把 .claude 当黑箱——知道它存在，看过它出现，但从来没打开过，更不知道里面每个文件是干嘛的。

这是个遗憾。.claude 文件夹才是 Claude 在项目里行为方式的控制中枢。

两个 .claude 目录

实际上存在两个 .claude 目录：

  • 项目级 ~/.claude/projects/<project-name>/：存放团队配置，提交到 Git，所有人共享相同的规则、命令和权限策略
  • 全局级 ~/.claude/：存放个人偏好和机器本地状态，如会话历史和自动记忆

CLAUDE.md：系统的核心文件

启动 Claude Code 会话时，Claude 第一个读取的就是 CLAUDE.md。它直接加载到 system prompt，在整个对话期间持续生效。

简单说：你在 CLAUDE.md 里写什么，Claude 就遵守什么。

告诉它"实现前先写测试"，它就会先写测试。告诉它"错误处理永远用自定义日志模块，不用 console.log"，它每次都会遵守。

可以有多层：项目根目录/CLAUDE.md（团队共用）、~/.claude/CLAUDE.md（全局偏好）、子目录下的 CLAUDE.md（特定文件夹规则）。Claude 会全部读取并合并。

CLAUDE.md 写法指南：

该写：

  • 构建、测试、lint 命令（npm run test、make build 等）
  • 关键架构决策（如"我们用 Turborepo 做 monorepo"）
  • 不直观踩坑点（如"TypeScript 严格模式开着的，未使用变量是错误"）
  • 导入规范、命名模式、错误处理风格
  • 主要模块的文件和目录结构

不该写：

  • 属于 linter 或 formatter 配置的内容
  • 可以直接链接到的完整文档
  • 长段解释理论的内容

保持 CLAUDE.md 在 200 行以内。 超过这个长度，上下文消耗太大，Claude 的指令遵守度反而下降。

CLAUDE.local.md：个人偏好，不进 Git

有时候偏好是你个人的，不适合整个团队。在项目根目录创建 CLAUDE.local.md，Claude 会与主 CLAUDE.md 一起读取，且自动被 gitignore，个人调整永远不会进入代码库。

rules/：当 CLAUDE.md 变得拥挤

单人项目用 CLAUDE.md 就够了。但团队一扩大，就会出现 300 行没人维护、所有人忽视的 CLAUDE.md。

rules/ 文件夹解决了这个问题。

.claude/rules/ 里的每个 markdown 文件都会与 CLAUDE.md 一起自动加载。按关注点拆分指令：

  • api-conventions.md → API 规范
  • testing.md → 测试标准

每个人只编辑自己负责的部分，不打架。

真正强大的功能：路径作用域规则。 给规则文件加 YAML frontmatter，它只在该路径下的文件被编辑时才激活：

---
paths: ["src/api/**", "src/handlers/**"]
---

这个规则在编辑 React 组件时不会加载，只在 src/api/ 或 src/handlers/ 下工作时才激活。没有 paths 字段的规则无条件加载。

commands/：自定义斜杠命令

Claude Code 内置了 /help、/compact 等斜杠命令。commands/ 文件夹让你添加自己的命令。

放在 .claude/commands/ 里的每个 markdown 文件都会变成一个斜杠命令：review.md 创建 /project:review，fix-issue.md 创建 /project:fix-issue。

# review.md
用于代码审查。运行 git diff 并将结果注入提示。

!`git diff --cached`

! 反引号语法运行 shell 命令并把输出嵌入提示，这是让命令真正有用的关键。

用 $ARGUMENTS 传递参数：/project:fix-issue 234 把 issue 234 的内容直接喂给提示。

  • 项目命令放在 项目/.claude/commands/，团队共享
  • 个人命令放在 ~/.claude/commands/，在所有项目可用，触发词是 /user:command-name

Skills vs Commands：触发机制的根本区别

两者表面相似，触发机制不同：

  • Commands：等你输入斜杠命令才执行
  • Skills：当任务描述匹配时，Claude 自己调用，不需要你输入命令

每个 skill 放在自己的子目录里，有 SKILL.md 文件：

---
name: "Security Review"
description: "Review a PR for security issues"
---

当你说"review this PR for security issues"，Claude 读取描述、识别匹配、自动调用 skill。也可以用 /security-review 显式调用。

关键区别：skills 可以打包支持文件（参考资料、详细指南），commands 是单文件。Skills 是包，commands 是文本。

agents/：子 Agent persona

当任务复杂到需要一个专门的专家角色，可以在 .claude/agents/ 定义子 agent persona。每个 agent 是独立的 markdown 文件，有自己的 system prompt、工具访问权限和模型偏好：

---
name: "Code Reviewer"
description: "Expert at finding bugs and code quality issues"
model: "claude-sonnet-4-20250514"
tools: ["Read", "Grep", "Glob"]
---

Claude 需要代码审查时，在独立隔离的上下文窗口里 spawn 这个 agent。Agent 干完活，把发现压缩后报告回来，主会话不会被大量中间探索过程的 token 污染。

tools 字段限制 agent 能做什么。安全审计 agent 只需要 Read、Grep、Glob，没有理由让它写文件——这个限制是刻意且值得明确的。

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

settings.json：权限控制

.claude/settings.json 控制 Claude 允许和禁止做什么：允许运行哪些工具、允许读取哪些文件、是否需要在运行某些命令前请求确认。

{
  "$schema": "https://...claude-settings-schema",
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git *)", "Read", "Write", "Edit"],
    "deny": ["Bash(rm -rf)", "Bash(curl *)", "Read(.env)"]
  }
}
  • Allow list：无需确认直接运行的命令，通常是 run 命令和只读 git 命令
  • Deny list：完全禁止的命令，通常是破坏性命令（rm -rf）、直接网络命令（curl）、敏感文件（.env、secrets/ 目录）

两者都没配置的中间地带是刻意设计的——给你安全网的同时，不需要提前预判每一种可能的命令。

settings.local.json 用于个人覆盖，与 CLAUDE.local.md 同样逻辑，自动 gitignore。

~/.claude/：全局记忆

  • ~/.claude/CLAUDE.md：在所有项目里都加载，适合个人编码原则、偏好风格
  • ~/.claude/projects/<name>/：按项目存储会话转录和自动记忆。Claude Code 自动给自己记笔记——它发现的命令、观察到的模式、架构洞察。这些跨会话保持，用 /memory 可以浏览和编辑
  • ~/.claude/commands/ 和 skills/：个人命令和 skill，在所有项目可用

从零开始的步骤

  1. 在 Claude Code 里运行 /init，它通过读取项目生成一个起始 CLAUDE.md，然后精简到 essentials
  2. 添加 .claude/settings.json，配置适合你技术栈的 allow/deny 规则。最低要求：allow 你的 run 命令，deny .env 读取
  3. 为最常用的工作流创建一两个命令，代码审查和 issue 修复是好的起点
  4. 当 CLAUDE.md 开始变拥挤，把指令拆分到 .claude/rules/ 文件，必要时用路径作用域
  5. 添加 ~/.claude/CLAUDE.md 存放个人偏好

这 5 步覆盖 95% 的项目需求。Skills 和 agents 只在有值得打包的重复复杂工作流时才需要。

核心结论

.claude 文件夹本质上是一套协议：告诉 Claude你是谁、项目做什么、应该遵守什么规则。这些定义得越清楚，纠正 Claude 浪费的时间越少，它做有用工作的时间越多。

CLAUDE.md 是杠杆最高的文件，先把它做对。其他都是优化。