Claude Code 项目目录结构

简介

.claude 目录是 Claude Code 的配置根目录，分为 项目级 .claude 和 用户全局级 ~/.claude 两套独立目录。项目级配置可提交Git，用于团队共享项目规则；全局配置属于个人本地配置，作用于所有项目，不提交到代码仓库。

加载优先级：项目配置 > 全局配置。会话启动时，会同时加载全局指令 + 项目指令合并生效。
大部分普通用户只需要维护 CLAUDE.md 和 settings.json 两个文件。

完整目录总览

my-runoops-project/
├── CLAUDE.md                   # 【推荐放在项目根】项目核心指令（优先读取）
├── .claude/                    # 项目级配置文件夹（claude init自动生成）
│   ├── CLAUDE.md               # 备选项目指令文件（根目录CLAUDE.md优先级更高）
│   ├── settings.json           # 项目级配置：模型、API地址、参数
│   ├── ignore                  # Claude读取忽略列表，语法同.gitignore
│   ├── hooks/                  # 钩子脚本，在Claude任务前后自动执行脚本
│   ├── skills/                 # 自定义技能
│   ├── commands/               # 自定义斜杠命令
│   ├── subagents/              # 子代理配置
│   ├── workflows/              # 工作流定义
│   └── rules/                  # 项目规则
├── .gitignore
└── src/用户全局目录（个人，所有项目生效，不提交Git）
Mac/Linux：~/.claude
Windows：%USERPROFILE%.claude
~/.claude/
├── CLAUDE.md                   # 全局个人默认指令
├── settings.json               # 全局默认模型、API配置
└── memory/                     # 自动记忆存储，本地会话数据

补充：如果项目已有 AGENTS.md，Claude Code 也可以自动读取，可替代 CLAUDE.md。

核心文件详解

1. `CLAUDE.md`（最重要）

项目指令文件，会话启动时加载进系统提示词。

优先级：项目根目录 CLAUDE.md > .claude/CLAUDE.md > 全局 ~/.claude/CLAUDE.md

用途：定义项目技术栈、代码规范、工作流程、约束要求。
示例：

# 项目信息
技术栈：Nuxt4 + TailwindCSS V4 + Shadcn/ui + TypeScript
编码规范：
1. 修改代码前，必须输出 Plan。
2. 组件使用组合式API，禁止选项式API。
3. 样式优先使用Tailwind，不新增自定义全局CSS。
约束：禁止直接修改数据库迁移与环境配置文件。

2. `.claude/ignore`

忽略文件清单，语法和 .gitignore 完全一致。用于阻止Claude读取密钥、证书、构建产物。

# 环境密钥
.env
.env.local
*.pem
*.key依赖、构建产物
node_modules
dist
.build
IDE配置
.idea
.vscode

3. `.claude/settings.json`

项目级别配置，覆盖全局配置。可配置模型、中转API地址、上下文窗口等。

{
  "model": "deepseek-coder",
  "baseUrl": "https://api.deepseek.com",
  "maxTokens": 8192
}

4. 扩展目录（进阶，普通用户可不创建）

hooks/：任务执行前后触发自定义脚本，用于代码格式化、自动运行测试。
skills/：自定义技能，扩展Claude能力。
commands/：自定义 / 斜杠命令。
subagents/：子代理，拆分复杂任务。
workflows/：预定义完整工作流，例如上线前检查流程。
rules/：细粒度规则，限制文件读写、命令执行权限。

全局目录 `~/.claude`

作用范围：本机所有项目，属于个人本地配置，不要提交Git。
存储内容：个人默认指令、全局API配置、自动记忆 memory。
自定义路径：可设置环境变量 CLAUDE_CONFIG_DIR 修改全局目录位置。

版本控制最佳实践

✅ 推荐提交项目根 CLAUDE.md 和 .claude/ 目录到Git，严禁写入密钥、密码。
✅ 密钥使用环境变量注入，不要写在 settings.json。
✅ .claude/ignore 屏蔽隐私文件，防止Claude读取敏感内容。
✅ 全局目录 ~/.claude 保留在本地，不纳入版本管理。

加载顺序与优先级

读取全局 ~/.claude 配置
读取项目 .claude/ 目录配置
读取项目根目录 CLAUDE.md（最高优先级，覆盖前面指令）
合并全部配置，启动会话

⚠️ 修改 CLAUDE.md、settings.json 后，仅新会话生效，已经打开的对话不会自动重载。

常见问题

根目录 CLAUDE.md 和 .claude/CLAUDE.md 同时存在，读取哪个？
优先读取项目根目录 CLAUDE.md。
.claude/ignore 不生效？
文件名必须是 ignore，不带 .txt 后缀；修改后新建会话。
全局配置和项目配置冲突？
项目配置优先级高于全局，同名配置会覆盖全局。
不需要子代理、自定义命令，必须创建 hooks/skills 文件夹吗？
不需要。claude init 默认只生成基础文件，进阶目录按需手动新建。

安全提示

密钥、私钥、数据库凭证不要写进任何 CLAUDE.md、settings.json。
敏感文件添加到 .claude/ignore，避免Claude读取。
使用 rules 目录可以限制Claude读写范围与终端命令权限，适合高风险项目。

简介

完整目录总览

核心文件详解

1. CLAUDE.md（最重要）

2. .claude/ignore

3. .claude/settings.json