Claude Code 项目结构与配置
Claude Code 是一款强大的 AI 命令行开发工具。为了更好地利用其自动化编码和项目理解能力，了解其推荐的项目结构和配置文件的作用至关重要。
1. 项目结构概览
以下是 Claude Code 推荐的项目组织方式，它能够帮助 AI 更好地理解您的代码库、编码规范和工作流。
2. 文件与目录详细说明
| 文件 / 目录 | 类型 | 作用说明 | 提交 Git |
|---|---|---|---|
CLAUDE.md | 文件 | 项目全局配置。包含项目介绍、技术栈、常用命令、编码约定及架构说明等。AI 启动时会优先加载。 | ✅ 是 |
CLAUDE.local.md | 文件 | 本地覆盖配置。用于存放个人偏好、本地环境差异等设置，其优先级高于 CLAUDE.md。 | ❌ 否 |
.mcp.json | 文件 | MCP 集成配置。管理与外部服务（如 GitHub, JIRA, Slack, 数据库等）的连接。 | ✅ 是 |
.claude/ | 目录 | Claude Code 核心配置目录。包含设置、规则、命令、技能等。 | ✅ 是 |
settings.json | 文件 | 全局设置。控制权限、工具访问、模型选择、钩子配置等。 | ✅ 是 |
settings.local.json | 文件 | 本地设置覆盖。仅提交到本地库，用于存放开发者特定的配置。 | ❌ 否 |
rules/ | 目录 | 规则集合。按主题划分的 Markdown 文件，用于定义编码风格、测试、API 设计等规则。 | ✅ 是 |
commands/ | 目录 | 自定义命令。定义常用的斜杠命令（如 /review），用于执行可复用的工作流程。 | ✅ 是 |
skills/ | 目录 | 技能集合。根据任务上下文自动触发的函数或能力，提高 AI 的执行效率。 | ✅ 是 |
agents/ | 目录 | 代理集合。定义具有特定角色和工具的子代理（Sub-agents）。 | ✅ 是 |
hooks/ | 目录 | 钩子脚本。在特定事件前后自动执行的脚本（如校验、格式化等）。 | ✅ 是 |
3. 核心文件详解
CLAUDE.md
这是最重要的文件。一个好的 CLAUDE.md 应该包含：
- 项目摘要：一两句话描述项目目标。
- 技术栈：列出核心框架和库。
- 常用命令：构建、测试、部署等命令，方便 AI 快速调用。
- 编码约定：命名规范、目录结构、测试要求等。
.claude/rules/
你可以根据需要创建多个规则文件，例如：
code-style.md: 定义缩进、注释、命名风格。testing.md: 定义测试框架使用规范。api-conventions.md: 定义 RESTful 规范或错误码处理方式。
IMPORTANT
最佳实践：除了以 .local 结尾的文件外，其余配置建议全部提交到版本库，以保持团队协作的一致性。