✦✦Firefly Labs Studio
Back to translations

深入了解 .claude/ 文件夹

CLAUDE.md、自定义命令、Skills、Agents 和权限的完整配置指南

Akshay Pachaar·2026-03-21·Published on 2026-03-25·Original article

image

关于 CLAUDE.md、自定义命令、技能、智能体和权限的完整指南，以及如何正确配置它们。

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

这其实是个遗憾。

.claude 文件夹是控制 Claude 在项目中行为的中枢。它存放着你的指令、自定义命令、权限规则，甚至还有跨会话的记忆。一旦你搞清楚了每个文件和目录的用途，就能把 Claude Code 配置成团队真正需要的样子。

本指南将带你完整了解这个文件夹的结构，从每天都会用到的文件，到配置一次就很少再碰的部分。

两个文件夹，不是一个

在深入之前，有件事值得提前了解：实际上存在两个 .claude 目录，而不是一个。

第一个在项目内部，第二个在你的主目录中：

image

项目级别的文件夹存放团队配置。你把它提交到 git，整个团队都会获得相同的规则、自定义命令和权限策略。

全局的 ~/.claude/ 文件夹则存放你的个人偏好和机器本地状态，比如会话历史和自动记忆功能。

CLAUDE.md：Claude 的使用手册

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

简单来说：你在 CLAUDE.md 里写什么，Claude 就会照做。

如果你告诉 Claude 永远先写测试再写实现，它会的。如果你写"不要用 console.log 来处理错误，必须使用自定义的日志模块"，它每次都会遵守。

在项目根目录放置 CLAUDE.md 是最常见的做法。但你也可以在 ~/.claude/CLAUDE.md 中放一个全局配置文件，让它对所有项目生效，甚至还可以在子目录中放置文件来定义特定文件夹的规则。Claude 会读取所有这些文件并合并它们。

CLAUDE.md 里到底该写什么

大多数人的做法要么太多，要么太少。下面是真正有效的方式。

应该写：

  • 构建、测试和代码检查命令（npm run test、make build 等）
  • 关键的架构决策（"我们使用 Turborepo 的单体仓库"）
  • 不太明显的坑（"TypeScript 严格模式已开启，未使用的变量会报错"）
  • 导入规范、命名模式、错误处理风格
  • 主要模块的文件和文件夹结构

不要写：

  • 属于 linter 或格式化配置的内容
  • 已经有链接可查的完整文档
  • 解释理论的长段落

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 掉，所以你的个人小调整永远不会进入代码仓库。

image

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 设计规则

- 所有 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。文件名就是命令名。

image

来一个简单的例子。创建 .claude/commands/review.md：

---
description: Merge 前审查当前分支的 diff，查找问题
---
## 待审查的变更

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

## 详细 Diff

!`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 会把 issue 234 的内容直接送入提示词。

个人命令 vs 项目命令

.claude/commands/ 里的项目命令会被提交、和团队共享。对于那些无论在哪个项目都想用的命令，放在 ~/.claude/commands/。这些会显示为 /user:command-name。

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

skills/ 目录：按需调用的可复用工作流

现在你已经了解了 commands 的工作方式。Skills 表面上看起来很像，但触发机制有着本质的不同。在继续之前，先把这个区别说清楚：

image

Skills 是一种工作流，当任务描述与 skill 的描述相匹配时，Claude 可以自动调用它，而不需要你输入斜杠命令。Commands 被动等待你的调用，而 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.

当你说出"review this PR for security issues"时，Claude 会读取描述，识别出匹配项，然后自动调用这个 skill。当然，你也可以通过 /security-review 显式调用它。

Skills 和 commands 的关键区别在于：skills 可以打包附带的支持文件。上面的 @DETAILED_GUIDE.md 引用会拉取一个与 SKILL.md 同目录下的详细文档。Commands 是单文件，Skills 则是打包好的工具包。

个人 skills 放在 ~/.claude/skills/ 目录下，会在所有项目中生效。

agents/ 目录：专业化的子智能体角色

当某个任务足够复杂，值得一个专门的专家来处理时，你可以在 .claude/agents/ 中定义一个子智能体角色。每个 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/ 目录下，会在所有项目中生效。

image

settings.json：权限与项目配置

.claude/ 目录下的 settings.json 控制着 Claude 允许和禁止做的事情。它定义了 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/ 目录下的任何东西

如果某个命令既不在 allow 列表也不在 deny 列表中，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 似乎"记住"了你从未告诉过它的事情，或者当你想要清空某个项目的自动记忆、重新开始的时候。

全景图

下面是所有内容是如何组合在一起的：

your-project/
├── CLAUDE.md                  # 团队指令（提交到版本库）
├── CLAUDE.local.md            # 个人覆盖设置（git 忽略）
│
└── .claude/
    ├── settings.json          # 权限 + 配置（提交到版本库）
    ├── settings.local.json    # 个人权限覆盖（git 忽略）
    │
    ├── 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/                # 自动触发的workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    │
    └── agents/                # 专业化子agent角色
        ├── code-reviewer.md
        └── security-auditor.md

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

从零开始的实用配置

如果你从零开始，以下是一个行之有效的进阶路线。

第一步。 在 Claude Code 中运行 /init。它会通过分析你的项目生成一个 CLAUDE.md 模板。然后把它精简到核心内容。

第二步。 创建 .claude/settings.json，配置适合你技术栈的 allow/deny 规则。至少要允许运行命令、禁止读取 .env 文件。

第三步。 为你最常用的工作流创建一到两个命令。代码审查和 issue 修复是不错的起点。

第四步。 随着项目增长，CLAUDE.md 变得拥挤时，开始把指令拆分到 .claude/rules/ 文件中。有道理的话，按路径来组织作用域。

第五步。 添加一个 ~/.claude/CLAUDE.md 放你的个人偏好。比如"总是先写类型再写实现"或者"优先使用函数式模式而非类"。

这就是 95% 的项目真正需要的全部东西。Skills 和 agents 只有在你有值得打包的重复复杂工作流时才会派上用场。

核心洞见

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

CLAUDE.md 是你杠杆效应最高的文件。先把这个搞对。其他都是优化。

从小处着手，边走边完善。把它当成项目中其他基础设施的一部分来对待——一旦配置好，每天都会持续产生回报。