本文档说明 .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.md -
settings.json -
agents/ -
skills/（除非确定不需要）
📝 最佳实践
1. 全局指令 (CLAUDE.md)
-
✅ 放置通用规则（如 Git 限制、安全规则）
-
✅ 定义公司/团队规范
-
❌ 不要放项目特定配置
2. 设置 (settings.json)
-
✅ 配置权限白名单减少确认
-
✅ 设置常用环境变量
-
❌ 不要放敏感信息（用环境变量）
3. Agent
-
✅ 为重复性任务创建专用 Agent
-
✅ 限制工具权限提高安全性
-
✅ 选择合适的模型（审查用 sonnet，复杂任务用 opus）
4. Skill
-
✅ 为流程性任务创建 Skill
-
✅ 使用文件夹形式组织复杂 Skill
-
✅ 添加详细的使用说明
🔗 相关链接
最后更新：2026-05-14