如何组织.claude/文件夹

微信 ezpoda免费咨询：AI编程 | AI模型微调| AI私有化部署
AI工具导航 | ONNX模型库 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

大多数Claude Code用户都知道 .claude/ 文件夹存在，但很少有人仔细思考它应该如何组织。

起初，这似乎不是问题。一个小项目可以用基本的 CLAUDE.md、一些设置和一两个额外的文件就能应付。但随着项目增长，这种随意的设置开始显现其局限性。指令变得更难维护，工作流程分散在错误的地方，文件夹慢慢变成了有用配置和难以解释的杂乱的混合体。

这就是结构重要的原因。

一个组织良好的 .claude/ 文件夹让Claude更容易指导、更容易信任，也更容易在真实项目中扩展。它有助于将广泛的指令与详细的规则分开，将可重用工作流程与自动化操作分开，将团队范围的标准与个人偏好分开。与其将 .claude/ 当作随机配置的垃圾场，不如开始将其视为项目操作层的一部分。

在本指南中，我们将探讨如何构建 .claude/ 文件夹以实现最高效率，每个部分应该包含什么，以及如何在您的工作流程变得更加高级时保持设置清洁。

1. 为什么.claude/的结构很重要？

大多数人是无意中发现 .claude/ 文件夹的！

他们看到它出现在项目中，认识到它与Claude Code相关，除非需要更改某个特定设置，否则不予理会。随着时间的推移，该文件夹变成了指令、脚本、规则和实验的混合体，背后没有清晰的结构。

这通常在开始时有效。但一旦项目增长，它就停止有效。

一个组织不善的 .claude/ 文件夹会产生与组织不善的代码库相同的摩擦。指令变得更难维护。重要规则被埋没。自动化脚本在没有命名约定的情况下堆积。团队成员不再确定在哪里添加新指导或哪些文件仍处于活动状态。与其让Claude更容易工作，文件夹开始增加噪音。

一个结构良好的 .claude/ 文件夹则相反。它为您的Claude Code设置的每个部分提供了一个明确的位置。您的主要指令易于找到。可重用规则与一次性偏好分开。钩子和工作流文件位于可预测的位置。技能和代理（当您真正需要它们时）被组织为深思熟虑的工具，而不是分散的实验。

这种结构很重要，因为Claude Code在您的设置易于理解时效果最佳——不仅对Claude，而且对您和您的团队也是如此。如果文件夹干净，您可以自信地更新它。如果它很乱，即使是小的改进也开始感到风险。

目标不是创建尽可能大的 .claude/ 文件夹。目标是创建一个易于导航、易于维护、易于随工作流程变得更加复杂而扩展的文件夹。在实践中，最高效率来自清晰：每个文件都应该有目的，每个文件夹都应该解决特定问题，整体结构应该一目了然。

这就是正确组织 .claude/ 的真正价值。您不仅仅是在存储配置文件。您正在构建塑造Claude在项目中如何工作的操作层。

在深入了解每个组件之前，先看看高效的 .claude/ 文件夹的整体结构会有所帮助。将其视为随着项目变得更加复杂我们想要建立的目标布局。

your-project/
├── CLAUDE.md              # 主要项目指令
├── CLAUDE.local.md        # 个人覆盖（不提交）
└── .claude/
    ├── settings.json      # 控制层
    ├── rules/             # 模块化指令
    ├── hooks/             # 自动化脚本
    ├── commands/          # 可重用提示工作流
    ├── skills/            # 打包能力
    └── agents/            # 专业子代理

2. 从核心开始：顶层应该放什么

一旦您看过了子文件夹，设置中最重要的部分仍然是顶层。这是Claude应该找到在最高级别定义项目的文件的地方，而无需挖掘嵌套目录。

在大多数情况下，这意味着两件事首先重要：您的主要指令文件和您的主要配置文件。

在项目根目录，CLAUDE.md 应该作为Claude如何理解代码库的入口点。这是您放置Claude在几乎每个会话中都需要的基本上下文的地方：技术栈、主要架构决策、重要约定以及定义正常开发工作流的命令。如果您团队中的某人想了解Claude应该在这个仓库中如何表现，这应该是他们首先检查的文件。

在 .claude/ 文件夹内，settings.json 文件应该处于顶层，原因相同。它不仅仅是另一个支持文件。它控制Claude Code的操作端：权限、钩子和项目级行为，这些需要易于查找和更新。将其埋在文件夹结构深处会使日常维护变得毫无必要地困难。

那个顶层应该故意保持轻量。许多人犯的错误是将 .claude/ 的根目录当作他们创建的每个脚本、工作流和实验笔记的存储区。这通常很快导致混乱。相反，顶层应该只包含全局定义项目的文件。任何更具体的内容都应该移入专用文件夹。

一个简单的思考方式是：

• CLAUDE.md： 解释项目如何工作
• settings.json： 控制Claude在项目中的操作方式
• 子文件夹：存在以保持其他一切井井有条

这种分离很有用，因为这些文件有不同的用途。CLAUDE.md 是关于指导的。settings.json 是关于控制的。一个告诉Claude代码库中什么重要。另一个塑造Claude被允许做什么以及其工作周围应该发生什么自动行为。

顶层还应该清楚区分共享文件和个人覆盖。共享的 CLAUDE.md 属于根目录，因为整个团队都从中受益。

个人覆盖（如 CLAUDE.local.md）则不同。它存在于本地偏好，应该远离团队的共享结构。同样的逻辑适用于 .claude/ 内的 settings.local.json。

换句话说，顶层应该首先回答最大的问题。Claude需要了解这个项目的什么？Claude在这里被允许做什么？其他一切都可以组织在这个基础之下。

这就是使结构高效的原因。最重要的文件保持明显，而更专业的部分被推到文件夹中，在那里它们更容易管理而不会拥挤核心设置。

3. 保持指令精简：CLAUDE.md vs rules/

使 .claude/ 文件夹效率低下的最简单方法之一是将太多内容放入 CLAUDE.md。

在开始时，该文件通常运作良好，因为项目仍然很小。您添加一些命令、一些编码约定，也许还有关于架构的简短说明。但一旦代码库增长，CLAUDE.md 往往会变成团队希望Claude记住的所有内容的万能文档。那就是它开始失去清晰度的时候。

更好的结构是将 CLAUDE.md 视为 项目的操作指南，而不是其整个知识库。

CLAUDE.md 应该保存Claude在大多数会话中需要的指令：

• 项目是什么
• 它如何组织
• 哪些命令最重要
• 哪些约定广泛适用
• Claude不应错过哪些约束

rules/ 文件夹是更具体指导所属的地方。这包括与代码库的某个部分、某个工作流或某个工程关注点（如测试或安全）相关的指令。

一个简单的思考方式是：

• CLAUDE.md 保存 全局指导
• rules/ 保存 专业指导

这种分离使结构更易于维护和扩展。

4. 为行动组织：hooks/、commands/ 等

一旦您的 .claude/ 文件夹有了清晰的指令层，下一步就是组织将指导转化为行动的文件。

这是许多设置开始变得混乱的地方。团队为格式化添加一个shell脚本，为拉取请求审查添加一个提示文件，也许还有另一个用于检查测试的脚本，不久之后，这些文件就分散在 .claude/ 的根目录中，名称只有创建它们的人才明白。

更好的方法是将 指令文件 与 行动文件 分开。

指令文件解释Claude应该如何表现。行动文件支持Claude实际反复做的事情。这就是为什么像 hooks/ 和 commands/ 这样的文件夹应该在结构中拥有自己的位置。

4.1 hooks/ 的作用

hooks/ 文件夹是您放置脚本的地方，这些脚本在Claude工作流的特定点自动运行。

这些文件不是一般文档。它们是操作脚本。它们的工作通常是三件事之一：

• 防止风险操作
• 清理或验证Claude的输出
• 强制执行工作流要求

4.2 commands/ 的作用

commands/ 文件夹用于可重用的提示工作流。

这些不像钩子那样自动。相反，它们打包您或您的团队反复运行的任务，例如：

• 审查拉取请求
• 编写缺失的测试
• 总结变更以用于发布说明
• 调试报告的问题
• 起草迁移步骤

commands/ 的价值在于它减少了重复提示。与其每次都重写相同的指令，不如将工作流一次存储在清晰的地方。

5. 构建专业能力的结构：skills/ 和 agents/

随着您的Claude Code设置变得更加复杂，您可能会发现自己一遍又一遍地创建类似的工作流。也许您总是要求Claude以相同的步骤审查后端代码，或者以相同的格式编写API端点。当这种情况发生时，将这些模式打包为可重用技能是有意义的。

skills/ 文件夹是您放置这些打包能力的地方。

技能不仅仅是另一个命令文件。它是一起工作的指令、规则和提示的组合，使Claude能够处理明确定义的任务。一个好的技能应该易于调用，易于更新，并且足够清晰，以便团队中的任何人都可以使用它而不需要猜测。

agents/ 文件夹在更专业的层面上工作。当技能不足以解决问题，而您需要子代理以不同的角色或不同的权限运行以处理特定任务时，这是您放置这些定义的地方。

6. 将团队结构与个人结构分开

高效 .claude/ 文件夹中较微妙的挑战之一是处理共享配置和个人偏好之间的紧张关系。

团队需要一致性。个人需要灵活性。如果一切都在同一个地方混合，您最终会得到两种情况的缺点：团队标准被个人覆盖削弱，个人偏好被意外提交并与他人造成冲突。

解决方法是在结构中将两者分开。

共享文件存在于 .claude/ 内部。个人覆盖存在于其外部。

对于顶层，这意味着：

• CLAUDE.md 是共享的（提交到版本控制）
• CLAUDE.local.md 是个人的（被忽略）

对于 .claude/ 内部，模式相同：

• settings.json 是共享的
• settings.local.json 是个人的

7. 高效.claude/文件夹的实用蓝图

如果您已阅读至此，您已看到每个部分如何运作。现在让我们将所有内容整合到一个您可以实际使用的实用蓝图中。

这是完整结构：

your-project/
├── CLAUDE.md                    # 共享：主要项目指令
├── CLAUDE.local.md             # 个人：本地覆盖（被忽略）
└── .claude/
    ├── settings.json           # 共享：控制层
    ├── settings.local.json     # 个人：本地覆盖（被忽略）
    ├── rules/                  # 模块化指令
    │   ├── frontend.md
    │   ├── backend-api.md
    │   └── testing.md
    ├── hooks/                  # 自动化脚本
    │   ├── format-edits.sh
    │   └── run-tests.sh
    ├── commands/               # 可重用工作流
    │   ├── review-pr.md
    │   └── write-tests.md
    ├── skills/                 # 打包能力
    │   └── fastapi-endpoint/
    └── agents/                 # 专业子代理
        └── security-reviewer/

8. 应避免的常见结构错误

即使有良好的意图，某些模式几乎总是导致问题。以下是您在组织 .claude/ 文件夹时应该避免的最常见错误：

错误1：将所有内容转储到根目录

将脚本和配置文件直接放在 .claude/ 根目录中而没有适当的文件夹组织。

错误2：将所有内容放入CLAUDE.md

允许 CLAUDE.md 增长到数百行，使其难以维护和解析。

错误3：模糊hooks/和commands/的区别

Hooks是自动的。Commands是手动的。混合它们会造成混乱。

错误4：忘记个人覆盖

不创建 CLAUDE.local.md 或 settings.local.json 意味着个人偏好污染团队配置。

错误5：过早创建skills/

在需要之前创建 skills/ 文件夹。如果只有一个使用该模式的命令，它还不是技能。

9、结束语

一个组织良好的 .claude/ 文件夹不仅仅是一种组织好奇心。它是帮助您扩展项目而不失去对Claude控制的基础设施。

关键原则很简单：

• 顶层保持轻量： 仅全局文件位于根目录
• 分离指令： 全局指导在 CLAUDE.md 中，专业指导在 rules/ 中
• 组织行动： hooks/ 用于自动行为，commands/ 用于可重用工作流
• 打包能力： skills/ 用于成熟模式，agents/ 用于专业子代理
• 分离关注点： 团队配置和个人覆盖不应混合

当您应用这些原则时，您的 .claude/ 文件夹从一个随机配置文件的集合转变为一个干净的操作层，帮助您指导、信任并随项目增长而扩展Claude。

结构不仅仅是整洁。它是清晰度。而这种清晰度使Claude Code在真实项目中随时间变得更加强大。

原文链接: How to Structure .Claude/ Folder for Maximum Efficiency

汇智网翻译整理，转载请标明出处