Claude Code 文件层级机制详解

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 主要配置项

{
  "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 权限配置示例

{
  "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 配置示例

{
  "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 配置

{
  "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 限定文件范围：

---
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

---

参考文档

• Memory 文档
• Settings 文档
• Hooks 指南