Claude Code 的 .claude/ 文件夹全指南

Claude Code 用户通常把 .claude/ 文件夹当成一个黑盒：只要能用，就很少有人去理解里面到底发生了什么。

但 .claude/ 其实是 Claude Code 的控制中心。它决定 Claude 读取哪些指令、可以使用哪些工具、必须遵守哪些限制，以及如何在你的项目里工作。真正理解它之后，你会得到一套可迁移、可复用、可版本控制的 AI 开发环境。

本文从文件夹结构开始，逐一解释 CLAUDE.md、rules、hooks、skills、agents、settings.json，以及用户目录中的全局配置，并给出一套可以直接落地的起步方案。

两个文件夹，而不是一个

Claude Code 实际上使用两个 .claude/ 文件夹：

项目级 .claude/：位于项目根目录，存放团队共享的配置，通常应提交到 Git。

用户级 ~/.claude/：位于 home 目录，存放个人配置、跨项目的 Skills、自定义命令、会话记录和自动记忆。

第一个属于项目，第二个属于你。两者会合并生效；当同名配置发生冲突时，更具体的项目级配置通常优先。

项目级文件夹承载团队配置，用户级文件夹承载个人偏好：

项目级文件夹负责让团队成员拥有一致的工作方式；用户级文件夹则让你在不同项目之间复用自己的工作流，而不必把个人偏好提交到每个仓库。

CLAUDE.md：Claude 的项目说明书

CLAUDE.md 是 Claude 在开始工作时读取的指令文件。它不是一份写给人看的项目介绍，而是一份告诉 Claude “在这个代码库里应该如何工作”的操作手册。

CLAUDE.md 适合写什么

适合放进去的内容包括：

安装、测试、构建和部署命令。

团队约定，例如命名方式、错误处理和代码风格。

Claude 经常需要遵守的架构边界。

常见陷阱、不能修改的文件，以及验证结果的要求。

完成任务前必须执行的检查。

不适合放进去的内容包括：

只对当前一次任务有用的临时上下文。

已经可以从代码中直接推断出的冗长说明。

会频繁变化、但没有维护机制的细节。

密钥、令牌、个人路径等敏感信息。

与项目无关的泛化建议。

一个好的 CLAUDE.md 应该短而明确。它的目标是减少 Claude 的猜测，而不是把整个项目重新写一遍。

一个最小示例

如果项目有多个层级，也可以在子目录继续放置 CLAUDE.md。Claude 会根据当前工作目录和文件位置读取相关指令，因此可以把全局规则放在根目录，把更具体的规则放到对应模块中。

CLAUDE.local.md：个人覆盖配置

CLAUDE.local.md 用来保存不应该提交到仓库的个人配置。它适合放：

你本地的开发环境说明。

个人习惯的命令或工具。

只对你有效的调试流程。

不适合和团队共享的实验性规则。

可以把 CLAUDE.local.md 加入 .gitignore，这样团队共享的 CLAUDE.md 保持稳定，同时每个人仍然可以保留自己的工作方式。

rules/ 文件夹：让指令可以模块化扩展

当 CLAUDE.md 越来越长时，把所有内容塞进一个文件会变得难以维护。 .claude/rules/ 可以把规则拆分成多个主题，并根据文件路径自动应用。

一个常见结构如下：

规则文件可以通过 YAML frontmatter 指定适用路径：

这样，API 规则只会在相关文件上工作，前端规则也不会污染后端任务。模块化的规则比一份超长的全局说明更容易复查、更新和复用。

hooks：对 Claude 的行为进行确定性控制

Skills 和 CLAUDE.md 主要依赖 Claude 理解并遵守指令，而 hooks 提供了更确定性的控制方式。它们可以在工具调用前后、任务停止时或特定事件发生时执行脚本。

Hooks 适合用来做：

阻止危险的 shell 命令。

在写入文件前执行格式检查。

在测试完成后发送通知。

记录工具调用。

在 Claude 停止前确认关键检查是否完成。

所有 hook 配置通常都写在 settings.json 中。一个简单的例子：

退出码很重要

对于阻止操作的 hook，退出码 2 通常表示拒绝这次操作。脚本可以检查命令内容，如果命令匹配危险模式，就输出原因并返回 2。

例如，项目可以拦截：

rm -rf 等破坏性命令。

强制推送到主分支。

未经确认的数据库迁移。

直接修改生产环境的命令。

Hooks 的优点是“确定性”：它们不依赖 Claude 是否正确理解了一段自然语言。但也要注意，过度使用 hooks 会让工作流变得难以调试。每个 hook 都应该有清晰的作用、明确的错误信息和独立的测试方式。

Stop hooks 与通知

Stop hook 可以在 Claude 准备结束任务时运行检查。例如：

确认测试已经执行。

检查工作区是否存在未处理的错误。

在长任务完成后发送桌面通知。

记录一次任务的摘要。

通知类 hook 不应阻塞任务；验证类 hook 则应该在失败时明确告诉 Claude 还缺少什么。

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

Skills 是可以按需调用的可复用工作流。它们适合承载比 CLAUDE.md 更长、更专业、更有步骤性的能力。

一个项目级 Skills 目录可以是：

每个 Skill 的核心是 SKILL.md。它通常包含名称、描述、触发条件和执行流程：

Skills 与自定义命令的区别在于：命令更像一个直接可执行的入口，而 Skill 更像一套完整的专业工作流。一个 Skill 可以包含参考资料、脚本、模板和多步判断逻辑。

适合做成 Skill 的内容包括：

安全审查。

发布流程。

数据迁移。

代码评审。

生成测试计划。

按团队规范撰写技术文档。

个人 Skills 可以放在 ~/.claude/skills/ 中，这样它们就能跨项目使用，而不需要复制进每个仓库。

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

Agents 用来定义专门负责某类工作的子代理。相比临时告诉 Claude “请你像代码审查员一样工作”，Agent 可以把角色、工具、模型和输出要求固定下来。

目录结构示例：

一个代码审查 Agent 可以这样定义：

Agent 的价值在于专业化。它可以限制工具范围，避免审查代理意外修改文件；也可以指定更适合当前任务的模型。个人 Agent 同样可以放在 ~/.claude/agents/ 中跨项目复用。

settings.json：权限与项目配置

settings.json 是项目级配置的核心入口。它可以控制权限、hooks、环境变量以及其他项目行为。

权限配置通常包含允许列表和拒绝列表：

允许列表让常规操作不必反复确认，拒绝列表则可以保护高风险边界。权限规则应该尽量具体，避免用过于宽泛的通配符。

如果个人机器需要额外权限，可以使用 settings.local.json。它适合保存不应提交到 Git 的本地设置，与 CLAUDE.local.md 的思路类似。

全局 ~/.claude/ 文件夹

用户级 ~/.claude/ 负责跨项目的长期配置，常见内容包括：

~/.claude/CLAUDE.md：所有项目都适用的个人规则。

~/.claude/commands/：个人自定义命令。

~/.claude/skills/：跨项目 Skills。

~/.claude/agents/：跨项目 Agents。

~/.claude/projects/：项目级会话记录、自动记忆和相关状态。

全局配置应该保持克制。适合放进去的是稳定、跨项目的工作习惯；具体项目的架构规则、命令和安全边界应该留在项目目录中。

完整结构

把这些部分放在一起，一个项目可能类似这样：

这里的关键不是文件越多越好，而是每种信息放在正确的位置：团队规则放项目里，个人偏好放用户目录，专业工作流放 Skills，角色边界放 Agents，确定性约束放 hooks，权限控制放 settings.json。

一套实用的起步方案

如果你刚开始搭建，可以按下面五步来：

第一步：先写一份短 CLAUDE.md

记录项目命令、目录结构、核心约定，以及 Claude 完成任务前必须运行的检查。先保持短小，等真实任务暴露问题后再补充。

第二步：把经常变化的规则拆出来

当主文件开始变长时，把 API、前端、测试和数据库规则移到 .claude/rules/，并用 paths 限定适用范围。

第三步：把重复工作做成 Skill

只要你第二次遇到同样的多步流程，就考虑将它整理成 Skill。把背景、步骤、检查清单和输出格式放在 SKILL.md 中。

第四步：为高风险工作设置 Agent 和 hooks

用 Agent 限定专业角色和工具范围，用 hooks 拦截危险操作。两者结合后，Claude 既能获得专业上下文，也不能轻易越过安全边界。

第五步：把权限配置得具体

允许常规测试和读取操作，拒绝破坏性命令。不要为了省确认而使用过于宽泛的权限；短期的便利往往会换来更大的风险。

核心认识

.claude/ 不是一堆零散配置，而是一套分层的 Agent 工作系统：

CLAUDE.md 负责长期上下文。

rules/ 负责按路径加载的模块化规则。

hooks 负责确定性控制。

skills/ 负责可复用工作流。

agents/ 负责专业化角色。

settings.json 负责权限和项目级行为。

~/.claude/ 负责跨项目的个人配置与记忆。

理解这套分层结构之后，Claude Code 就不再只是一个“会写代码的聊天工具”，而更像一个可以被配置、约束、扩展和复用的开发环境。最好的配置不是最复杂的配置，而是让正确的上下文在正确的时间出现，并让危险的行为在执行前被明确拦截。