# .claude/ 文件夹的结构
**作者**: Akshay
**日期**: 2026-03-21T13:04:34.000Z
**来源**: [https://x.com/akshay_pachaar/status/2035341800739877091](https://x.com/akshay_pachaar/status/2035341800739877091)
---
CLAUDE.md、自定义命令、技能、代理和权限的完整指南，以及如何正确设置它们。
大多数 Claude Code 用户都把 .claude 文件夹当作一个黑盒子。他们知道它的存在，也见过它出现在项目根目录下，但他们从未打开过它，更别提了解里面每个文件的作用了。
那真是错失良机。
.claude 文件夹是 Claude 在项目中运行的控制中心。 它存储着您的指令、自定义命令、权限规则，甚至包括 Claude 在不同会话中的记忆。一旦您了解了每个文件的位置及其用途，就可以配置 Claude Code，使其完全按照团队的需求运行。
本指南将带您了解文件夹的整个结构，从您每天使用的文件到您设置一次即可不再使用的文件。
两个文件夹，不是一个。
在深入了解之前，有一件事值得事先了解：实际上有两个 .claude 目录，而不是一个。
第一个文件位于您的项目目录中，第二个文件位于您的主目录中：
项目级文件夹存放团队配置。 您需要将其提交到 Git。团队中的每个人都会获得相同的规则、相同的自定义命令和相同的权限策略。
全局 ~/.claude/ 文件夹保存您的个人偏好和机器本地状态，例如会话历史记录和自动内存。
CLAUDE.md：克劳德的使用说明书
这是整个系统中最重要的文件。启动 Claude Code 会话时，它首先读取的就是 CLAUDE.md 文件。它会将该文件直接加载到系统提示符中，并在整个会话过程中保持加载状态。
简单来说： 你在 CLAUDE.md 中写什么，Claude 都会照做。
如果你告诉 Claude 永远在实现之前编写测试，它就会照做。如果你说“永远不要用 console.log 处理错误，一定要用自定义的日志模块”，它每次都会遵守你的指示。
一个 CLAUDE.md 文件是最常见的设置。但你也可以在 ~/.claude/CLAUDE.md，用于设置适用于所有项目的全局偏好，甚至可以在子目录中创建一个文件，用于设置特定文件夹的规则。Claude 会读取所有这些文件并将它们合并。
CLAUDE.md 文件中究竟应该包含哪些内容？
大多数人要么写得太多，要么写得太少。以下是行之有效的方法。
## 写：
- 构建、测试和代码检查命令（npm run test、make build 等）
- 关键架构决策（“我们使用带有 Turborepo 的 monopo”）
- 不易察觉的陷阱（“TypeScript 严格模式已开启，未使用的变量会报错”）
- 导入约定、命名模式、错误处理风格
- 主要模块的文件和文件夹结构
## 不要写：
- 任何属于代码检查器或格式化器配置的内容
- 您可以提供完整文档的链接。
- 用大段文字解释理论
CLAUDE.md 文件长度应控制在 200 行以内。文件过长会丢失过多上下文信息，而且 Claude 对指令的执行率实际上会下降。
以下是一个简单但有效的例子：
大约 20 行代码。这足以让 Claude 高效地处理这个代码库，无需不断进行解释。
CLAUDE.local.md 用于个人自定义设置
有时你可能有一些个人偏好，而不是整个团队的偏好。例如，你可能更喜欢使用不同的测试运行器，或者你希望 Claude 始终按照特定的模式打开文件。
在项目根目录下创建 CLAUDE.local.md 文件。Claude 会将其与主 CLAUDE.md 文件一起读取，并且它会自动被 .gitignore 忽略，因此您的个人修改永远不会出现在代码仓库中。
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/ 目录下运行时才会加载。没有路径字段的规则会无条件加载，每次会话都会加载。
当你的 CLAUDE.md 文件开始显得拥挤时，这就是正确的模式。
commands/ 文件夹：您的自定义斜杠命令
Claude Code 默认内置了一些斜杠命令，例如 /help 和 /compact。commands/ 文件夹添加自己的命令。
放入 .claude/commands/ 目录的每个 markdown 文件都会变成一个斜杠命令。
review.md 的文件会创建 /project:review 项目 。名为 fix-issue.md 的文件会创建 /project:fix-issue 项目
这里有一个简单的例子。创建 .claude/commands/review.md：
现在在 Claude Code 中运行 `/project:review`，它会在 Claude 读取之前自动将真实的 Git 差异注入到提示符中。`!` 反引号语法会运行 shell 命令并将输出嵌入其中。这使得这些命令真正有用，而不仅仅是保存的文本。
## 向命令传递参数
使用参数在命令名称后添加文本：
运行 /project:fix-issue 234 会将 issue 234 的内容直接输出到提示符中。
## 个人指令与项目指令
项目命令位于 `.claude/commands/` 目录，这些命令会被提交并与团队共享。如果您希望所有项目都使用相同的命令，请将其放在 `~/.claude/commands/` 目录下。这些命令将显示为 `/user:command-name` 的形式。
一个实用的个人命令：每日站会助手、按照你的约定生成提交信息的命令，或者快速安全扫描。
技能/文件夹：按需可重用的工作流程
现在你已经了解了命令的工作原理。技能表面上看起来很相似，但触发机制却截然不同。在我们继续深入探讨之前，先来了解一下它们的区别：
技能是 Claude 可以自动调用的工作流程 ，无需您输入斜杠命令，只要任务与技能描述相符即可。命令会等待您输入，而技能则会监控对话并在合适的时机采取行动。
每个技能都位于其自身的子目录中，并包含一个 SKILL.md 文件：
SKILL.md 使用 YAML frontmatter 来描述何时使用该功能：
当你说“检查此 PR 是否存在安全问题”时，Claude 会读取描述，识别出匹配项，并自动调用该技能。你也可以使用 /security-review。
与命令的主要区别在于：技能可以捆绑支持文件。@详细指南上面的 .md 引用会加载一个详细的文档，该文档与 SKILL.md 位于同一目录下。命令是单独的文件，技能是软件包。
个人技能位于 ~/.claude/skills/，可在所有项目中使用。
代理人/文件夹：专门的子代理人角色
当任务复杂到需要专职人员协助时，您可以在 .claude/agents/ 目录中定义子代理角色。每个代理都是一个 Markdown 文件，拥有自己的系统提示符、工具访问权限和模型偏好：
以下是 code-reviewer.md 的示例：
当 Claude 需要进行代码审查时，它会在独立的上下文窗口中启动这个代理。代理执行代码审查工作，压缩审查结果，然后返回报告。这样，你的主会话就不会被成千上万个中间探索的令牌所淹没。
工具字段限制了代理可以执行的操作。安全审计员只需要读取、Grep 和 Glob 功能，它无需写入文件。这种限制是有意为之，值得明确说明。
模型字段允许您使用更经济、更快速的模型来处理特定任务。Haiku 可以很好地处理大多数只读探索。Sonnet 和 Opus 则留给真正需要它们的工作。
~/.claude/agents/ 目录下
settings.json：权限和项目配置
位于 .claude/ 目录下的 settings.json 文件控制着 Claude 的权限。您可以在此文件中定义 Claude 可以运行哪些工具、可以读取哪些文件，以及在执行某些命令之前是否需要询问。
完整文件如下所示：
## 以下是各部分的功能。
这 $schema 这行代码可以在 VS Code 或 Cursor 中启用自动完成和内联验证。务必包含它。
允许列表包含无需 Claude 确认即可运行的命令。对于大多数项目而言，一个好的允许列表应涵盖以下内容：
- 使用 Bash(npm run *) 或 Bash(make *) 命令，这样 Claude 就可以自由运行你的脚本了。
- 使用 Bash(git *) 执行只读 git 命令
- 文件操作的读取、写入、编辑、Glob、Grep 命令
禁止列表包含无论如何都会被完全阻止的命令。一个合理的禁止列表会阻止：
- 类似 rm -rf 这样的破坏性 shell 命令
- 直接网络命令，例如 curl
- 敏感文件，例如 .env 文件以及 secrets/ 目录下的任何内容。
如果某项内容不在两个列表中，克劳德会在继续操作前询问。 这种折衷方案是有意为之。它既能提供安全保障，又无需预先预判所有可能的指令。
## settings.local.json 用于自定义设置
CLAUDE.local.md 的思路相同 。创建 .claude/settings.local.json 文件
全局 ~/.claude/ 文件夹
虽然你不经常会用到这个文件夹，但了解它里面有什么内容还是很有用的。
~/.claude/CLAUDE.md 文件会在每次 Claude Code 会话中加载，适用于所有项目。这里可以存放你的个人编码原则、偏好风格，或者任何你想让 Claude 记住的内容，无论你当前在哪个代码库中。
~/.claude/projects/ 目录存储每个项目的会话记录和自动记忆信息。Claude Code 会在运行过程中自动保存笔记：它发现的命令、观察到的模式以及架构见解。这些笔记会在会话之间保留。您可以使用 /memory 命令浏览和编辑它们。
~/.claude/commands/ 和 ~/.claude/skills/ 包含所有项目中可用的个人命令和技能。
通常情况下，你不需要手动管理这些设置。但是，了解它们的存在会很有帮助，比如当 Claude 似乎“记住”了你从未告诉过它的事情，或者当你想要清除项目的自动记忆并重新开始时。
## 完整画面
以下是所有环节如何衔接起来的：
一个实用的入门方案
如果你是从零开始，这里有一个行之有效的进阶方法。
步骤 1. 在 Claude Code 中运行 /init 命令。它会读取你的项目并生成一个初始的 CLAUDE.md 文件。将其精简到只保留必要内容。
步骤 2. 添加 .claude/settings.json 文件，并根据您的技术栈配置相应的允许/拒绝规则。至少应允许运行命令，并拒绝读取 .env 文件。
步骤 3. 为最常用的工作流程创建一到两个命令。代码审查和问题修复是很好的切入点。
第四步： 随着项目的增长和 CLAUDE.md 文件内容的增多，开始将指令拆分到 .claude/rules/ 文件中。在适当的情况下，按路径限定其作用范围。
步骤 5. 添加一个 ~/.claude/CLAUDE.md 文件，其中包含您的个人偏好。例如，“始终在实现之前编写类型”或“优先选择函数式模式而不是基于类的模式”。
对于95%的项目来说，这确实就足够了。只有当涉及到值得打包的、重复性的复杂工作流程时，才需要用到技能和代理。
## 关键见解
.claude 文件夹实际上是一个协议，用于告诉 Claude 你是谁、你的项目是做什么的，以及它应该遵循哪些规则。你定义得越清晰，就越少花时间去纠正 Claude，而它就能把更多的时间用于执行有用的工作。
CLAUDE.md 是你最重要的文件。 务必先确保它正确无误。其他一切都是优化。
从小处着手，逐步完善，并将其视为项目中的任何其他基础设施：一旦正确设置，它每天都会带来收益。
拍摄结束！
如果你喜欢这篇文章。
找到我 →@akshay_pachaar ✔️
我每天都会分享关于人工智能、机器学习和 Vibe 编程最佳实践的教程和见解。
## 相关链接
- [Akshay](https://x.com/akshay_pachaar)
- [@akshay_pachaar](https://x.com/akshay_pachaar)
- [854K](https://x.com/akshay_pachaar/status/2035341800739877091/analytics)
- [@详细指南](https://x.com/@DETAILED_GUIDE)
- [$schema](https://x.com/search?q=%24schema&src=cashtag_click)
- [@akshay_pachaar](https://x.com/@akshay_pachaar)
- [升级至高级版](https://x.com/i/premium_sign_up)
- [9:04 PM · Mar 21, 2026](https://x.com/akshay_pachaar/status/2035341800739877091)
- [853.5K Views](https://x.com/akshay_pachaar/status/2035341800739877091/analytics)
- [View quotes](https://x.com/akshay_pachaar/status/2035341800739877091/quotes)
---
*导出时间: 2026/3/22 23:09:26*