本文档说明 .claude/ 目录下各个文件夹和配置文件的用途，帮助您更好地理解和管理 Claude Code。

📁 目录结构总览

C:/Users/100984/.claude/ │ ├── 📄 CLAUDE.md              # 🔴 全局指令（最重要） ├── 📄 settings.json          # 🔴 全局设置（最重要） ├── 📄 settings.local.json    # 项目级设置（可选） │ ├── 📁 agents/                # 🤖 Agent 定义 ├── 📁 skills/                # 📚 Skill 定义 ├── 📁 plugins/               # 🔌 插件 │ ├── 📁 projects/              # 📂 项目会话记录 ├── 📁 sessions/              # 💬 会话数据 ├── 📁 plans/                 # 📋 计划文件 ├── 📁 tasks/                 # ✅ 任务记录 │ ├── 📁 cache/                 # 🗄️ 缓存数据 ├── 📁 backups/               # 💾 备份文件 ├── 📁 file-history/          # 📜 文件历史 ├── 📁 shell-snapshots/       # 🖥️ Shell 快照 ├── 📁 paste-cache/           # 📋 剪贴板缓存 ├── 📁 session-env/           # 🌐 会话环境 ├── 📁 ide/                   # 💻 IDE 集成 ├── 📁 telemetry/             # 📊 遥测数据 ├── 📁 debug/                 # 🐛 调试日志 │ └── 📄 history.jsonl          # 📜 命令历史

🔴 核心配置文件

1. CLAUDE.md - 全局指令

用途：定义在所有项目中都生效的全局指令和规则。

位置：C:/Users/100984/.claude/CLAUDE.md

示例内容：

# 项目安全操作规则  ## Git 操作限制 ### 允许的操作（只读） - `git status` - 查看状态 - `git diff` - 对比变更 ...  ## 文件操作规则 ### 修改文件前 默认必须先询问用户确认。 ...

生效范围：所有项目、所有会话

优先级：最高（会覆盖默认行为）

2. settings.json - 全局设置

用途：Claude Code 的全局配置，包括权限、模型、工具等。

位置：C:/Users/100984/.claude/settings.json

示例内容：

{   "model": "claude-sonnet-4-20250514",   "permissions": {     "allow": [       "Bash(ls:*)",       "Bash(git status:*)",       "Read(*)"     ],     "deny": [       "Bash(rm -rf:*)"     ]   },   "env": {     "MY_API_KEY": "xxx"   } }

常用配置项：

3. settings.local.json - 项目级设置

用途：针对特定项目的设置，会覆盖全局设置。

位置：项目根目录下的 .claude/settings.local.json

优先级：settings.local.json > settings.json > 默认值

🤖 agents/ - Agent 定义

用途：存放自定义 Agent（智能体）定义文件。

结构：

agents/ ├── architect.md       # 软件架构师 ├── code-reviewer.md   # 代码审查员 └── java-reviewer.md   # Java 审查员

Agent 文件格式

--- name: my-agent                    # Agent 名称 description: 描述信息...           # 描述（用于自动触发） tools: ["Read", "Grep", "Glob"]   # 可用工具 model: sonnet                     # 使用的模型 ---  # Agent 指令  你是一个专业的 XXX，负责...

Agent 与 Skill 的区别

如何创建新 Agent

1. 在 agents/ 下创建 .md 文件

2. 添加 YAML frontmatter

3. 编写 Agent 指令

📚 skills/ - Skill 定义

用途：存放可复用的技能/流程定义。

结构：

skills/ ├── .agents/skills/     # 安装的 Agent Skills（来自 modelscope） │   ├── code-auditing/ │   └── java-reviewer/ │ ├── .clawhub/           # 包管理器缓存 ├── skills-lock.json    # 安装记录 │ ├── zentao-test-task/   # 用户创建的 Skill ├── theme-kit/          # 用户创建的 Skill └── ...

Skill 文件格式

方式一：单个 Markdown 文件

skills/ └── my-skill.md

方式二：文件夹形式（推荐）

skills/ └── my-skill/     ├── SKILL.md        # Skill 主文件     ├── helper.js       # 辅助脚本     └── resources/      # 资源文件

SKILL.md 格式

# Skill 名称  简短描述...  ## 触发条件  当用户提到 "xxx" 时触发。  ## 使用方式  ...  ## 操作流程  ### 第一步：xxx ...  ### 第二步：xxx ...

如何创建新 Skill

1. 在 skills/ 下创建文件夹

2. 创建 SKILL.md 主文件

3. 添加辅助文件（可选）

🔌 plugins/ - 插件

用途：存放 Claude Code 插件。

结构：

plugins/ └── my-plugin/     ├── plugin.json    # 插件配置     └── ...

📂 项目与会话相关

projects/ - 项目记录

用途：存储各个项目的会话信息。

projects/ ├── project-a/ │   ├── sessions/ │   └── config.json └── project-b/     └── ...

sessions/ - 会话数据

用途：存储当前会话的临时数据。

plans/ - 计划文件

用途：存储进入计划模式时生成的计划文档。

格式：plan-{timestamp}.md

tasks/ - 任务记录

用途：存储后台任务的状态和输出。

🗄️ 缓存与历史

cache/ - 缓存

用途：API 响应缓存、提示词缓存等。

说明：可定期清理，不影响功能。

backups/ - 备份

用途：文件修改前的自动备份。

命名格式：原路径/文件名_时间戳.扩展名

file-history/ - 文件历史

用途：记录文件修改历史。

shell-snapshots/ - Shell 快照

用途：保存 Shell 状态快照。

history.jsonl - 命令历史

用途：记录所有执行的命令。

📊 其他目录

ide/ - IDE 集成

用途：与 IDE（如 VS Code）集成相关数据。

telemetry/ - 遥测

用途：匿名使用统计（可禁用）。

debug/ - 调试

用途：调试日志，排查问题时使用。

paste-cache/ - 剪贴板缓存

用途：粘贴内容缓存。

session-env/ - 会话环境

用途：会话级环境变量。

⚙️ 常用配置示例

1. 添加权限白名单

在 settings.json 中：

{   "permissions": {     "allow": [       "Bash(npm:*)",       "Bash(pnpm:*)",       "Bash(yarn:*)",       "Bash(git status:*)",       "Bash(git diff:*)"     ]   } }

2. 配置钩子（Hooks）

在 settings.json 中：

{   "hooks": {     "PreToolUse": [       {         "matcher": "Bash",         "hooks": ["echo '即将执行 Bash 命令'"]       }     ],     "PostToolUse": [       {         "matcher": "Write",         "hooks": ["echo '文件已写入'"]       }     ]   } }

3. 设置环境变量

在 settings.json 中：

{   "env": {     "OPENAI_API_KEY": "sk-xxx",     "DATABASE_URL": "postgresql://..."   } }

4. 配置模型

在 settings.json 中：

{   "model": "claude-sonnet-4-20250514" }

可选模型：

• claude-sonnet-4-20250514 - Sonnet（推荐）

• claude-opus-4-20250514 - Opus（更强）

• claude-haiku-3-5-20241022 - Haiku（快速）

🧹 清理建议

以下目录可定期清理以释放空间：

不要删除：

• CLAUDE.md

• settings.json

• agents/

• skills/（除非确定不需要）

📝 最佳实践

1. 全局指令 (CLAUDE.md)

• ✅ 放置通用规则（如 Git 限制、安全规则）

• ✅ 定义公司/团队规范

• ❌ 不要放项目特定配置

2. 设置 (settings.json)

• ✅ 配置权限白名单减少确认

• ✅ 设置常用环境变量

• ❌ 不要放敏感信息（用环境变量）

3. Agent

• ✅ 为重复性任务创建专用 Agent

• ✅ 限制工具权限提高安全性

• ✅ 选择合适的模型（审查用 sonnet，复杂任务用 opus）

4. Skill

• ✅ 为流程性任务创建 Skill

• ✅ 使用文件夹形式组织复杂 Skill

• ✅ 添加详细的使用说明

🔗 相关链接

• Claude Code 官方文档

• Agent SDK 文档

• Claude API 文档

最后更新：2026-05-14