Claude Code 文件层级机制详解
一、整体架构图
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code 配置层级 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Managed (全局托管) - 最高优先级，不可覆盖 │ │
│ │ macOS: /Library/Application Support/ClaudeCode/ │ │
│ │ Linux: /etc/claude-code/ │ │
│ │ Windows: C:\Program Files\ClaudeCode\ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↑ │
│ │ 优先级 │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Local (本地) - .claude/settings.local.json │ │
│ │ 仅当前用户、当前项目可见，gitignored │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↑ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Project (项目级) - .claude/settings.json │ │
│ │ 项目内所有协作者共享，可提交到git │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↑ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ User (用户级) - ~/.claude/settings.json │ │
│ │ 当前用户所有项目生效 │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘二、CLAUDE.md 文件
2.1 作用
CLAUDE.md 是 Claude Code 的核心指令文件，为项目提供持久化的上下文指导。
2.2 文件位置与作用域
| 作用域 | 位置 | 用途 |
|---|---|---|
| Managed | 系统级目录 | IT/DevOps 组织的统一规范 |
| Project | ./CLAUDE.md 或 ./.claude/CLAUDE.md |
团队共享的项目指令 |
| User | ~/.claude/CLAUDE.md |
个人偏好设置 |
2.3 加载规则
- 向上遍历：从当前工作目录向上检查每个目录
- 在
foo/bar/运行时，会加载foo/bar/CLAUDE.md和foo/CLAUDE.md - 子目录的 CLAUDE.md 按需加载
2.4 最佳实践
- 每个文件控制在 200 行以内
- 使用 headers 和 bullets 组织内容
- 指令要具体可验证
- 可用
@path/to/file导入额外文件
三、.claude 目录结构
项目根目录/
├── CLAUDE.md # 项目指令 (根目录位置)
├── .claude/
│ ├── CLAUDE.md # 项目指令 (备选位置)
│ ├── settings.json # 项目级配置 (可共享)
│ ├── settings.local.json # 本地配置 (gitignored)
│ ├── rules/ # 模块化规则目录
│ │ ├── code-style.md
│ │ ├── testing.md
│ │ └── security.md
│ ├── hooks/ # Hook 脚本目录
│ │ └── *.sh / *.py
│ ├── agents/ # 子代理定义
│ └── plugins/ # 插件目录四、settings.json 配置项
4.1 作用域对比
| 作用域 | 位置 | 影响范围 | 可提交到git |
|---|---|---|---|
| Managed | 系统级 | 机器所有用户 | 否 |
| User | ~/.claude/settings.json |
当前用户所有项目 | 否 |
| Project | .claude/settings.json |
项目所有协作者 | ✅ |
| Local | .claude/settings.local.json |
仅本地 | ❌ (gitignored) |
4.2 主要配置项
json
{
"env": { "FOO": "bar" }, // 环境变量
"permissions": { "allow": [...], "deny": [...] }, // 权限规则
"hooks": { ... }, // Hook 配置
"model": "claude-sonnet-4-6", // 默认模型
"effortLevel": "medium", // 努力级别
"autoMemoryEnabled": true, // 自动记忆开关
"autoMemoryDirectory": "~/memory", // 记忆目录
"claudeMdExcludes": ["**/monorepo/**"], // 排除的CLAUDE.md
"sandbox": { ... }, // 沙箱配置
"enabledPlugins": { ... }, // 启用的插件
"allowedMcpServers": [...], // 允许的MCP服务器
"outputStyle": "Explanatory" // 输出风格
}4.3 权限配置示例
json
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm test *)"
],
"deny": [
"Read(./.env)",
"Read(./secrets/**)"
]
}
}五、Hooks 机制
5.1 什么是 Hooks
Hooks 是在 Claude Code 生命周期特定点自动执行的脚本。
5.2 Hook 类型
| 类型 | 说明 |
|---|---|
command |
执行 shell 命令 |
http |
POST 事件到 URL |
prompt |
单轮 LLM 评估 |
agent |
多轮验证子代理 |
5.3 事件类型
| 事件 | 触发时机 |
|---|---|
SessionStart |
会话开始或恢复 |
UserPromptSubmit |
提交 prompt 时 |
PreToolUse |
工具执行前 (可阻止) |
PostToolUse |
工具成功后 |
PostToolUseFailure |
工具失败后 |
PermissionRequest |
权限对话框出现时 |
Notification |
发送通知时 |
Stop |
Claude 停止响应时 |
InstructionsLoaded |
CLAUDE.md 加载时 |
SessionEnd |
会话终止时 |
5.4 配置示例
json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/format.sh",
"timeout": 600
}
]
}
]
}
}六、Memory 目录
6.1 位置
~/.claude/projects/<项目名>/memory/6.2 结构
memory/
├── MEMORY.md # 索引文件，每次会话加载前200行
├── debugging.md # 调试笔记 (按需读取)
├── patterns.md # 模式记录
└── ...6.3 工作原理
MEMORY.md前 200 行每次会话开始时加载- 超过 200 行不加载
- 主题文件按需读取
- 使用
/memory命令管理
6.4 配置
json
{
"autoMemoryEnabled": false // 禁用自动记忆
}或设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
七、rules/ 目录 (模块化规则)
7.1 用途
将大型 CLAUDE.md 拆分为多个主题文件。
7.2 结构
.claude/
├── CLAUDE.md
└── rules/
├── code-style.md # 代码风格
├── testing.md # 测试规范
└── security.md # 安全要求7.3 限定范围
支持 YAML frontmatter 限定文件范围：
markdown
---
paths:
- "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 必须包含输入验证八、优先级总结
| 层级 | 位置 | 优先级 |
|---|---|---|
| 1 | Managed (系统级) | 最高，不可覆盖 |
| 2 | 命令行参数 | |
| 3 | Local (.claude/settings.local.json) | |
| 4 | Project (.claude/settings.json) | |
| 5 | User (~/.claude/settings.json) | 最低 |
九、Q&A
Q: CLAUDE.md 放在根目录还是 .claude/ 区别？
A: 两者效果一样，根目录是约定俗成的位置。
Q: settings.json 和 CLAUDE.md 的区别？
A:
settings.json: 配置工具行为（权限、hooks、环境变量等）CLAUDE.md: 提供项目指令和上下文
Q: 哪些文件应该提交到 git？
A: 项目级配置可提交：
.claude/settings.json.claude/CLAUDE.md.claude/rules/下的文件
Q: 哪些文件应该 gitignore？
A: 本地个人配置：
.claude/settings.local.json