上千万浏览，大神教你深度玩转Claude Code

一篇《深度剖析 .claude/ 文件夹》的文章火了，上千万浏览。

这是 Daily Dose of Data Science（每日一点数据科学）创始人的一篇 Claude Code 深度使用指南，是一份如何彻底掌控 AI 编程助手（Claude Code）的非常优质的干货文章。

我们来看看大神是怎么正确地使用 Claude code 的。

这是一份关于 CLAUDE.md、自定义命令、技能（skills）、智能体（agents）、权限及其正确配置方式的完整指南。

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

这其实错失了极大的便利。

.claude 文件夹是 Claude 在你项目中行为表现的“控制中心”。它保存着你的指令、自定义命令、权限规则，甚至还包括 Claude 跨会话的记忆。

一旦你弄清楚了什么文件放在哪里以及为什么这么放，你就能对 Claude Code 进行精准配置，让它完全按照你们团队的需求来工作。

本指南将带你从头到尾剖析这个文件夹，从你每天都要用的文件，到那些“设置一次就不用再管”的文件，统统讲明白。

是两个文件夹，而不是一个

在深入讲解之前，有一点需要先了解：实际上有两个 .claude 目录，而不是一个。

第一个存在于你的项目中，第二个存在于你的电脑用户主目录 (home directory) 下：

项目级文件夹保存团队配置。你会把它提交到 Git 代码库里。这样团队里的每个人都会遵守相同的规则、使用相同的自定义命令和相同的权限策略；全局 ~/.claude/ 文件夹保存你的个人偏好和本机状态，比如会话历史记录和自动记忆功能。

CLAUDE.md：Claude 的使用说明书

这是整个系统中最重要的一份文件。当你启动一个 Claude Code 会话时，它读取的第一样东西就是 CLAUDE.md。它会把这份文件直接加载到系统提示词 (system prompt) 中，并在整个对话过程中牢记于心。

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

如果你告诉 Claude “在写代码前永远先写测试”，它就会照做。如果你说“千万别用 console.log 来处理错误，永远使用自定义的 logger 模块”，它每次都会严格遵守。

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

CLAUDE.md 里到底该写些什么

大多数人要么写得太多，要么写得太少。以下是行之有效的做法。

建议写：

• 构建、测试和代码检查命令（如 npm run test, make build 等）

• 关键的架构决策（“我们使用带有 Turborepo 的 monorepo 单体仓库架构”）

• 不明显的坑和注意事项（“开启了 TypeScript 严格模式，有未使用的变量会报错”）

• 导入约定、命名规范、错误处理风格

• 核心模块的文件和文件夹结构

千万别写：

• 任何属于代码检查器 (linter) 或格式化工具 (formatter) 配置文件里的东西

• 你可以直接丢链接的完整长篇文档

• 解释理论原理的长篇大论

请将 CLAUDE.md 保持在 200 行以内。比这更长的文件会占用过多的上下文空间，而且反而会导致 Claude 对指令的遵守程度下降。

这是一个极简但极其有效的例子：

这大概只有 20 行代码。但它为 Claude 提供了在这个代码库中高效工作所需的一切信息，而不需要反复向你确认。

CLAUDE.local.md：用于个人专属覆盖设置

有时你会有一些只属于你个人的偏好，而不是整个团队的。也许你更喜欢不同的测试运行工具，或者你希望 Claude 总是按特定的模式打开文件。

你可以在项目根目录下创建 CLAUDE.local.md。Claude 会将它与主 CLAUDE.md 一起读取，而且它会自动被加入 Git 忽略列表（gitignored），这样你的个人微调就不会被提交到团队的代码库里了。

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

对于单个项目来说，CLAUDE.md 非常好用。但随着团队的壮大，你最终会得到一个 300 多行的 CLAUDE.md，结果就是没人去维护，大家也都视而不见。

rules/ (规则) 文件夹就是为了解决这个问题的。

.claude/rules/ 目录下的每一个 Markdown 文件都会自动与你的 CLAUDE.md 一起加载。你可以按关注点将指令拆分开来，而不是全塞进一个巨大的文件里：

每个文件都保持聚焦，易于更新。负责 API 约定的团队成员去编辑 api-conventions.md。负责测试标准的成员去编辑 testing.md。大家互不踩踏。

真正的威力来自于按路径限定的规则。在规则文件顶部添加一段 YAML “前言” (frontmatter) 配置，它就只会在 Claude 处理匹配的文件时才会激活：

当 Claude 在编辑一个 React 组件时，它不会加载这个文件。只有当它在 src/api/ 或 src/handlers/ 目录下工作时才会加载。没有 paths 字段的规则文件则会无条件地在每次会话中加载。

一旦你的 CLAUDE.md 开始感觉变得拥挤，这就应该使用这种模式了。

Hooks（钩子）系统：对 Claude 行为的确定性控制

CLAUDE.md 里的指令是不错的。但它们只是“建议”。Claude 大多数时候会听从，但并非总是如此。你不能指望一个语言模型永远记得运行你的代码检查工具、永远不执行危险命令，或者在它完成任务时始终如一地通知你。

Hooks（钩子）让这些行为变得具有确定性。它们是事件处理器，会在 Claude 工作流的特定节点自动触发。你的 Shell 脚本每次都会运行，绝无例外。

所有的 Hook 配置都放在 settings.json 文件中的 hooks 键值下。Claude Code 会在会话开始时快照（记录）这份配置，当事件触发时通过标准输入 (stdin) 接收 JSON 数据，并根据退出码 (exit codes) 来决定下一步怎么做。

你需要知道的最关键一点是：退出码 2 是唯一会拦截（阻止）执行的代码。 退出码 0 代表成功。退出码 1 代表报错但不会拦截。退出码 2 意味着停止一切操作，并将你的标准错误 (stderr) 发送给 Claude 让它自我纠正。

在安全类的 Hook 中错误地使用退出码 1 是最常见的问题，它只会记录一个错误然后什么都不做。

你最常用的事件有：

• PreToolUse（在任何工具运行前触发，这是你的安全闸门）

• PostToolUse（在工具成功运行后触发，用于格式化和代码检查）

• Stop（在 Claude 完成时触发，用于“测试必须通过”等质量关卡）

• UserPromptSubmit（按下回车键时触发，用于提示词验证）

• Notification（用于桌面通知）

• SessionStart/SessionEnd（用于上下文注入和清理）

对于工具类事件，可以使用 matcher 正则表达式字段来缩小触发 Hook 的工具范围。"Write|Edit|MultiEdit" 针对的是文件修改。"Bash" 针对的是 Shell 命令。省略该字段则匹配所有工具。

这是一个典型的 Hook 配置示例。它会自动格式化 Claude 碰过的每个文件，并阻止危险的 Bash 命令：

那个“bash 防火墙脚本”会从标准输入读取命令，对照危险模式（如 rm -rf /, git push --force main 和 DROP TABLE）进行检查，并以退出码 2 退出以阻止任何匹配的命令。

Stop 钩子同样强大。一个运行 npm test 并在失败时以退出码 2 退出的脚本，可以阻止 Claude 宣布“完成任务”，直到所有测试变绿为止。一个需要注意的坑：一定要在 JSON payload 中检查 stop_hook_active 标志。如果没有它，Hook 拦截了 Claude，Claude 重试，Hook 再次拦截，你就会陷入死循环。应该让 Claude 在第二次尝试时停下来。

对于桌面通知，将 Notification 钩子配置在 ~/.claude/settings.json 中，并结合 macOS 的 osascript 或 Linux 的 notify-send，就能在你的所有项目中完美工作。

几点注意事项：

Hooks 在会话中途不会热重载 (hot-reload)。PostToolUse 无法撤销任何操作，因为工具已经运行过了，所以如果你需要阻止某个动作，请使用 PreToolUse。Hooks 也会在子智能体 (subagent) 执行动作时递归触发。并且，Hooks 是以你完整的用户权限执行的，没有任何沙盒隔离，所以务必将 Shell 变量加引号、验证 JSON 输入，并在引用脚本时使用绝对路径。

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

技能 (Skills) 是一种工作流，当当前任务与技能描述相符时，Claude 可以根据上下文自行调用它们。技能会默默观察对话，并在合适的时机采取行动。

每个技能都存放在各自的子目录中，并包含一个 SKILL.md 文件：

SKILL.md 使用 YAML 前言来描述何时使用它：

当你说“审查一下这个 PR 看有没有安全问题”时，Claude 会读取描述，识别出匹配该场景，然后自动调用这个技能。你也可以使用 /security-review 显式地调用它。

它与自定义命令的关键区别在于：技能可以将支持性文件与它们打包在一起。上面提到的 @DETAILED_GUIDE.md 引用就能引入一个直接与 SKILL.md 放在同级目录的详细文档。命令是单一的文件。而技能则是完整的包。

个人的技能可以放在 ~/.claude/skills/ 下，这样在你所有的项目中都可以使用。

agents/ 文件夹：专门的子智能体角色

当一个任务复杂到需要一位专门的“专家”时，你可以在 .claude/agents/ 目录中定义一个子智能体角色 (subagent persona)。每个智能体都是一个 Markdown 文件，拥有自己的系统提示词、工具访问权限和模型偏好设定：

一个 code-reviewer.md 看起来大概是这样的：

当 Claude 需要完成代码审查时，它会在自己独立的上下文窗口中生成这个智能体。智能体完成工作，压缩总结发现的问题，然后汇报回来。你的主对话会话就不会被数以千计的中间探索 token 给弄得乱七八糟。

tools（工具）字段限制了智能体能做什么。一个安全审计员只需要 Read (读取), Grep (内容搜索), 和 Glob (路径匹配) 就够了。它绝不该有写入文件的权限。这种限制是刻意为之的，非常有必要明确设定。

model（模型）字段让你可以在处理特定任务时使用更便宜、更快的模型。Haiku 模型能很好地处理大部分只读的探索性工作。把更强大的 Sonnet 和 Opus 模型留给真正需要它们的工作吧。

个人的智能体可以放在 ~/.claude/agents/ 下，这样在你所有的项目中都可以使用。

settings.json：权限与项目配置

.claude/ 目录下的 settings.json 文件控制着 Claude 可以做和不可以做的事情。这也是你的 hooks (钩子) 存放的地方，你还要在这里定义 Claude 可以运行哪些工具、可以读取哪些文件，以及它在运行某些命令前是否需要先询问你。

完整的文件长这样：

以下是各部分的作用：

• $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 来保存你不想提交到团队代码库的权限变更。它也是自动被 Git 忽略的。

全局的 ~/.claude/ 文件夹

你不会经常和这个文件夹打交道，但了解里面的内容很有用。

• ~/.claude/CLAUDE.md 会被加载到你的所有项目中的每一个 Claude Code 会话里。这是一个放置你个人编码原则、偏好的代码风格，或者任何你希望 Claude 不论在哪个仓库里都要记住的事情的好地方。

• ~/.claude/projects/ 按项目存储会话记录和自动记忆 (auto-memory)。Claude Code 在工作时会自动给自己做笔记：它发现的命令、观察到的模式、架构层面的见解。这些记录跨会话持久存在。你可以通过输入 /memory 命令来浏览和编辑它们。

• ~/.claude/commands/ 和 ~/.claude/skills/ 保存你个人专属、跨项目通用的命令和技能。

通常你不需要手动管理这些内容。但知道它们的存在是很方便的，特别是当 Claude 似乎“记住”了一些你从来没告诉过它的事情，或者当你想清空某个项目的自动记忆一切重新开始时。

全景图 (The full picture)

这是所有东西组合在一起的样子：

一份实用的入门配置指南

如果你打算从零开始，以下是一个非常奏效的渐进流程。

第一步。在 Claude Code 里运行 /init。它会通过读取你的项目自动生成一个基础版的 CLAUDE.md。请把它精简到只剩核心内容。

第二步。添加 .claude/settings.json，并配置适合你们技术栈的 allow/deny（允许/拒绝）规则。最起码，允许你的 run 运行命令，并拒绝读取 .env。

第三步。为你最常做的工作流创建一两个自定义命令。代码审查和修复 bug 是很好的起点。

第四步。随着项目变大以及 CLAUDE.md 变得拥挤，开始将指令拆分到 .claude/rules/ 文件中。在合理的情况下按路径去限定它们的作用域。

第五步。添加一个带有你个人偏好的全局 ~/.claude/CLAUDE.md。比如可以是“永远在实现代码前先写好类型定义”，或者“比起基于类的模式，更偏好函数式编程模式”。

对于 95% 的项目来说，这就完全足够了。只有当你有反复出现的、值得被打包的复杂工作流时，技能 (skills) 和智能体 (agents) 才会派上用场。

核心总结

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

CLAUDE.md 是你杠杆率最高的文件。先把它写对。其他的都只是优化。

从小处着手，边做边完善，像对待项目里的任何其他基础设施一样对待它：一旦配置得当，它每天都会给你带来巨大的回报。

就是这些了！

参考资料：

https://x.com/akshay_pachaar/status/2035341800739877091

END

点击图片立即报名👇️