本文档说明.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" } }常用配置项：
| 配置项 | 说明 | 示例 |
|---|---|---|
model | 默认模型 | "claude-sonnet-4-20250514" |
permissions.allow | 允许的操作 | ["Bash(npm:*)"] |
permissions.deny | 禁止的操作 | ["Bash(rm:*)"] |
env | 环境变量 | {"API_KEY": "xxx"} |
theme | 主题 | "dark" |
hooks | 钩子 | 见下方说明 |
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 | Skill |
|---|---|---|
| 执行方式 | 独立子进程 | 当前会话加载 |
| 工具权限 | 可限制 | 继承当前会话 |
| 模型 | 可指定 | 使用当前模型 |
| 上下文 | 独立 | 共享 |
| 适用场景 | 审查、探索 | 流程指导 |
如何创建新 Agent
在
agents/下创建.md文件添加 YAML frontmatter
编写 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
在
skills/下创建文件夹创建
SKILL.md主文件添加辅助文件（可选）
🔌 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（快速）
🧹 清理建议
以下目录可定期清理以释放空间：
| 目录 | 清理频率 | 说明 |
|---|---|---|
cache/ | 每月 | 缓存数据 |
backups/ | 按需 | 旧备份 |
file-history/ | 每月 | 文件历史 |
debug/ | 按需 | 调试日志 |
history.jsonl | 按需 | 命令历史 |
不要删除：
CLAUDE.mdsettings.jsonagents/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
