← BACK
Claude CodeVibe Coding工程化

Claude Code 项目治理指南：.claude 目录的完整结构与最佳实践

2026-05-28

在前两节中，系统讲解了 CLAUDE.md、memory.md、settings.json 和 rules/*.md 这四个核心记忆文件。

本节将从更高维度，完整梳理 .claude 目录 的整体结构与最佳实践，帮助你建立系统化的 Claude 项目治理能力。

.claude 目录的两层配置体系

Claude Code 采用两层配置目录设计，兼顾团队协作与个人定制：

  1. 项目级：你的项目/.claude/（推荐提交到 Git，团队共享）
  2. 全局级：~/.claude/（个人配置，全项目生效，不提交 Git）

推荐的项目级目录结构（生产级推荐）

你的项目/
├── CLAUDE.md                    # 项目总纲（必须）
├── CLAUDE.local.md              # 个人私有补充（强烈建议 gitignore）
│
└── .claude/
    ├── settings.json            # 项目共享设置
    ├── settings.local.json      # 个人设置覆盖（gitignore）
    ├── .claudeignore            # 忽略文件列表
    │
    ├── rules/                   # 模块化规则集（最核心）
    │   ├── code-style.md
    │   ├── api-design.md
    │   ├── testing.md
    │   ├── security.md
    │   └── frontend/
    │       └── component.md
    │
    ├── skills/                  # 可复用工作流
    │   ├── code-review/
    │   │   └── SKILL.md
    │   ├── deploy/
    │   │   └── SKILL.md
    │   └── fix-bug/
    │       └── SKILL.md
    │
    ├── agents/                  # 专精子代理
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    │
    ├── commands/                # 自定义斜杠命令
    │   └── triage.md
    │
    ├── docs/                    # 项目知识文档
    │   ├── architecture.md
    │   └── decisions.md
    │
    └── worktrees/               # 会话工作树隔离（可选）

各文件/文件夹详细说明

文件/文件夹 主要作用 是否提交 Git 优先级 推荐说明
CLAUDE.md 项目总纲、技术栈、架构原则、大方向 是 ★★★★★ 控制在 200 行以内，作为规则入口
CLAUDE.local.md 个人偏好、临时笔记、敏感信息 否 ★★★★ 存放个人习惯和隐私内容
settings.json 权限控制、模型选择、Token 限制、Hooks 是 ★★★★★ 团队统一安全与工具策略
settings.local.json 个人对 settings 的覆盖 否 ★★★ 本地调试使用
.claudeignore 忽略特定文件/目录，减少上下文污染 是 ★★★★ 类似 .gitignore
rules/ 按领域解耦的专业规则 是 ★★★★★ 核心，按需加载
skills/ 可复用的多步工作流（SKILL.md） 是 ★★★★ 标准化重复任务
agents/ 专精子代理定义（多代理协作） 是 ★★★ 大型复杂项目使用
commands/ 自定义斜杠命令 (/command) 是 ★★★ 提升操作效率
docs/ 架构文档、决策记录、知识沉淀 是 ★★★ 项目长期记忆补充
worktrees/ 不同任务的工作树隔离 否 ★★ 高级用户可选

最佳实践总结

1. 配置分层原则（由高到低）

  • 全局 (~/.claude/) → 项目 (.claude/) → 本地 (.local.)
  • 优先使用项目级配置，便于团队成员保持一致

2. 保持精简与解耦

  • CLAUDE.md 只保留核心原则和规则索引
  • 具体细节全部拆到 rules/ 目录
  • 规则文件名必须语义清晰（api-client.md 而非 rule-1.md）

3. 路径作用域规则（强烈推荐）

在规则文件顶部添加路径匹配，实现精准加载：

# Path: src/api/**, src/services/**
# Priority: high

此规则仅在处理 API 相关文件时自动加载

4. Git 管理策略

  • 提交：CLAUDE.md、settings.json、rules/、skills/、agents/、docs/ 等团队共享内容
  • 忽略：.local.、CLAUDE.local.md

5. 进阶用法

  • 通过 skills/ 实现标准化工作流（如代码审查、部署流程）
  • 使用 agents/ 构建多代理协作体系
  • 在 settings.json 中配置 hooks 实现自动检查
  • 善用 .claudeignore 排除 node_modules、dist 等目录，降低 Token 消耗

通过合理构建 .claude 目录，你可以让 Claude 在大型项目中保持高度一致性、低 Token 消耗和强专业性，真正实现从“辅助工具”到“资深团队成员”的转变。