用 Claude Code 的人，项目根目录里都会冒出个 .claude 文件夹。大部分人知道它存在，但从没打开过，更别说搞清楚里面每个文件是干什么的。

这是巨大的浪费。.claude 文件夹是 Claude 在你项目里的「控制中心」：你的团队约定、自定义命令、权限规则，甚至 Claude 跨会话的记忆，全都住在里面。搞懂了什么放在哪、为什么，你就能把 Claude Code 调成你团队最需要的样子。

这篇编译自 Daily Dose of DS 的拆解长文，我把整个文件夹的解剖结构讲透：哪些文件天天用，哪些配一次就忘掉，以及一套五步落地的路线图。文中的配置、模板、目录树都可以直接抄走改。

一、先把问题说准：.claude 其实有两个

很多人不知道，.claude 目录有两个，不是同一个东西：

	your-project/.claude/	~/.claude/
归属	项目级，团队配置	全局级，个人配置
是否进 git	提交，全团队共享	永不提交，只有你自己看得见
装什么	团队规则、自定义命令、权限策略	个人偏好、会话历史、自动记忆

同一套工具，不同的作用域。项目级的管「我们团队怎么干活」，全局的管「我个人喜欢怎么干活」。两个目录每次会话都会加载。

一句话：一个给团队，一个给自己。想清楚这条，后面所有文件的归属问题都迎刃而解。

二、CLAUDE.md：整个系统里杠杆率最高的文件

这是整个体系里最重要的文件。Claude Code 启动会话时，第一件事就是读 CLAUDE.md，把它直接塞进系统提示词，整个对话期间都生效。

说白了：你写在 CLAUDE.md 里的东西，Claude 就会照做。你写「先写测试再写实现」，它就会这么做；你写「错误处理一律用自定义 logger，禁止 console.log」，它每次都遵守。

但大部分人要么写太多，要么写太少。写法上有个清晰的清单：

该写	不该写
构建、测试、lint 命令（npm run test、make build）	linter / formatter 配置文件里已有的东西
关键架构决策（「我们是 Turborepo monorepo」）	可以直接贴链接的完整文档
不明显的坑（「TS 开了 strict，未使用变量会报错」）	大段大段讲理论的文字
import 约定、命名规范、错误处理风格
主要模块的目录结构

还有一条硬指标：控制在 200 行以内。超过这个长度，不但吃掉太多上下文，Claude 对指令的遵从度反而会下降。一个最小但够用的例子：

# 项目：Acme API


## 命令
npm run dev          # 启动开发服务器
npm run test         # 跑测试（Jest）
npm run lint         # ESLint + Prettier 检查
npm run build        # 生产构建


## 架构
- Express REST API，Node 20
- PostgreSQL，走 Prisma ORM
- 所有 handler 在 src/handlers/
- 共享类型在 src/types/


## 约定
- 每个 handler 都用 zod 做请求校验
- 返回结构永远是 { data, error }
- 绝不把堆栈信息暴露给客户端
- 用 logger 模块，禁止 console.log


## 注意
- 测试连真实本地数据库，不是 mock。先跑 npm run db:test:reset
- 严格 TypeScript：任何未使用的 import 都不允许

二十来行，Claude 在这个代码库里干活需要的背景就齐了，不用你反复解释。

三、加载顺序：四层叠加，冲突时谁说了算

有时候你的偏好只属于自己的习惯，不适合强加给团队，比如你喜欢另一个测试框架。这时候建一个 CLAUDE.local.md 放在项目根目录：它会和 CLAUDE.md 一起被读取，而且自动进 gitignore，你的个人调整永远不会污染仓库。

完整的加载顺序是四层叠加，优先级越往上越高，冲突时上面的赢：

CLAUDE.local.md          ← 你的个人项目微调（gitignore）
　↑ 覆盖
./CLAUDE.md              ← 团队约定（提交进 git）
　↑ 覆盖
~/.claude/CLAUDE.md      ← 你的全局偏好
　↑ 覆盖
Managed Policy（组织级）  ← IT 统一下发，不可覆盖

四层最终在会话启动时合并进同一份系统提示词，Claude 全部可见。

四、rules/：CLAUDE.md 装不下之后的解药

CLAUDE.md 单文件够小团队用。但团队一大，它就会膨胀成 300 行没人维护、也没人看的文件。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 开始臃肿的时候，这就是正确的拆法。

五、commands/：把重复工作流做成斜杠命令

Claude Code 自带 /help、/compact 这类内置命令。commands/ 文件夹让你加自己的：往 .claude/commands/ 里丢一个 markdown 文件，它就是一个斜杠命令，文件名即命令名。review.md 对应 /project:review，fix-issue.md 对应 /project:fix-issue。

看个实例，建 .claude/commands/review.md：

---
description: 合并前审查当前分支的 diff
---
## 待审查的改动


!`git diff --name-only main...HEAD`


## 详细 Diff


!`git diff main...HEAD`


请从以下角度审查以上改动：
1. 代码质量问题
2. 安全漏洞
3. 缺失的测试覆盖
4. 性能隐患


按文件给出具体、可执行的反馈。

在 Claude Code 里敲 /project:review，真实的 git diff 会在 Claude 看到 prompt 之前自动注入进去。关键就是这个!反引号语法：先执行 shell 命令，再把输出嵌进 prompt。这让命令真正有用，而不只是存了一段文本。

还能用 $ARGUMENTS 接收命令后面的参数：

---
description: 定位并修复一个 GitHub issue
argument-hint: [issue-number]
---
查看本仓库的 issue #$ARGUMENTS。
!`gh issue view $ARGUMENTS`
理解 bug，追到根因，修复它，并补一个
本来就能拦住它的测试。

敲 /project:fix-issue 234，issue 234 的内容就直接进 prompt 了。

.claude/commands/ 里的项目命令会提交进 git、全团队共享；想在所有项目都能用的个人命令，放~/.claude/commands/，显示为 /user:命令名。比如每日站报生成器、按你的规范生成 commit message、快速安全扫描，都很适合。

六、Skills 和 Commands：看着像，触发方式完全不同

Skills 表面上和 commands 很像，但触发机制有本质区别，这条必须先说清楚：

	Commands	Skills
触发方式	你手动敲斜杠命令	Claude 识别任务匹配，自动调用
形态	永远是单个 .md 文件	一个文件夹，SKILL.md + 配套文件
适合	可重复的手动工作流	需要上下文感知的自动工作流

一句话：Commands 等你发令，Skills 自己盯着对话找时机。

每个 skill 住在自己的子目录里，核心是 SKILL.md，用 YAML frontmatter 描述什么时候该用它：

.claude/skills/
├── security-review/
│   ├── SKILL.md
│   └── DETAILED_GUIDE.md
└── deploy/
    ├── SKILL.md
    └── templates/
        └── release-notes.md

---
name: security-review
description: 全面安全审计。审查代码漏洞、上线前检查、
  或用户提到安全相关话题时使用。
allowed-tools: Read, Grep, Glob
---
分析代码库的安全漏洞：
1. SQL 注入和 XSS 风险
2. 暴露的凭证和密钥
3. 不安全的配置
4. 认证和授权缺口
按严重级别报告发现，并给出具体修复步骤。
安全标准参考 @DETAILED_GUIDE.md。

你说「帮我审一下这个 PR 的安全问题」，Claude 读到 description、识别出匹配，就自动调起这个 skill。当然你也可以用/security-review显式调用。

和 commands 的关键差异：skills 可以打包配套文件。上面引用的DETAILED_GUIDE.md就放在 SKILL.md 旁边，需要时才加载。Commands 是单文件，Skills 是包裹。个人 skills 放~/.claude/skills/，全项目可用。

七、agents/：给复杂任务请专家，还不污染主上下文

任务复杂到值得请一位「专家」专门处理时，在.claude/agents/ 里定义 subagent 人设。每个 agent 是一个 markdown 文件，有自己的系统提示词、工具权限和模型偏好：

.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 需要做代码审查时，它会把这个 agent 派生到一个独立的上下文窗口里干活：agent 做完探索、压缩结论、只把结果带回来。你的主会话不会被几千个 token 的中间探索过程污染。

两个字段值得单独说：

• tools 字段是权限收缩。安全审计员只需要 Read、Grep、Glob，它没有任何写文件的理由。这个限制是刻意的，值得写明确。
• model 字段是成本控制。读代码为主的探索活，Haiku 就够用；Sonnet 和 Opus 留给真正需要它们的任务。

题眼在这里：subagent 吸收所有脏活累活的探索过程，主 agent 只拿答案。个人 agents 放 ~/.claude/agents/，全项目可用。

八、settings.json：权限的 allow / deny 清单

.claude/settings.json 控制 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 清单：不弹确认直接跑的命令。对大部分项目，放你的脚本入口（Bash(npm run *)或Bash(make *)）、只读 git 命令（Bash(git *)）、文件操作（Read / Write / Edit / Glob / Grep）就差不多了。
• deny 清单：无条件拦截。建议至少拦掉：毁灭性命令（rm -rf）、直连网络的命令（curl）、敏感文件（.env、secrets/ 目录）。
• 都不在清单里的：Claude 会先问你。这个中间地带是刻意设计的安全网，不用你预先枚举所有命令。

和 CLAUDE.local.md 同理，还有 settings.local.json：放你不想提交的个人权限覆盖，自动 gitignore。

九、~/.claude/：你的个人地盘，外加 Claude 的「记忆」

这个文件夹平时不怎么打交道，但知道里面有什么很有用：

• ~/.claude/CLAUDE.md：跨所有项目加载，放你的个人编码原则，比如「先写类型再写实现」「优先函数式而不是类」。
• ~/.claude/projects/：按项目存会话记录和自动记忆。Claude Code 干活时会自动给自己做笔记：发现的命令、观察到的模式、架构认知，跨会话保留。用 /memory 可以浏览和编辑。
• ~/.claude/commands/、~/.claude/skills/、~/.claude/agents/：你的个人命令、skills、agents，全项目可用。

一般不用手动管。但当 Claude 好像「记得」一件你从没说过的事，或者你想清空某个项目的自动记忆重新开始时，就知道去哪找了。

十、完整目录树 + 五步落地路线图

所有东西拼起来的全景：

your-project/
├── CLAUDE.md                  # 团队约定（提交）
├── CLAUDE.local.md            # 个人覆盖（gitignore）
│
└── .claude/
    ├── settings.json          # 权限 + 配置（提交）
    ├── settings.local.json    # 个人权限覆盖（gitignore）
    │
    ├── commands/              # 自定义斜杠命令
    │   ├── review.md          # → /project:review
    │   ├── fix-issue.md       # → /project:fix-issue
    │   └── deploy.md          # → /project:deploy
    │
    ├── rules/                 # 模块化规则文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    │
    ├── skills/                # 自动触发的工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # 专家 subagent 人设
        ├── code-reviewer.md
        └── security-auditor.md


~/.claude/
├── CLAUDE.md                  # 你的全局约定
├── settings.json              # 你的全局配置
├── commands/                  # 个人命令（全项目）
├── skills/                    # 个人 skills（全项目）
├── agents/                    # 个人 agents（全项目）
└── projects/                  # 会话历史 + 自动记忆

从零开始的落地节奏，五步就够：

步骤	做什么
1	在 Claude Code 里跑 /init，它会读你的项目生成初始 CLAUDE.md，然后手动删到只剩精华
2	加 .claude/settings.json，按你的技术栈配 allow / deny。最低限度：放行运行命令，拦掉 .env 读取
3	给最高频的工作流建一两个命令，代码审查和修 issue 是很好的起点
4	CLAUDE.md 开始臃肿时，把规则拆进 .claude/rules/，能用路径收口的就收
5	建 ~/.claude/CLAUDE.md 放个人偏好

这套配置对 95% 的项目都够用了。Skills 和 agents 等你有了值得打包的复杂工作流再上。

十一、结语

.claude 文件夹本质上是一套协议：告诉 Claude 你是谁、你的项目是干什么的、该守什么规矩。定义得越清楚，你纠正 Claude 的时间越少，它干正经活的时间越多。

CLAUDE.md 是杠杆率最高的文件，先把它写好，其他一切都是优化项。

从小处开始，边用边调，把它当成项目里的基础设施来经营：一次配好，每天分红。与其每次开会话都重复交代背景，不如这个周末就把 CLAUDE.md 写了。

资料展示：

下面是我整理的AI大模型     学习资料和工具包预览，适合收藏后按主题逐步学习