claude code 中 .claude 文件夹详解

公众号名称：方圆AI分享

作者名称：方圆yo

发布时间：2026-04-02 20:14

用过 Claude Code 的人，大概都注意过项目根目录下会自动出现一个 .claude 文件夹。

大多数人对它的态度是：知道它在那儿，但从来没点开看过里面到底有什么。

这其实挺可惜的。

因为这个文件夹，本质上就是你和 Claude 之间的「沟通协议」。

你在里面写什么，Claude 就按什么规矩办事。你不写，它就只能靠猜。猜对了算运气好，猜错了你还得花时间纠正它。

最近看到一篇很不错的文章 Anatomy of the .claude/ folder[1]，作者把 .claude 文件夹从里到外拆了个遍，从日常指令到团队协作，从权限控制到自动化工作流，几乎覆盖了 Claude Code 的所有高级用法。

建议感兴趣的朋友直接去读一读原文，内容很扎实。

今天我把这篇文章里的核心内容整理出来，跟大家好好聊聊。

不是一个文件夹，而是两个

很多人以为 .claude 文件夹只有一个，其实有两个。

一个在你的项目目录里，比如 your-project/.claude/，这是项目级的配置。另一个在你的用户主目录下，也就是～/.claude/，这是全局的个人配置。

项目级的文件夹是给团队用的。你把它提交到 Git 仓库里，团队里每个人拉下来之后，大家用的就是同一套规则、同一套自定义命令、同一套权限策略。

这就像给整个团队定了一个统一的工作标准。

全局的～/.claude/ 文件夹则是你个人的地盘。会话历史、自动记忆、个人偏好，这些只跟你自己有关的东西都放在这里。

下面这张图展示了两个文件夹的位置关系：

这种设计思路，其实在很多工具里都能看到。比如 Git 也有项目级的 .gitignore 和全局的～/.gitignore。

把「团队共识」和「个人偏好」分开管理，既保证了一致性，又给每个人留了定制空间。这种分层思维在日常工作中也很值得借鉴。

CLAUDE.md 才是核心中的核心

在整个 .claude 文件夹里，最重要的文件只有一个：CLAUDE.md。

当你启动 Claude Code 会话时，它做的第一件事就是读取 CLAUDE.md，把里面的内容加载到系统提示词里，整个对话过程中都会遵守你写的规则。

你告诉它「先写测试再写实现」，它就会这么做。你告诉它「错误处理不要用 console.log，用我们自定义的 logger 模块」，它每次都会照办。

换句话说，CLAUDE.md 就是你给 Claude 写的「工作手册」。

CLAUDE.md 可以放在三个地方：项目根目录（最常见）、～/.claude/CLAUDE.md（全局偏好）、以及子目录里（文件夹级别的规则）。Claude 会把它们全部读取并合并。

那 CLAUDE.md 里应该写什么呢？原文给了一个很清晰的建议。

适合写的内容包括：构建、测试、lint 的命令（比如 npm run test、make build 等），关键的架构决策（比如「我们用 Turborepo 管理 monorepo」），一些不太容易发现的坑（比如「TypeScript 开了严格模式，未使用的变量会报错」），以及导入规范、命名约定、错误处理风格这些。

不适合写的内容包括：已经在 linter 或 formatter 配置里定义过的规则、可以通过链接指向的完整文档、长篇大论的理论解释。

有一个很关键的建议：CLAUDE.md 控制在 200 行以内。

太长了会占用过多上下文窗口，Claude 对指令的遵守程度反而会下降。

原文给了一个大约 20 行的示例，包含命令、架构说明、代码约定和注意事项四个板块，简洁但信息密度很高。这个示例告诉我们，有效的指令不在于写得多，在于写得准。

这个道理放到日常工作中也一样。我们写文档、定规范、做沟通的时候，往往有一种冲动想要事无巨细全部写进去。

但信息过载的结果往往是没人看。精准、简洁、可执行，这才是好文档的标准。

个人偏好怎么办？用 CLAUDE.local.md

有时候你有一些偏好是只属于自己的。比如你喜欢用特定的测试框架，或者你习惯让 Claude 用某种特定的模式打开文件。

这时候可以在项目根目录创建一个 CLAUDE.local.md。Claude 会把它和主 CLAUDE.md 一起读取，但它会自动被 gitignore 掉，不会提交到仓库里。

下面这张图说明了 CLAUDE.local.md 的定位：

团队规则和个人偏好各归各的，互不干扰。这才是协作该有的样子。

当 CLAUDE.md 变得臃肿：rules 文件夹来救场

CLAUDE.md 在单个项目里用着挺好。

但随着团队变大，你会发现这个文件越来越长，300 行、500 行，到最后谁也不维护，谁也懒得看。

rules 文件夹 就是为了解决这个问题。

在 .claude/rules/ 目录下，每个 Markdown 文件都会自动和 CLAUDE.md 一起被加载。你可以按职责把指令拆开：

.claude/rules/
├── code-style.md
├── testing.md
├── api-conventions.md
└── security.md

负责 API 规范的人维护 api-conventions.md，负责测试标准的人维护 testing.md，各管各的，互不踩脚。

更厉害的地方在于，rules 文件支持 路径作用域。你可以在文件头部加一段 YAML 前置声明，让这个规则只在 Claude 处理特定路径的文件时才生效。

比如你定义了一套 API 设计规则，只有当 Claude 在 src/api/ 或 src/handlers/ 目录下工作时，这套规则才会被加载。它去编辑 React 组件的时候，这些规则完全不会出现。

没有设置 paths 字段的规则文件则会在每个会话中无条件加载。

这种「按需加载」的思路非常巧妙。上下文窗口是有限的资源，把不相关的指令塞进去只会浪费空间。

只在需要的时候加载需要的规则，既节省了上下文，又保证了指令的精准度。

其实这种模块化管理思维放到任何领域都适用。当一份文件开始变得谁都不想看的时候，与其苦苦维护，不如拆分成几个小而精的模块，各自独立、各自负责。

自定义斜杠命令：把重复操作一键搞定

Claude Code 内置了一些斜杠命令，比如 /help 和 /compact。而 commands 文件夹让你可以自己创建命令。

方法很简单：在 .claude/commands/ 目录下放一个 Markdown 文件，文件名就是命令名。比如 review.md 对应 /project:review，fix-issue.md 对应 /project:fix-issue。

下面这张图展示了自定义命令的创建方式：

最有意思的部分是，命令文件里可以用 ! 反引号语法来嵌入 shell 命令的输出。

举个例子，你写一个代码审查命令，在里面嵌入 git diff 的输出，Claude 就能自动拿到当前分支的改动内容来做审查。这不再是一段保存好的静态文本，而是一个真正可以执行的工作流。

命令还支持传参。用 $ARGUMENTS 占位符，运行命令时后面跟的内容就会自动替换进去。

比如 /project:fix-issue 234，Claude 就会自动去拉取第 234 号 issue 的内容，然后追踪问题、修复代码、编写测试，一条龙服务。

个人命令可以放在～/.claude/commands/ 里，以 /user:command-name 的形式调用，在所有项目中通用。适合放一些日常习惯性的操作，比如生成符合你习惯的 commit message，或者做一个每日站会的总结模板。

把高频操作封装成一条命令，这个思路在编程之外也很有价值。我们日常工作中有大量重复性动作，如果能花点时间把它们模板化、流程化，长期来看节省的时间是非常可观的。

Skills：让 Claude 自己判断什么时候该做什么

如果说 commands 是你主动触发的工具，那 skills 就是 Claude 自己判断该不该用的能力。

两者长得很像，但触发机制完全不同。

下面这张图直观展示了 commands 和 skills 的区别：

commands 是你输入一个斜杠命令来触发的，Claude 等着你来召唤。skills 则完全不一样，Claude 会监听对话内容，当任务匹配到某个 skill 的描述时，它会自动激活并执行。

每个 skill 住在 .claude/skills/ 下面的独立子目录里，核心是一个 SKILL.md 文件。这个文件用 YAML 前置声明来描述这个 skill 的用途和触发条件。

比如一个安全审查的 skill，描述里写着「当审查代码安全性、部署前检查、或用户提到安全相关话题时使用」。于是你只要说一句「帮我看看这个 PR 有没有安全问题」，Claude 就自动识别并调用这个 skill。

skills 和 commands 还有一个关键区别：skills 可以打包附带文件。

一个命令只是一个单独的 Markdown 文件，但一个 skill 是一个完整的目录，里面可以包含详细指南、模板、参考文档等等。通过 @ 引用语法，SKILL.md 可以拉取同目录下的其他文件。

这种「让 AI 自己判断时机」的设计，某种程度上代表了人机协作的一个方向。我们不再需要事无巨细地告诉工具该做什么，而是定义好规则和能力，让工具在合适的时候自动发挥作用。

Agents：专门的子智能体

当任务复杂到需要专家介入时，agents 文件夹 就派上用场了。

在 .claude/agents/ 目录下，每个 Markdown 文件定义一个子智能体。它有自己的系统提示词、工具权限和模型偏好。

比如定义一个 code-reviewer.md，系统提示词里写明它是一个专注于正确性和可维护性的高级代码审查员。当 Claude 需要做代码审查时，它会单独启动这个子智能体，在独立的上下文窗口里工作。

子智能体做完之后会压缩结果返回，主会话不会被大量中间过程的 token 占满。

下面这张图展示了 agents 的配置结构：

这里有两个值得注意的设计。

一个是 tools 字段。它限制了子智能体能使用的工具。比如一个安全审计智能体，它只需要读取和搜索文件的能力，完全没必要给它写文件的权限。

这种 最小权限原则 在安全领域是基本常识，用在 AI 工具上同样重要。

另一个是 model 字段。你可以给不同的子智能体指定不同的模型。简单的只读探索任务用小模型就够了（比如 Haiku），省钱又快。

真正需要深度推理的任务再上大模型（比如 Sonnet 或 Opus）。这种按需分配资源的思路，在 AI 使用成本越来越受关注的今天，很有实际意义。

权限管控：settings.json

.claude/settings.json 是 权限控制的核心文件。它决定了 Claude 能做什么、不能做什么。

整体结构很清晰：一个 allow 列表，一个 deny 列表。

allow 列表里的命令和操作，Claude 可以直接执行，不需要征求你的同意。一般来说，运行测试、查看 git 状态、读写文件这些日常操作放进去就行。

deny 列表里的命令则是完全禁止的，无论如何都不允许执行。比如 rm -rf 这类破坏性命令、curl 这类直接发起网络请求的命令、以及 .env 这类敏感文件的读取。

如果一个操作既不在 allow 列表也不在 deny 列表里，Claude 会在执行前先问你。这个中间地带的设计很聪明。

你不需要提前把所有可能的操作都想到，只需要定义好两端：明确允许的和明确禁止的，其余的交给交互确认。

同样的，settings.local.json 提供个人覆盖，自动被 gitignore，不会影响团队配置。

这种权限模型其实很有借鉴意义。在我们管理任何需要权限控制的系统时，白名单加黑名单再加中间的确认层，是一个既安全又灵活的方案。

全局文件夹：你的个人基地

～/.claude/ 这个全局文件夹虽然不需要经常打理，但了解它的存在很有必要。

～/.claude/CLAUDE.md 里写的内容会在你所有的 Claude Code 会话中生效。适合放一些跨项目的个人编码原则，比如「永远先定义类型再写实现」或者「优先使用函数式编程风格」。

～/.claude/projects/ 目录存储了按项目分类的会话记录和自动记忆。Claude Code 在工作过程中会自动给自己记笔记：它发现了哪些命令、观察到了什么代码模式、了解到了什么架构信息。

这些记忆会跨会话保留，你可以通过 /memory 命令来查看和编辑。

所以有时候你会发现 Claude 好像「记住」了你从来没告诉过它的东西。别惊讶，那是它的自动记忆在起作用。如果你想清空某个项目的记忆从头开始，也可以手动处理。

完整的文件结构一览

把上面说的所有内容汇总起来，整个 .claude 体系的文件结构是这样的：

your-project/
├── CLAUDE.md                  # 团队指令（提交到 Git）
├── CLAUDE.local.md            # 个人覆盖（gitignored）
│
└── .claude/
    ├── settings.json          # 权限与配置（提交到 Git）
    ├── settings.local.json    # 个人权限覆盖（gitignored）
    │
    ├── 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/                # 专用子智能体
        ├── code-reviewer.md
        └── security-auditor.md

～/.claude/
├── CLAUDE.md                  # 全局个人指令
├── settings.json              # 全局设置
├── commands/                  # 个人命令（所有项目通用）
├── skills/                    # 个人 skills（所有项目通用）
├── agents/                    # 个人 agents（所有项目通用）
└── projects/                  # 会话历史与自动记忆