Skip to content

从 .claude 文件夹读懂 Claude Code

摘要总结: 针对 AI 编程范式从 Vibe Coding 向 Agentic Engineering 跃迁的背景,深入拆解 Claude Code 工具的核心配置体系。通过分析 .claude 目录结构,系统阐述全局与项目级两级配置的设计思路,详细解读 CLAUDE.md、rules、commands、skills、agents 等模块的功能定位与使用场景,并结合权限隔离、模块化扩展等设计原则,为团队协作提供可落地的配置方案。

1. 引言

在过去的两年里,AI 编程领域经历了剧烈的范式震荡。当开发者们还在争论 Vibe Coding 是否只是昙花一现时,AI 已经悄然完成了三次跃迁:从最初"动动嘴皮子就能生成完整项目"的魔法时刻,到编辑器里那个如影随形的智能补全伙伴,再到如今能够独立思考、规划并执行复杂工程任务的 Agentic Engineering——AI 不再只是工具,而是正在成为真正的"自主工程师"。

在这场变革中,Claude Code 无疑是最具代表性的工具,深入理解其内部机制,可以帮助我们更好地利用 Claude Code 的功能,提高开发效率。本文就从 .claude 文件夹开始,深入拆解 Claude Code 的内部机制,从而理解 Claude Code 的工作原理。

2. 目录概览

Claude Code 通过 .claude/ 文件夹实现配置与扩展,支持全局配置~/.claude/)和项目级配置(项目根目录下的 .claude/)两级体系:

  • 全局:~/.claude/,包含个人偏好、本机状态,如会话历史和自动记忆。
  • 项目级:<your-project>/.claude/团队配置,提交到 git 每个人都能获得相同的规则、自定义命令和权限设置策略。
markdown
全局 (~/.claude/): 
├── CLAUDE.md          # 全局偏好,定义个人习惯的交互风格
├── commands/          # 个人自定义斜杠命令
├── skills/            # 个人技能,封装可复用的工作流
├── agents/            # 个人代理,定义专属的子智能体角色
└── projects/          # 自动记忆和会话历史(由系统自动管理)

项目级的 .claude/ 是团队协作的核心载体,可提交到 Git 仓库:

markdown
项目根目录:
├── .claude/
│   ├── CLAUDE.md              # 团队指令:定义项目规范、编码风格等(提交)
│   ├── CLAUDE.local.md        # 个人覆盖:本地个性化设置(gitignore)
│   ├── settings.json          # 权限+配置:团队统一的权限策略(提交)
│   └── settings.local.json    # 个人权限:本地私有配置( gitignore)
│   ├── commands/              # 团队斜杠命令:如 /review、/deploy 等(提交)
│   │   ├── review.md          # → /project: 审查
│   │   ├── fix-issue.md       # → /project: 修复问题
│   │   └── deploy.md          # → /project: 部署
│   ├── rules/                 # 模块化规则:拆分的大型指令文件(提交)
│   │   ├── code-style.md
│   │   ├── testing.md
│   │   └── api-conventions.md
│   ├── skills/                # 团队技能:自动触发的工作流(提交)
│   │   ├── security-review/
│   │   │   └── SKILL.md
│   │   └── deploy/
│   │       └── SKILL.md
│   └── agents/                # 子智能体角色:专注特定任务的 AI 代理(提交)
│       ├── code-reviewer.md
│       └── security-auditor.md
└── ...你的项目文件...

文件作用说明

文件/目录说明
CLAUDE.md项目的"系统提示词",定义团队编码规范、技术栈约束、输出格式要求等
CLAUDE.local.md本地个人偏好覆盖,如喜欢的注释风格、调试习惯等
settings.json团队统一的权限策略,如允许/禁止的操作、API 密钥的引用方式
commands/自定义斜杠命令,将常用操作封装为 /review/deploy 等快捷指令
rules/模块化规则文件,避免单个 CLAUDE.md 过于臃肿,可按主题拆分
skills/自动触发的工作流,当满足特定条件时自动执行(如代码提交前自动安全检查)
agents/子智能体角色,定义专注特定任务的 AI 人格(如专注安全的审计员、专注代码质量的审查者)

从目录结构中,我们可以看出三个关键设计思想:

设计原则说明体现
权限隔离通过 .local 后缀区分团队共享与个人私有配置,敏感信息不上传CLAUDE.local.mdsettings.local.json
模块化将庞大指令拆分为可复用的规则、命令和技能rules/commands/skills/ 目录
自动化Skill 可在特定条件下自动触发,Agent 可独立执行子任务skills/(⚡自动)、agents/(💬隔离)

3. CLAUDE.md:最核心的配置文件

启动 Claude Code 会话时,它做的第一件事就是读取 CLAUDE.md,将其直接加载到系统提示词中,并在整个对话过程中时刻参照。这意味着你告诉 Claude 的每一项规则——比如"总是在实现之前编写测试"或"永远不要使用 console.log,总是使用自定义日志模块"——都会在后续的每一次交互中被严格执行。

CLAUDE.md 的放置位置决定其作用范围:

位置作用范围提交到 Git
~/.claude/CLAUDE.md全局:对所有项目生效
项目根目录或 .claude/CLAUDE.md项目级:团队共享上下文
子目录中的 CLAUDE.md目录级:特定文件夹的规则

如果需要在项目中覆盖全局配置,可在项目根目录创建 CLAUDE.local.md,它会优先生效(通常已加入 .gitignore)。

3.1 应该写什么

CLAUDE.md 的篇幅建议控制在 200 行以内。过于冗长的配置会大量消耗上下文窗口,反而降低指令遵循度。

应该写的核心内容:

  • 命令:构建、测试、lint 等常用命令(如 npm run testmake build
  • 架构决策:关键的技术选型(如"我们使用 Turborepo 管理 monorepo")
  • 目录结构:主要模块的划分和组织方式
  • Code Style:导入约定、命名规范、错误处理风格
  • 注意事项:容易被忽略的坑点(如"TypeScript 严格模式已开启,未使用的变量是错误")

不该写的:

  • 任何已由 linter 或 formatter 配置文件管控的内容
  • 可以通过链接查阅的完整文档
  • 大段解释理论的长篇文字

3.2 示例

下面是一个 CLAUDE.md 模板示例,方括号 [...] 中的内容为提示,需要替换为你的项目信息:

markdown
# 项目:[项目名称]

[一句话背景:这是一个什么项目?描述项目的核心功能和特点。比如:"一个基于 RAG 的企业内部知识库问答系统,使用 Next.js + FastAPI 构建。" 一句话提供的信息往往比你想象中要多。]

## 技术栈
- **前端**:[你的前端技术,如 Next.js、React、Vue]
- **后端**:[你的后端技术,如 FastAPI、Django、Express]
- **数据库**:[数据库类型,如 PostgreSQL、MongoDB]
- **AI**:[AI 相关技术,如 OpenAI API、Claude API、本地模型]
- **部署**:[部署方式,如 Docker、Kubernetes、Vercel]

## 命令
[列出常用命令及说明]
npm run dev          # [启动开发服务器]
npm run test         # [运行测试]
npm run lint         # [代码检查]
# ...其他命令

## 架构
- `[目录/模块1]`:[说明这个目录的作用]
- `[目录/模块2]`:[说明这个目录的作用]
- `[共享模块路径]`:[如共享类型、工具库等]

## 规范
- [团队统一的编码规范,如统一的 API 风格、命名约定]
- [必须遵守的规则,如"禁止直接操作数据库,必须通过 ORM""]
- [代码质量要求,如"所有函数必须有类型注解""]

## 坑点 / 注意事项(Gotchas)
- [容易踩坑的地方,如"测试需要先启动 Docker""]
- [环境配置注意点,如".env.local 已加入 gitignore""]
- [版本或依赖的特殊要求]

3.3 如何创建 CLAUDE.md

最快捷的方式是使用 /init 命令。Claude 会根据项目结构和检测到的技术栈,自动生成一个初始版本的 CLAUDE.md

4. rules/:模块化规则

当项目从个人项目成长为团队协作时,CLAUDE.md 往往会逐渐膨胀——技术栈说明、编码规范、API 约定、安全要求...... 300 行的配置不仅难以维护,新成员也难以快速定位所需内容。

.claude/rules/ 正是为解决这一问题而生。该目录下的每个 Markdown 文件会与 CLAUDE.md 一起自动加载,你可以通过拆分规则文件实现关注点分离:

.claude/rules/
├── code-style.md        # 代码风格规范
├── testing.md           # 测试相关规范
├── api-conventions.md   # API 设计约定
└── security.md          # 安全相关要求

这样一来,CLAUDE.md 只需保留项目概述和核心规则,而具体的规范则分散到对应的规则文件中。

4.1 路径过滤:让规则精准生效

规则文件支持 YAML frontmatter 配置,只有当 Claude 操作的文件匹配指定路径时,对应规则才会激活。这一特性使得规则可以做到"在正确的场景下自动出现":

yaml
---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

# API 设计规范

## 请求处理
- 所有处理函数返回 `{ data, error }` 格式
- 使用 zod 校验请求体,拒绝无效输入
- 绝不向客户端暴露内部错误详情

## 响应规范
- 分页接口统一使用 `meta.page`、`meta.total` 返回元信息
- 错误响应必须包含机器可读的错误码,便于前端做分支处理

上面这条规则只会在操作 src/api/src/handlers/ 目录下的 TypeScript 文件时生效,避免了规则的"噪音"污染。

4.2 何时该拆分到 rules/

一个简单的判断标准:当某个规范需要独立编辑、独立 review,或可能由不同人负责时,就该拆分出来。

场景建议
仅有 3-5 条规则留在 CLAUDE.md 中即可
规则与特定目录强相关(如只在 API 层生效)拆分到 rules/api-conventions.md,用 paths 限制
规则需要团队协作维护独立成文件,便于 code review
规则可能因技术演进而频繁变化拆分,降低主文件变动频率

4.3 规则文件的组织建议

  • 按关注点命名security.mdtesting.mddatabase.md
  • 保持单一职责:一个文件只讨论一个主题
  • 规则要具体:避免模糊描述(如"代码要写得好"),使用可验证的表述(如"所有导出函数必须有 JSDoc 注释")
  • 善用 paths:路径过滤不仅能避免噪音,还能在正确时机唤醒正确规则,提升 Claude 的响应准确性

5. commands/:自定义斜杠命令

commands/ 让我们可以将常用的工作流封装为斜杠命令(如 /review/deploy),一键触发复杂的自动化操作。每个 Markdown 文件会自动变成一个可调用的命令。

5.1 命令的存放位置

位置作用范围典型用途
~/.claude/commands/全局个人习惯、跨项目通用操作
.claude/commands/项目级团队标准化流程、需团队共享的操作

5.2 命令的结构

一个命令文件由 YAML frontmatter 和执行指令两部分组成:

yaml
---
name: commit-added
description: 智能提交已 git add 的代码,自动生成符合规范的 commit message
---

请帮我提交当前已经 git add 的代码。按照以下步骤执行:

1. 检查 git 状态,确认哪些文件已被 staged
2. 查看 staged 文件的具体修改内容(`git diff --cached`)
3. 根据修改内容生成 commit message,格式为 `type(scope): description`
   - type 可选:feat, fix, docs, style, refactor, test, chore 等
4. 在 message 尾部添加一行 `Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>`
5. 执行 `git commit` 并显示提交结果

注意:
- 只提交已 staging 的文件,不处理未 add 的文件
- 若无 staged 文件,提示用户并拒绝执行提交
- Co-Authored-By 行必须作为最后一行,前面有空行分隔
  • name:命令名称(用于调用,如 /commit-added
  • description:命令说明,会显示在帮助信息中
  • YAML frontmatter 之后的内容:Claude 执行的具体指令

5.3 传递参数:$ARGUMENTS

使用 $ARGUMENTS 占位符接收命令后的额外输入:

yaml
---
name: explain
description: 解释代码片段,支持传递要解释的内容
---

请解释以下代码:

$ARGUMENTS

调用 /explain some code here 时,$ARGUMENTS 会被替换为 some code here

5.4 命令的价值

为什么值得使用 commands?想象几个场景:

  • 每次代码审查都要重复说"请检查这三个文件的潜在安全问题" → 封装为 /security-review src/api/**/*.ts
  • 每次部署都要确认环境、权限、回滚策略 → 封装为 /deploy staging,一键完成
  • 新成员不知道如何正确初始化项目环境 → 封装为 /init-dev,包含所有 setup 步骤

commands 的核心价值在于:将共性的、繁琐的、需要固定流程的操作封装起来,一次定义、多次复用。这样你只需关注"做什么",而不必每次重复交代"怎么做"。

编写命令的最佳实践:

  1. 命令要原子化:一个命令只做一件事,避免将多个操作强行合并
  2. 指令要具体:明确告诉 Claude 每个步骤做什么,而不是模糊的"帮我处理"
  3. 善用 $ARGUMENTS:将可变部分作为参数传入,保持命令的通用性
  4. 添加边界条件:说明什么情况下命令应该拒绝执行或提示用户(如文件不存在、环境未就绪)
  5. 全局 vs 项目:仅跨项目通用的操作放在 ~/.claude/commands/,团队特定流程放在 .claude/commands/

常见的命令场景:

命令适用场景封装的内容
/review [files]代码审查检查范围、审查重点、输出格式
/deploy [env]应用部署环境确认、构建、上传、回滚流程
/changelog生成更新日志git log 解析、格式规范、分类规则
/test-record测试与报告运行测试、生成覆盖率、存档
/migration [name]数据库迁移创建迁移文件、编写 up/down、校验
/init-dev项目初始化安装依赖、配置环境、同步种子数据

6. skills/:自动触发的工作流

如果说 commands/ 是你"主动召唤"的助手,那么 skills/ 则是"时刻待命"的专家——你不需要告诉它什么时候上场,它会根据上下文自行判断是否该出手。

6.1 技能与命令的根本区别

特性commands/skills/
触发方式你输入 /xxx,它立即执行AI 判断当前任务匹配时自动触发
主动性被动等待指令主动观察、伺机而动
复杂度单个 Markdown 文件一个完整的包(可包含多个文件)
适用场景明确的、一次性的操作序列需要配套文档的复杂工作流

用一句话总结:命令是你告诉 AI"去做这件事",技能是 AI 看到某类任务时主动说"这件事我擅长,让我来"

6.2 技能的结构

每个技能独占一个子目录,至少包含 SKILL.md,还可包含配套文档:

.claude/skills/
└── security-review/           # 安全审查技能
    ├── SKILL.md               # 技能定义:名称、触发条件、核心逻辑
    └── GUIDE.md                # 详细指南:检查清单、漏洞分类、修复建议

SKILL.md 的核心是 YAML frontmatter 中的触发条件描述:

yaml
---
name: security-review
description: 自动检测代码中的安全漏洞和潜在风险
triggers:
  - "安全审查"
  - "检查漏洞"
  - "security audit"
---

# 安全审查技能

当检测到以下关键词时自动触发:安全、漏洞、audit、permission...

本技能执行以下检查:
1. SQL 注入风险检测
2. XSS 向量识别
3. 权限校验缺失提醒
4. 敏感信息硬编码检查

详细检查清单参见 @DETAILED_GUIDE.md
  • triggers:触发关键词列表,当对话中出现相关内容时自动匹配
  • @DETAILED_GUIDE.md:引用同目录下的详细文档,保持主文件简洁

6.3 技能的使用场景

技能特别适合那些触发条件明确、但执行逻辑复杂的工作:

技能触发场景为什么用技能而非命令
security-review/代码审查时提到"安全"、"漏洞"检查清单长,需要配套文档
deploy/提到"部署"、"发布"、"上线"流程复杂,包含审批和回滚
refactor/提到"重构"、"优化代码"有特定的模式和反模式清单
migration/数据库变更、Schema 修改需要校验和回滚方案

6.4 何时用命令,何时用技能

一个简单的判断标准:

  • 步骤固定、但每次都要你提醒 → 用命令(如 /changelog
  • AI 应该自己判断时机、自动介入 → 用技能(如安全审查不应该每次都手动触发)

在实际项目中,两者往往配合使用:你用 /review 启动代码审查,审查过程中如果涉及到安全问题,AI 会自动触发 security-review 技能介入,形成多层防护。

关于 Agent Skills 的详细规范和编写方法,可参考另一篇文章:如何编写一个高可用的 Agent Skill?从机制拆解到生产实践指南

7. agents/:独立执行的专职角色

当任务的复杂度上升到需要"专人负责"时,agents/ 提供了另一种抽象层次:不是把某段指令封装起来,而是创造一个拥有独立身份、独立上下文、独立判断能力的角色。

7.1 为什么需要 agents

对比一下三种扩展机制:

机制本质执行方式上下文
commands/封装一段指令你调用,它执行共享主会话
skills/封装一套流程触发后自动执行共享主会话
agents/创造一个角色主 Agent 指派它执行独立隔离

agents 的核心价值在于上下文隔离。当 Code Reviewer 在独立窗口中审查数千行代码时,这些中间过程不会污染主会话;当 Security Auditor 反复追问"这个 API 调用真的必要吗",主会话中的项目上下文依然清晰。

另一个关键点:避免利益冲突。试想,让同一个 AI 同时写代码和审查代码,它往往会为自己的代码辩护——"这段逻辑是合理的"。但如果审查工作由独立的 agent 执行,它没有任何"需要捍卫的代码",审查结论会更客观。

7.2 agents 的定义结构

在 Claude Code 中,每个 agent 是放置在 agents/ 目录下的一个 Markdown 文件中,通过 YAML frontmatter 定义其能力边界:

yaml
---
name: code-reviewer
description: 资深代码审查专家,专注于正确性和可维护性
model: sonnet
tools: Read, Grep, Glob, Bash
---

你是代码审查专家。当主 Agent 发起代码审查请求时,执行以下工作:

1. 全面审查:检查逻辑错误、边界条件、错误处理
2. 重点关注:安全性、并发问题、潜在的性能瓶颈
3. 忽略范围:代码风格(由 linter 负责)、无关紧要的偏好问题

输出格式:
- 发现的问题按严重程度分为:🔴 阻断、🟡 建议、🟢 优化
- 每个问题说明:位置 → 原因 → 修复建议

其中 tools 字段是刻意设计的最小权限原则:Code Reviewer 只需要读取代码,不应该能修改文件;Security Auditor 只需要搜索和读取,不应该能执行命令。限制工具就是限制风险。

7.3 agents vs skills:谁是更好的选择

两者都会在特定场景下被触发,但性质不同:

判断维度skills/agents/
触发方式通过关键词匹配自动激活由主 Agent 显式指派
执行者身份无身份的技能执行有独立身份的角色
上下文共享主会话独立隔离的上下文窗口
适用场景标准化、可复用的流程需要独立判断的复杂任务

一个直观的场景选择:

  • 代码提交前自动安全检查 → 用 security-review skill,因为这是一个标准流程。
  • 某次 PR 需要多人协作审查 → 指派一个独立的 code-reviewer agent,它有独立的判断空间。

agents 的实战场景:

Agent何时触发为什么需要独立身份
code-reviewer主 Agent 指派审查任务避免"既当运动员又当裁判"
security-auditor涉及认证、权限、数据操作时需要深入追问,隔离上下文不干扰主任务
performance-profiler性能问题排查时生成大量分析数据,不应进入主会话
database-expertSchema 变更、数据迁移时需要专门的数据库上下文知识

agents/ 代表着 Claude Code 向"多智能体协作"方向的演进:主 Agent 不再是全能选手,而是演变为一个任务协调者,将专业工作交给专业的 agent 去执行。

8. settings.json:权限与项目配置

settings.json 定义了 Claude Code 在项目中的行为边界——哪些操作可以直接执行,哪些需要确认,哪些完全禁止。这是一种预防机制,在危险操作发生之前就将其拦截。

8.1 配置结构

json
{
  "allow": {
    "Bash": ["npm run *", "pnpm run *", "make *"],
    "Read": true,
    "Write": true,
    "Edit": true,
    "Glob": true,
    "Grep": true
  },
  "deny": {
    "Bash": ["rm -rf *", "curl *", "wget *"],
    "Read": [".env", "secrets/**", "credentials/**"]
  },
  "context": {
    "maxFiles": 1000,
    "maxLinesPerFile": 10000
  },
  "diff": {
    "autoStage": false,
    "maxLines": 500
  }
}

allow:白名单,Claude 无需请求确认即可执行的命令或操作

deny:黑名单,Claude 完全禁止执行的命令或访问的文件

context:上下文限制,控制 Claude 能读取的文件数量和大小

diff:diff 相关配置,如自动 staging、diff 行数上限

8.2 典型场景

场景配置方式
允许运行测试、构建命令"Bash": ["npm run test", "npm run build"]
禁止删除操作、危险命令"Bash": ["rm -rf *", "mkfs *"]
禁止读取敏感文件"Read": [".env", "secrets/**"]
限制大文件处理"maxLinesPerFile": 5000

8.3 settings.local.json:个人权限覆盖

CLAUDE.local.md 的设计理念相同——将团队共识与个人偏好分离:

  • settings.json:团队统一的权限策略,提交到 Git
  • settings.local.json:个人特殊需求,不提交(已加入 .gitignore

例如,你在本地可能需要更高的权限来做调试,但在团队配置中这些是高风险操作,此时可以在 settings.local.json 中覆盖。

9. 结语

综合以上分析,.claude/ 目录的设计思路可以归纳为:

  • 层级分明~/.claude/ 处理个人偏好,项目/.claude/ 处理团队共识,分工明确。

  • 渐进扩展:从最简单的 CLAUDE.md 单文件,到 rules/ 的模块化拆分,再到 commands/skills/agents/ 的自动化能力,配置复杂度可以根据项目需求逐步升级。

  • 安全优先settings.json 的白名单/黑名单机制,确保 AI 在受控范围内执行操作。

  • 团队协作*.local 文件与主配置的分离设计,让团队标准和个人自由可以共存。

理解这些设计思想,比记住具体的配置项更重要。当我们面对一个新项目时,可以从 CLAUDE.md 开始,逐步引入 rules/ 整理规范,用 commands/ 封装重复操作,让 skills/ 在关键时刻自动介入,在需要专业判断时指派 agents/

这样一个渐进式的能力建设,正是 Claude Code "授人以渔"的设计初衷。

延伸阅读: