从 .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 每个人都能获得相同的规则、自定义命令和权限设置策略。
全局 (~/.claude/):
├── CLAUDE.md # 全局偏好,定义个人习惯的交互风格
├── commands/ # 个人自定义斜杠命令
├── skills/ # 个人技能,封装可复用的工作流
├── agents/ # 个人代理,定义专属的子智能体角色
└── projects/ # 自动记忆和会话历史(由系统自动管理)项目级的 .claude/ 是团队协作的核心载体,可提交到 Git 仓库:
项目根目录:
├── .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.md、settings.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 test、make build) - 架构决策:关键的技术选型(如"我们使用 Turborepo 管理 monorepo")
- 目录结构:主要模块的划分和组织方式
- Code Style:导入约定、命名规范、错误处理风格
- 注意事项:容易被忽略的坑点(如"TypeScript 严格模式已开启,未使用的变量是错误")
不该写的:
- 任何已由 linter 或 formatter 配置文件管控的内容
- 可以通过链接查阅的完整文档
- 大段解释理论的长篇文字
3.2 示例
下面是一个 CLAUDE.md 模板示例,方括号 [...] 中的内容为提示,需要替换为你的项目信息:
# 项目:[项目名称]
[一句话背景:这是一个什么项目?描述项目的核心功能和特点。比如:"一个基于 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 操作的文件匹配指定路径时,对应规则才会激活。这一特性使得规则可以做到"在正确的场景下自动出现":
---
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.md、testing.md、database.md - 保持单一职责:一个文件只讨论一个主题
- 规则要具体:避免模糊描述(如"代码要写得好"),使用可验证的表述(如"所有导出函数必须有 JSDoc 注释")
- 善用 paths:路径过滤不仅能避免噪音,还能在正确时机唤醒正确规则,提升 Claude 的响应准确性
5. commands/:自定义斜杠命令
commands/ 让我们可以将常用的工作流封装为斜杠命令(如 /review、/deploy),一键触发复杂的自动化操作。每个 Markdown 文件会自动变成一个可调用的命令。
5.1 命令的存放位置
| 位置 | 作用范围 | 典型用途 |
|---|---|---|
~/.claude/commands/ | 全局 | 个人习惯、跨项目通用操作 |
.claude/commands/ | 项目级 | 团队标准化流程、需团队共享的操作 |
5.2 命令的结构
一个命令文件由 YAML frontmatter 和执行指令两部分组成:
---
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 占位符接收命令后的额外输入:
---
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 的核心价值在于:将共性的、繁琐的、需要固定流程的操作封装起来,一次定义、多次复用。这样你只需关注"做什么",而不必每次重复交代"怎么做"。
编写命令的最佳实践:
- 命令要原子化:一个命令只做一件事,避免将多个操作强行合并
- 指令要具体:明确告诉 Claude 每个步骤做什么,而不是模糊的"帮我处理"
- 善用
$ARGUMENTS:将可变部分作为参数传入,保持命令的通用性 - 添加边界条件:说明什么情况下命令应该拒绝执行或提示用户(如文件不存在、环境未就绪)
- 全局 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 中的触发条件描述:
---
name: security-review
description: 自动检测代码中的安全漏洞和潜在风险
triggers:
- "安全审查"
- "检查漏洞"
- "security audit"
---
# 安全审查技能
当检测到以下关键词时自动触发:安全、漏洞、audit、permission...
本技能执行以下检查:
1. SQL 注入风险检测
2. XSS 向量识别
3. 权限校验缺失提醒
4. 敏感信息硬编码检查
详细检查清单参见 @DETAILED_GUIDE.mdtriggers:触发关键词列表,当对话中出现相关内容时自动匹配@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 定义其能力边界:
---
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-reviewskill,因为这是一个标准流程。 - 某次 PR 需要多人协作审查 → 指派一个独立的 code-reviewer agent,它有独立的判断空间。
agents 的实战场景:
| Agent | 何时触发 | 为什么需要独立身份 |
|---|---|---|
code-reviewer | 主 Agent 指派审查任务 | 避免"既当运动员又当裁判" |
security-auditor | 涉及认证、权限、数据操作时 | 需要深入追问,隔离上下文不干扰主任务 |
performance-profiler | 性能问题排查时 | 生成大量分析数据,不应进入主会话 |
database-expert | Schema 变更、数据迁移时 | 需要专门的数据库上下文知识 |
agents/ 代表着 Claude Code 向"多智能体协作"方向的演进:主 Agent 不再是全能选手,而是演变为一个任务协调者,将专业工作交给专业的 agent 去执行。
8. settings.json:权限与项目配置
settings.json 定义了 Claude Code 在项目中的行为边界——哪些操作可以直接执行,哪些需要确认,哪些完全禁止。这是一种预防机制,在危险操作发生之前就将其拦截。
8.1 配置结构
{
"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:团队统一的权限策略,提交到 Gitsettings.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 "授人以渔"的设计初衷。
延伸阅读:
- 官方文档:Claude Code 官方文档