Claude Code .claude 目录结构详解：CLAUDE.md、settings.json、skills、agents 全文件指南 #

Claude Code 的 .claude 目录和 ~/.claude 分别存储项目级和用户级的配置，包括指令、权限、子代理、技能和自动记忆。项目级文件可提交 Git 与团队共享，全局文件仅个人使用。最常用的文件是 CLAUDE.md 和 settings.json；按需添加 rules、skills、agents 等。运行 /context 或 /memory 可查看当前会话加载了哪些文件。

Claude Code 从项目目录（项目根目录下的 .claude/ 和根目录文件）以及用户主目录下的 ~/.claude/ 读取指令、设置、技能、子代理和记忆。项目级文件提交到 Git 即与团队共享；全局级文件仅应用于你自己的所有项目。

在 Windows 上，~/.claude 解析为 %USERPROFILE%\.claude。如果设置了 CLAUDE_CONFIG_DIR，所有 ~/.claude 路径都基于该目录。

大多数用户只需要编辑 CLAUDE.md 和 settings.json。其余目录按需添加：skills、rules、subagents、output-styles 等。

项目级 .claude 目录 #

项目级配置存放在仓库的 .claude/ 目录下，部分文件（CLAUDE.md、.mcp.json、.worktreeinclude）位于项目根目录。

CLAUDE.md #

加载时机：每个会话开始时完整加载到上下文。

功能：项目特定的指令和约定。在此写下你的代码规范、常用命令、架构上下文，让 Claude 在仓库中工作时遵循团队习惯。

编写技巧：

• 控制在 200 行以内。更长的文件仍会完整加载，但可能降低遵循度。
• 如果内容只对特定任务有用，移到 skill 或路径限定的 rule 中按需加载。
• 列出最常运行的命令（build、test、format），Claude 无需你每次拼写即知道。
• 在会话中运行 /memory 可直接打开并编辑 CLAUDE.md。
• 如果想要保持项目根目录整洁，可以放在 .claude/CLAUDE.md。

示例（TypeScript + React 项目）：

# Project conventions

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Stack
- TypeScript with strict mode
- React 19, functional components only

## Rules
- Named exports, never default exports
- Tests live next to source: `foo.ts` -> `foo.test.ts`
- All API routes return `{ data, error }` shape

.mcp.json #

加载时机：会话开始时连接 MCP 服务器，工具模式延迟加载。

功能：配置 Model Context Protocol (MCP) 服务器，让 Claude 访问外部工具（数据库、API、浏览器等）。团队共享的 MCP 服务器放在此文件；个人服务器放在 ~/.claude.json。

Tips：

• 使用环境变量引用敏感信息：${GITHUB_TOKEN}
• 该文件位于项目根目录，不在 .claude/ 内
• 个人服务器使用 claude mcp add --scope user 写入 ~/.claude.json

示例（GitHub MCP 服务器）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

.worktreeinclude #

加载时机：当 Claude 通过 --worktree、EnterWorktree 工具或子代理 isolation: worktree 创建 Git worktree 时读取。

功能：列出 gitignored 文件（如 .env），在新建 worktree 时自动复制进去。使用 .gitignore 语法，只有同时被 gitignore 且匹配模式的文件才会复制。

Tips：

• 文件位于项目根目录，不在 .claude/ 内
• 仅用于 Git。如果配置了其他 VCS 的 WorktreeCreate hook，此文件无效
• 桌面应用的并行会话也适用

示例：

# Local environment
.env
.env.local

# API credentials
config/secrets.json

.claude/ 目录下的文件 #

settings.json #

加载时机：覆盖全局 ~/.claude/settings.json。本地设置、CLI 标志和管理设置优先级更高。

功能：设置权限（allow/deny）、hooks、statusLine、默认模型、环境变量等。与 CLAUDE.md 不同，这些是强制执行的行为，而非建议。

常见配置项：

• permissions：允许、拒绝或提示是否使用特定工具或命令
• hooks：在工具调用前后等事件点运行自定义脚本
• statusLine：自定义底部状态行
• model：设置该项目的默认模型
• env：为每个会话设置环境变量
• outputStyle：选择自定义系统提示样式

Tips：

• Bash 权限模式支持通配符：Bash(npm test *) 匹配所有以 npm test 开头的命令
• 数组型设置（如 permissions.allow）跨作用域合并；标量设置（如 model）使用最具体的值

示例（允许 npm test 和 npm run，禁止 rm -rf，使用 Prettier 格式化）：

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

settings.local.json #

加载时机：用户可编辑的设置文件中优先级最高；CLI 标志和管理设置仍优先。

功能：个人配置覆盖，与 settings.json 格式相同但不会提交到 Git。适用于需要不同权限或默认值的情况。

Tips：

• 数组设置跨作用域合并，标量设置使用本地值
• Claude Code 首次写入时会自动加入 ~/.config/git/ignore；如果使用自定义 core.excludesFile，手动添加模式

示例（添加 Docker 权限）：

{
  "permissions": {
    "allow": [
      "Bash(docker *)"
    ]
  }
}

rules/ #

加载时机：没有 paths: 前言的规则在会话开始时加载；有 paths: 的规则在匹配文件进入上下文时加载。

功能：按主题拆分的项目指令，可以按文件路径条件加载。类似于 CLAUDE.md，但粒度更细。规则是 Claude 读取的指南，而非强制行为；如需强制行为，使用 hooks 或 permissions。

Tips：

• 使用 paths: 前言配合 glob 匹配文件范围
• 支持子目录，例如 .claude/rules/frontend/react.md 会自动发现
• 当 CLAUDE.md 接近 200 行时，开始拆分为 rules

示例（测试规则，仅在处理测试文件时加载）：

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
---

# Testing Rules

- Use descriptive test names: "should [expected] when [condition]"
- Mock external dependencies, not internal modules
- Clean up side effects in afterEach

示例（API 设计规则，仅在编辑 src/api/ 下的文件时加载）：

---
paths:
  - "src/api/**/*.ts"
---

# API Design Rules

- All endpoints must validate input with Zod schemas
- Return shape: { data: T } | { error: string }
- Rate limit all public endpoints

skills/ #

加载时机：通过 /skill-name 调用，或当 Claude 匹配任务时自动触发。

功能：每个技能是一个文件夹，包含 SKILL.md 和任意支持文件。默认情况下你与 Claude 都可调用。通过前言控制：disable-model-invocation: true 禁止 Claude 自动调用（如 /deploy），user-invocable: false 在命令菜单中隐藏。

Tips：

• 技能接受参数：/deploy staging 传递 “staging” 作为 $ARGUMENTS
• description 前言决定 Claude 何时自动调用技能
• 可以将参考文档与 SKILL.md 放在一起，Claude 知道技能目录路径并能读取支持文件

示例（安全审查技能：仅用户触发，禁止 Claude 自动调用）：

---
description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks
disable-model-invocation: true
argument-hint: <branch-or-path>
---

## Diff to review

!\`git diff $ARGUMENTS\`

Audit the changes above for:

1. Injection vulnerabilities (SQL, XSS, command)
2. Authentication and authorization gaps
3. Hardcoded secrets or credentials

Use checklist.md in this skill directory for the full review checklist.

Report findings with severity ratings and remediation steps.

配套文件 checklist.md（技能目录下的支持文件）：

# Security Review Checklist

## Input Validation
- [ ] All user input sanitized before DB queries
- [ ] File upload MIME types validated
- [ ] Path traversal prevented on file operations

## Authentication
- [ ] JWT tokens expire after 24 hours
- [ ] API keys stored in environment variables
- [ ] Passwords hashed with bcrypt or argon2

commands/ #

命令和技能现在使用同一机制。对于新工作流，请使用 skills/：支持 /name 调用，并且可以捆绑支持文件。

加载时机：用户输入 /command-name 时。

功能：单文件形式的提示语，与技能的机制相同。commands/deploy.md 创建 /deploy，与 skills/deploy/SKILL.md 效果一致。但技能使用目录结构，可捆绑参考文档；命令仅为单个 Markdown 文件。建议新工作流使用技能。

Tips：

• 在文件中使用 $ARGUMENTS 接受参数：/fix-issue 123
• 如果技能和命令同名，技能优先
• 新命令应优先写成技能；命令保持兼容

示例（修复 Github Issue 的命令）：

---
argument-hint: <issue-number>
---

!\`gh issue view $ARGUMENTS\`

Investigate and fix the issue above.

1. Trace the bug to its root cause
2. Implement the fix
3. Write or update tests
4. Summarize what you changed and why

output-styles/ #

加载时机：通过 outputStyle 设置在会话开始时应用。

功能：自定义系统提示片段，用于调整 Claude 的行为（如教学模式、代码审查模式）。通常个人样式放在 ~/.claude/output-styles/，团队共享的样式可以放在项目 output-styles/ 下。选择样式可以通过 /config 或设置文件中的 outputStyle 键。

Tips：

• 内置样式包括 Explanatory 和 Learning；自定义样式放在这里
• 在前言中设置 keep-coding- instructions: true 可保留默认任务指令
• 样式在下一个会话生效（系统提示在启动时固定以支持缓存）

agents/ #

加载时机：你或 Claude 调用子代理时，它在独立的上下文窗口中运行。

功能：每个 Markdown 文件定义一个子代理，拥有自己的系统提示、工具访问权限，以及可选的模型。子代理运行在独立的上下文窗口中，与主对话隔离，适合并行工作或隔离任务。

Tips：

• 每个子代理获得一个全新的上下文窗口
• 使用 tools: 前言限制每个代理的工具
• 输入 @ 并从自动完成中选择代理可直接委托

示例（只读代码审查子代理）：

---
name: code-reviewer
description: Reviews code for correctness, security, and maintainability
tools: Read, Grep, Glob
---

You are a senior code reviewer. Review for:

1. Correctness: logic errors, edge cases, null handling
2. Security: injection, auth bypass, data exposure
3. Maintainability: naming, complexity, duplication

Every finding must include a concrete fix.

agent-memory/ #

加载时机：子代理启动时，将 MEMORY.md 的前 200 行（最多 25KB）加载到系统提示中。

功能：子代理的持久化记忆，与主会话的自动记忆分离。仅当子代理在前言中设置 memory: project 时创建。此目录存储项目级的子代理记忆，适合团队共享。若需回避版本控制，使用 memory: local（写入 .claude/agent-memory-local/），跨项目使用 memory: user（写入 ~/.claude/agent-memory/）。

Tips：

• 子代理自动创建并更新 MEMORY.md，你无需手动编写
• 该记忆独立于主会话的自动记忆

全局级 ~/.claude 目录 #

全局级配置位于用户主目录的 ~/.claude/ 下，应用于所有项目。

.claude.json #

加载时机：会话开始时读取偏好和 MCP 服务器；当你使用 /config 或批准信任提示时写入。

功能：存储不属于 settings.json 的状态：主题、OAuth 会话、每个项目的信任决策、个人 MCP 服务器、UI 开关等。主要通过 /config 管理。

Tips：

• IDE 开关如 autoConnectIde、externalEditorContext 在此文件，不在 settings.json 中
• projects 键跟踪每个项目的状态（如信任对话框、上次会话指标）。会话中批准的权限规则写入 .claude/settings.local.json
• MCP 服务器：user 作用域跨项目，local 作用域不提交。团队服务器放在 .mcp.json

示例：

{
  "autoConnectIde": true,
  "externalEditorContext": true,
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

.claude/ 下的全局文件 #

CLAUDE.md #

加载时机：每个项目每个会话开始时，与项目级 CLAUDE.md 一起加载。

功能：你的全局指令文件。当指令冲突时，项目级指令优先。保持简短，涵盖适用于所有项目的偏好：回复风格、提交格式、个人习惯。

示例：

# Global preferences

- Keep explanations concise
- Use conventional commit format
- Show the terminal command to verify changes
- Prefer composition over inheritance

settings.json #

加载时机：默认设置，项目级和本地 settings.json 会覆盖某些键。

功能：与项目级 settings.json 相同：权限、hooks、模型、环境变量等。与此处不同的优先级：项目级 settings.json 会覆盖全局的匹配键（不是合并，而是覆盖）。这与 CLAUDE.md 不同，全局和项目级 CLAUDE.md 是同时加载而非键级合并。

示例：

{
  "permissions": {
    "allow": [
      "Bash(git log *)",
      "Bash(git diff *)"
    ]
  }
}

keybindings.json #

加载时机：会话开始时读取，编辑文件时热重载。

功能：自定义交互式 CLI 中的键盘快捷键。运行 /keybindings 创建或打开此文件。Ctrl+C、Ctrl+D、Ctrl+M、Caps Lock 保留不可变。

示例：

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

themes/ #

加载时机：会话开始时读取，文件变化时热重载。在 /theme 中列出。

功能：自定义颜色主题。每个 .json 文件定义：一个内置的 base 预设和 overrides 颜色标记映射。通过 /theme 交互创建或手写 JSON。

示例（Dracula 主题）：

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

projects/ #

加载时机：会话开始时加载 MEMORY.md；主题文件按需读取。

功能：自动记忆（Auto memory），Claude 跨会话积累知识，无需你手动编写。Claude 运行时保存笔记：构建命令、调试信息、架构笔记。每个项目使用仓库路径作为键获得独立的记忆目录。

Tips：

• 默认开启。通过 /memory 或设置中的 autoMemoryEnabled 切换
• MEMORY.md 是索引，每次会话加载前 200 行或 25KB（取小）
• 主题文件（如 debugging.md）按需读取，不在启动时加载
• 这些是纯 Markdown，可随时编辑或删除

自动生成的 MEMORY.md 示例：

# Memory Index

## Project
- [build-and-test.md](build-and-test.md): npm run build (~45s), Vitest, dev server on 3001
- [architecture.md](architecture.md): API client singleton, refresh-token auth

## Reference
- [debugging.md](debugging.md): auth token rotation and DB connection troubleshooting

自动生成的主题文件示例（debugging.md）：

---
name: Debugging patterns
description: Auth token rotation and database connection troubleshooting for this project
type: reference
---

## Auth Token Issues
- Refresh token rotation: old token invalidated immediately
- If 401 after refresh: check clock skew between client and server

## Database Connection Drops
- Connection pool: max 10 in dev, 50 in prod
- Always check \`docker compose ps\` first

rules/ #

与项目级 rules/ 相同，但应用于所有项目。用于个人代码风格、提交消息格式等跨项目约定。

skills/ #

个人技能，在所有项目中可用。与项目级 skills/ 结构相同。

commands/ #

个人命令，在所有项目中可用。与项目级 commands/ 相同。

output-styles/ #

个人输出样式，在所有项目中可用。与项目级 output-styles/ 相同。

agents/ #

个人子代理，在所有项目中可用。与项目级 agents/ 相同。

agent-memory/ #

存储 memory: user 子代理的持久化记忆，跨所有项目。

隐藏或系统级文件 #

~/.claude 还保存 Claude Code 运行产生的数据：文字稿、提示历史、文件快照、缓存和日志。见下文“应用数据”。

选择正确的文件 #

文件参考总表 #

覆盖优先级：

• 管理设置 > 一切
• CLI 标志（如 --permission-mode、--settings）覆盖 settings.json 此会话
• 某些环境变量覆盖等效设置，但情况各异：请查看环境变量参考
• 完整优先级见设置优先级

检查实际加载了什么 #

调试配置 #

如果某个设置、hook 或文件不生效，请参考调试你的配置获取检查命令和症状优先的排查表。

应用数据 #

除了你手动编写的配置，~/.claude 中还存储了 Claude Code 运行期间写入的数据。这些文件是纯文本。所有通过工具的数据都会以文字稿形式保存在磁盘上：文件内容、命令输出、粘贴的文本。

自动清理 #

以下路径下的文件会在启动时删除（如果超过 cleanupPeriodDays 设置的天数，默认 30 天）：

永久保留（需手动删除） #

纯文本存储 #

文字稿和历史记录未加密。OS 文件权限是唯一保护。如果工具读取了 .env 文件或命令输出了凭据，该值会写入 projects/<project>/<session>.jsonl。降低风险的方法：

• 降低 cleanupPeriodDays 缩短保留时间
• 设置环境变量 CLAUDE_CODE_SKIP_PROMPT_HISTORY 跳过写入文字稿和提示历史
• 在非交互模式下使用 --no-session-persistence + -p
• 在 Agent SDK 中设置 persistSession: false
• 使用权限规则禁止读取凭据文件

清除本地数据 #

运行 claude project purge 删除 Claude Code 为一个项目保存的状态：

• projects/ 下的文字稿和自动记忆
• 会话对应的 tasks/、debug/、file-history/ 条目
• history.jsonl 中匹配的提示行
• ~/.claude.json 中该项目的条目

预览而不删除：

claude project purge ~/work/my-repo --dry-run

单次确认后删除：

claude project purge ~/work/my-repo

不指定路径则从交互式列表中选择。

脚本中使用 --yes 跳过确认：

claude project purge ~/work/my-repo --yes

使用 --all 代替路径一次性清除所有项目，此时会直接删除 history.jsonl 而非过滤。使用 -i 逐项确认。

该命令不会删除 shell-snapshots/ 和 backups/（非项目相关），并在计划输出中提示。如果没有匹配到状态，退出码为 1。

你也可以手动删除上述任何应用数据路径，新会话不受影响。各路径删除后丢失的内容：

不要删除 ~/.claude.json、~/.claude/settings.json 或 ~/.claude/plugins/：它们保存身份认证、偏好和已安装插件。

常见问题 #

settings.local.json 和 settings.json 有什么区别？ #

settings.json (项目级或全局) 会提交到 Git，团队共享。settings.local.json 仅存在于项目 .claude/ 下，自动被 gitignore，用于存放你个人的权限覆盖或模型偏好，不会影响团队配置。两者的设置格式相同，settings.local.json 优先级高于项目 settings.json。

CLAUDE.md 和 rules/ 里的规则有什么区别？ #

CLAUDE.md 是每个会话开始时都会完整加载的项目指令，适合放全局约定和常用命令。rules/ 是拆分为独立文件的指令，可以通过 paths: 前言条件加载（仅当 Claude 读取匹配的文件时才将其加入上下文），适合为特定目录或文件类型定制规则。当 CLAUDE.md 接近 200 行时，建议拆分为 rules。

如何清除 Claude Code 的本地缓存和对话历史？ #

运行 claude project purge <项目路径> 可删除指定项目的对话文字稿、自动记忆、文件快照和提示历史。使用 --dry-run 预览删除计划。使用 --yes 跳过确认适合脚本。使用 --all 一次清除所有项目。自动清理周期由 cleanupPeriodDays 设置控制（默认 30 天），更早的旧文件会在下次启动时自动删除。