摘要

文章全面剖析了 Claude Code 的隐藏控制中枢——.claude/ 文件夹。该目录分为项目级和全局级，是定义 Claude 行为、权限和记忆的关键。核心文件 CLAUDE.md 充当指令手册，直接影响系统提示词；rules/ 目录支持模块化和路径感知的指令管理；commands/ 允许创建自定义斜杠命令并执行 shell 脚本；skills/ 和 agents/ 则分别用于自动化工作流和专门的专家角色。此外，文章还介绍了 settings.json 如何通过白名单和黑名单机制管理工具权限，并提供了一套从零开始配置 Claude Code 的渐进式实践路径。

核心要点

  1. .claude/ 文件夹是 Claude Code 的行为控制中枢，分为项目级和全局级。

项目级配置随 Git 提交以实现团队同步，全局配置则存储个人偏好和跨项目的自动记忆。

  1. CLAUDE.md 是最重要的指令文件，直接决定了 Claude 的工作风格和规范。

它会被加载到系统提示词中，建议控制在 200 行以内，涵盖构建命令、架构决策和编码规范，避免冗余信息。

  1. 通过 rules/、commands/ 和 skills/ 实现高度定制化的 AI 协作。

rules 支持按路径生效的模块化指令，commands 提供手动触发的斜杠命令，而 skills 则是 Claude 根据对话上下文自动调用的工作流。

  1. settings.json 建立了安全边界，通过权限控制管理 AI 的工具调用。

利用 allow 和 deny 列表明确 Claude 可以执行的 Bash 命令和可以读取的文件范围，防止误删或敏感信息泄露。

金句摘录

.claude 文件夹是 Claude 在你项目中行为表现的控制中枢。你的指令、自定义命令、权限规则，甚至跨会话的 Claude 记忆，全都保存在这里。

你在 CLAUDE.md 中写什么，Claude 就会遵循什么。

命令：你输入它们。它们立即运行。技能：Claude 监视你的对话并在相关时触发它们。

.claude 文件夹本质上是一套协议，用来告诉 Claude 你是谁、你的项目做什么、它应该遵循什么规则。

正文

前言

一份关于 CLAUDE.md、自定义命令、技能、代理和权限配置的完整指南，手把手教你正确设置。

大多数 Claude Code 用户将 .claude 文件夹当作黑盒子。他们知道它存在。也见过它出现在项目根目录下，但从来没有打开过，更别提弄明白里面每个文件的用途了。

这实在是暴殄天物。

.claude 文件夹是 Claude 在你项目中行为表现的控制中枢。你的指令、自定义命令、权限规则，甚至跨会话的 Claude 记忆，全都保存在这里。一旦你搞清楚了什么文件放在哪里、为什么这样放，就能让 Claude Code 完全按照团队的需求来运作。

本指南将带你逐一剖析这个文件夹的完整结构 —— 从你每天都会用到的文件，到那些设置一次便可高枕无忧的文件。

两个文件夹，而非一个

图像

深入讲解之前，有一点值得先说清楚：实际上存在两个 .claude 目录，而不是一个。

一个位于你的项目内，另一个位于你的用户主目录：

  • 项目级：<your-project>/.claude/

  • 全局：~/.claude/

项目级文件夹包含团队配置。你将其提交到 git。团队中的每个人都获得相同的规则、相同的自定义命令和相同的权限策略。

全局 ~/.claude/ 文件夹包含你的个人偏好和本机状态，如会话历史和自动记忆。

CLAUDE.md：Claude 的指令手册

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

简单来说：你在 CLAUDE.md 中写什么，Claude 就会遵循什么。

如果你告诉 Claude 总是在实现之前编写测试，它就会这样做。如果你说 “永远不要使用 console.log 进行错误处理，总是使用自定义日志模块”，它每次都会尊重这一点。

最常见的做法是在项目根目录放一个 CLAUDE.md。但你也可以在 ~/.claude/CLAUDE.md 中设置一个，用于适用于所有项目的全局偏好，甚至可以在子目录中设置一个用于特定文件夹的规则。Claude 会读取所有这些并将它们组合起来。

CLAUDE.md 中实际应该包含什么

大多数人要么写太多，要么写太少。以下是有效的方法。

该写的：

  • 构建、测试和 lint 命令（npm run test、make build 等）

  • 关键的架构决策（“我们使用 Turborepo 管理 monorepo”）

  • 不易察觉的注意事项（“TypeScript 严格模式已开启，未使用的变量是错误”）

  • 导入约定、命名模式、错误处理风格

  • 主要模块的文件和文件夹结构

不该写的：

  • 任何已经由 linter 或 formatter 配置文件管控的内容

  • 可以通过链接查阅的完整文档

  • 大段大段解释理论的长篇文字

CLAUDE.md 的篇幅建议控制在 200 行以内。超出这个长度会开始大量消耗上下文窗口，Claude 对指令的遵循度反而会下降。

这是一个最小但有效的例子：

# 项目：Acme API
 ## 命令
 npm run dev          # 启动开发服务器
 npm run test         # 运行测试（Jest）
 npm run lint         # ESLint + Prettier 检查
 npm run build        # 生产环境构建
 ## 架构
 - Express REST API，Node 20
 - 通过 Prisma ORM 连接 PostgreSQL
 - 所有处理函数位于 src/handlers/
 - 共享类型定义位于 src/types/
 ## 规范
 - 每个处理函数必须使用 zod 进行请求校验
 - 返回值格式统一为 { data, error }
 - 绝不向客户端暴露堆栈信息
 - 使用 logger 模块，禁止使用 console.log
 ## 注意事项
 - 测试使用的是真实的本地数据库，而非 mock。请先运行 `npm run db:test:reset`
 - TypeScript 严格模式：绝不允许出现未使用的导入

这大约 20 行。它给了 Claude 在这个代码库中高效工作所需的一切，而无需不断澄清。

CLAUDE.local.md 用于个人覆盖

有时候你有一些个人偏好，只属于你自己，而非整个团队。也许你更习惯用另一个测试运行器，或者你希望 Claude 始终按某种特定方式打开文件。

在项目根目录中创建 CLAUDE.local.md。Claude 会将其与主 CLAUDE.md 一起读取，并且它会被自动 gitignore，所以你的个人调整永远不会进入仓库。

# 我的个人偏好
- 总是使用 vitest 而不是 jest
- 打开文件时，从 `src/` 目录开始

图像

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 设计规范
- 所有处理函数返回 { 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: 合并前审查当前分支的差异，排查问题
 ---
 ## 待审查的变更
 !`git diff --name-only main...HEAD`
 ## 详细差异
 !`git diff main...HEAD`
 请审查以上变更，重点关注：
 1. 代码质量问题
 2. 安全漏洞
 3. 测试覆盖缺失
 4. 性能隐患
 请针对每个文件给出具体、可操作的反馈。

现在在 Claude Code 中执行 /project:review，它会自动将真实的 git diff 注入提示词，然后再交给 Claude 处理。! 反引号语法会执行 shell 命令并嵌入其输出。这正是让这些命令真正实用 —— 而不仅仅是一段保存好的文本 —— 的关键所在。

向命令传递参数

使用 $ARGUMENTS 传递命令名称后的文本：

---
description: 调查并修复一个 GitHub issue
argument-hint: [issue-number]
---
查看本仓库中的 issue #$ARGUMENTS。
!`gh issue view $ARGUMENTS`
理解这个 bug，追溯到根本原因，修复它，
并编写一个能捕获该问题的测试。

执行 /project:fix-issue 234，就会将第 234 号 issue 的内容直接注入提示词。

个人命令与项目命令

.claude/commands/ 中的项目命令会被提交到仓库，与团队共享。如果某些命令你希望在所有项目中通用，就把它们放到 ~/.claude/commands/ 下。这类命令会以 /user:command-name 的形式出现。

实用的个人命令举例：每日站会助手、按照你的规范生成提交信息的命令，或者快速安全扫描。

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

前面已经介绍了命令的工作方式。技能（Skills）乍看之下与命令类似，但触发机制有本质区别。在继续深入之前，先把这个区别讲清楚：

  • 命令：你输入它们。它们立即运行。

  • 技 *：Claude 监视你的对话并在相关时触发它们。

技能是 Claude 可以自己调用的工作流，无需你输入斜杠命令，只要当前任务与技能的描述相匹配，它就会自动启动。命令等着你来召唤，而技能则在对话中伺机而动，时机一到便主动出击。

每个技能都有自己的子目录，包含 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 会读取描述信息，识别出与之匹配，然后自动调用该技能。你也可以通过 /security-review 显式调用。

与命令的关键区别在于：技能可以捆绑配套文件。上面的 @DETAILED_GUIDE.md 引用的是一份与 SKILL.md 放在一起的详细文档。命令是单个文件，而技能是一个完整的包。

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

agents/ 文件夹：专门的子代理角色

当一项任务复杂到需要一位专职专家来处理时，你可以在 .claude/agents/ 中定义子代理角色。每个代理都是一个 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 需要进行代码审查时，它会在一个独立的上下文窗口中生成这个代理。代理完成工作后，会压缩整理结论并汇报回来。你的主会话不会被成千上万个中间探索过程的 token 所淹没。

tools 字段限制了代理的能力范围。安全审计员只需要 Read、Grep 和 Glob，它没有理由去写文件。这种限制是刻意为之的，值得明确声明。

model 字段则允许你为专项任务使用更经济、更快速的模型。Haiku 可以胜任大多数只读探索工作。把 Sonnet 和 Opus 留给真正需要它们的任务。

个人代理放在 ~/.claude/agents/ 下，在你所有的项目中都可以使用。

自动生成代理

添加 description 字段，Claude 会在任务匹配时自动调用代理：

---
name: Security Auditor
description: 执行全面安全审计
model: sonnet-4
system: 你是一位安全专家。[...]
---

settings.json：权限和项目配置

.claude/ 目录下的 settings.json 文件控制着 Claude 能做什么、不能做什么。你在这里定义 Claude 可以运行哪些工具、可以读取哪些文件，以及在执行某些命令前是否需要先征得你的同意。

完整文件如下所示：

{
   "$schema": "https://raw.githubusercontent.com/anthropics/claude-code/main/settings-schema.json",
   "allow": {
     "Bash": ["npm run *", "make *"],
     "Read": true,
     "Write": true,
     "Edit": true,
     "Glob": true,
     "Grep": true
   },
   "deny": {
     "Bash": ["rm -rf *", "curl *"],
     "Read": [".env", "secrets/**"]
   },
   "context": {
     "maxFiles": 1000,
     "maxLinesPerFile": 10000
   },
   "diff": {
     "autoStage": false,
     "maxLines": 500
   }
 }

以下是每个部分的作用。

$schema 这一行用于在 VS Code 或 Cursor 中启用自动补全和行内校验。务必加上。

allow 列表包含 Claude 无需请求确认即可直接执行的命令。对于大多数项目，一个合理的白名单应覆盖：

  • Bash(npm run *)

    或 Bash(make *)，让 Claude 可以自由运行你的脚本

  • Bash(git *)

    用于只读的 git 命令

  • Read、Write、Edit、Glob、Grep 用于文件操作

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/ 存放可在所有项目中使用的个人命令和技能。

通常你不需要手动管理这些文件。但知道它们的存在很有用 —— 比如当 Claude 似乎 “记住” 了你从未告诉过它的东西，或者当你想清除某个项目的自动记忆、从零开始时。

全景总览

这就是所有东西如何组合在一起：

项目根目录:
├── .claude/
│   ├── CLAUDE.md           # 团队指令（已提交）
│   ├── CLAUDE.local.md     # 个人覆盖（已 gitignore）
│   ├── rules/              # 模块化规则（已提交）
│   │   ├── api-conventions.md
│   │   └── testing.md
│   ├── commands/           # 团队斜杠命令（已提交）
│   │   └── review.md
│   ├── skills/             # 团队技能（已提交）
│   │   └── security-review/
│   ├── agents/             # 团队代理（已提交）
│   │   └── code-reviewer.md
│   ├── settings.json       # 权限（已提交）
│   └── settings.local.json # 个人设置（已 gitignore）
└── ...你的项目文件...
全局 (~/.claude/):
├── CLAUDE.md              # 全局偏好
├── commands/              # 个人命令
├── skills/                # 个人技能
├── 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% 的项目真正需要的全部配置。技能和代理则适用于那些值得打包封装的、反复出现的复杂工作流。

关键洞察

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

CLAUDE.md 是你投入产出比最高的文件。先把它写好，其他一切都是锦上添花。

从小处着手，在实践中不断打磨，把它当作项目基础设施的一部分来对待 —— 就像其他基础设施一样，一旦配置到位，便能日复一日地为你带来回报。

原文：https://x.com/akshay_pachaar/status/2035341800739877091