深度解读：如何构建高效的 .Claude/ 目录结构

深度解读：如何构建高效的 .Claude/ 目录结构

📖 原文来源：How to Structure .Claude/ Folder for Maximum Efficiency
✍️ 作者：youssef-hosni | 📅 发布日期：2026-04-10 | 👏 热度：560+ 点赞 · 3,219+ 阅读

---

一、为什么 .Claude/ 目录结构如此重要？

大多数开发者对 .claude/ 目录的态度是”用完即弃”——发现它存在，随便放点配置，然后就再也不管了。

问题在于：随着项目增长，这种”随意”会带来严重的维护噩梦：

混乱状态 ❌	有序状态 ✅
指令分散、难以定位	每个文件职责清晰
规则被埋没	重要规则一目了然
自动化脚本堆积	脚本命名规范、易于查找
团队成员不知从何下手	新成员快速上手
文件变成”配置垃圾堆”	成为项目的”操作层”

核心观点：.claude/ 不是用来存储随机配置的垃圾桶，而是塑造 Claude 在项目中行为的操作层（Operating Layer）。

---

二、推荐的完整目录结构

your-project/
├── CLAUDE.md                  # 主项目指令（团队共享）
├── CLAUDE.local.md            # 个人覆盖配置（不提交到 Git）
└── .claude/
    ├── settings.json          # 控制层配置
    ├── rules/                 # 模块化指令
    │   ├── frontend.md
    │   ├── backend-api.md
    │   ├── testing.md
    │   └── data-pipelines.md
    ├── hooks/                 # 自动化脚本
    ├── commands/              # 可复用的提示词工作流
    ├── skills/                # 打包的能力集
    └── agents/                # 专业子代理

---

三、核心组件详解

3.1 顶层文件：CLAUDE.md vs settings.json

文件	定位	职责	提交到 Git？
CLAUDE.md	项目操作指南	解释项目如何工作	✅ 是
CLAUDE.local.md	个人覆盖	本地偏好设置	❌ 否
.claude/settings.json	控制层	控制 Claude 能做什么	✅ 是
.claude/settings.local.json	本地控制	本地权限调整	❌ 否

CLAUDE.md 示例结构：

# 项目：Customer Insights API

## 技术栈
- FastAPI + PostgreSQL + SQLAlchemy + Pytest

## 目录结构
- `app/api/` - 路由定义
- `app/services/` - 业务逻辑
- `app/models/` - ORM 模型
- `app/schemas/` - 请求/响应模式

## 常用命令
- `pytest` - 运行测试
- `alembic upgrade head` - 应用数据库迁移
- `ruff check .` - 代码检查
- `ruff format .` - 代码格式化

## 开发规范
- 所有请求体必须用 Pydantic 验证
- 路由处理器保持精简，业务逻辑放入 services
- API 响应中不暴露内部异常细节

3.2 rules/ 模块化指令目录

为什么需要拆分？

当项目包含多个技术栈时（如 Next.js 前端 + FastAPI 后端 + 数据管道），把所有规则塞进一个 CLAUDE.md 会导致：

• 文件臃肿、难以维护
• 不同领域的规则混杂
• Claude 获得的上下文变多，但质量反而下降

拆分方案示例：

.claude/
└── rules/
    ├── frontend.md        # UI 规范
    ├── backend-api.md     # API 行为和验证规则
    ├── testing.md         # 测试编写和运行规范
    └── data-pipelines.md  # 批处理和定时任务规范

3.3 hooks/ 自动化脚本

Hooks 用于在 Claude 工作中自动触发特定操作：

Hook 类型	触发时机	典型用途
pre-tool-use	工具调用前	权限检查、安全过滤
post-tool-use	工具调用后	自动格式化、日志记录
pre-command-exec	命令执行前	环境检查、依赖验证
post-command-exec	命令执行后	结果验证、通知发送

3.4 commands/ 可复用提示词工作流

将常用的复杂提示词模板化，避免重复输入：

# .claude/commands/refactor-code.md
# 重构代码的标准流程
# 使用方法：/refactor-code <file_path>

1. 分析当前代码结构和依赖
2. 识别需要重构的部分
3. 确保有充分的测试覆盖
4. 进行小步重构，每步验证
5. 更新相关文档

3.5 skills/ 技能包

Skills 是打包好的能力集，可以包含：

• 专用指令集
• 相关的工具配置
• 示例和模板

.claude/skills/
├── code-review/        # 代码审查技能
├── api-design/         # API 设计技能
└── data-analysis/      # 数据分析技能

3.6 agents/ 专业子代理

当项目足够复杂时，可以定义专门的子代理来处理特定领域：

{
  "agents": {
    "backend": {
      "description": "后端开发专家",
      "instructions": "专注 API 设计、数据库建模、性能优化"
    },
    "frontend": {
      "description": "前端开发专家", 
      "instructions": "专注用户体验、响应式设计、性能调优"
    }
  }
}

---

四、团队协作 vs 个人使用

团队场景

共享（提交到 Git）	个人（不提交）
CLAUDE.md	CLAUDE.local.md
.claude/rules/	.claude/settings.local.json
.claude/settings.json
.claude/commands/

个人优化建议

1. 本地覆盖优先：用 .local.md 覆盖团队规则
2. 实验性脚本：先在本地 hooks/ 测试，成熟后再共享
3. 渐进式完善：从小规模开始，根据需要逐步添加

---

五、常见错误及避坑指南

❌ 常见错误	✅ 正确做法
把所有指令塞进一个 CLAUDE.md	按领域拆分到 rules/
在顶层堆放所有脚本	按类型放入 hooks/、commands/
忽略本地文件 (.local)	用 .local 隔离个人偏好
不区分团队 vs 个人文件	明确哪些需要提交 Git
把 .claude/ 当垃圾堆	把它当作项目的操作层
过度工程化	从简单开始，按需扩展

---

六、实战建议

小项目（起步阶段）

project/
├── CLAUDE.md          # 简单的项目说明
└── .claude/
    └── settings.json  # 基本配置

中型项目（多模块）

project/
├── CLAUDE.md
└── .claude/
    ├── settings.json
    └── rules/
        ├── frontend.md
        └── backend.md

大型项目（团队协作）

project/
├── CLAUDE.md
├── CLAUDE.local.md    # 个人覆盖
└── .claude/
    ├── settings.json
    ├── rules/
    ├── hooks/
    ├── commands/
    ├── skills/
    └── agents/

---

七、核心要点总结

💡 效率最大化 = 清晰的结构 + 明确的职责 + 按需扩展

1. CLAUDE.md = 项目操作指南（告诉 Claude 项目是什么）
2. settings.json = 控制层配置（告诉 Claude 能做什么）
3. rules/ = 模块化指令（按领域拆分规则）
4. hooks/ = 自动化脚本（事件驱动的自动化）
5. commands/ = 可复用工作流（避免重复输入）
6. skills/ = 打包能力集（可移植的专业技能）
7. agents/ = 专业子代理（复杂项目的分工协作）

---

八、延伸阅读

• Building Agent Skills for Claude Code - 作者举办的实战工作坊
• Claude Code 官方文档
• CLAUDE.md 写作指南