Claude Code 文件层级机制详解

消灭八哥

703人浏览 · 2026-03-24 10:15:42

消灭八哥 · 2026-03-24 10:15:42 发布

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)	最低