本文档说明.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-20250514permissions.allow允许的操作[Bash(npm:*)]permissions.deny禁止的操作[Bash(rm:*)]env环境变量{API_KEY: xxx}theme主题darkhooks钩子见下方说明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 的区别特性AgentSkill执行方式独立子进程当前会话加载工具权限可限制继承当前会话模型可指定使用当前模型上下文独立共享适用场景审查、探索流程指导如何创建新 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}.mdtasks/ - 任务记录用途存储后台任务的状态和输出。️ 缓存与历史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复杂任务用 opus4. Skill✅ 为流程性任务创建 Skill✅ 使用文件夹形式组织复杂 Skill✅ 添加详细的使用说明 相关链接Claude Code 官方文档Agent SDK 文档Claude API 文档最后更新2026-05-14