AI 知识库

一文玩转 Claude Code

Properties2
tagsai, claude, claude-code, 工具
aliasesClaude Code 教程

60分钟阅读

摘要

更顺畅、更智能的 vibe coding 工具。

介绍

简介

名称类型用途/适用场景注意事项
核心定位产品特征简单、纯粹的智能体式编码助手适合终端驱动工作流
交互形态使用方式类似“在终端做事的同事”，可配合 MCP 操作外部能力主要交互仍在终端内完成
推荐安装安装方式官方原生安装器脚本具体命令见下方安装提示
兼容安装安装方式npm install -g @anthropic-ai/claude-code文档标注为 deprecated，建议仅作兼容方案
搜索机制能力特征采用代理式搜索（agentic search）而非索引更依赖迭代探索与上下文推理

安装提示

  • macOS/Linux：curl -fsSL https://claude.ai/install.sh | bash
  • Windows：irm https://claude.ai/install.ps1 | iex

代理式搜索

  • Claude Code 通过像人类一样探索和理解代码库来工作，使用 glob、grep 和 find 等工具，而不是通过索引或嵌入整个代码库
  • 它能进行迭代搜索：执行搜索、分析结果，然后决定是否需要进行更多搜索

目录

CLI 命令

名称类型用途/适用场景注意事项
claude启动命令启动交互式会话日常开发主入口
claude "query"启动命令启动会话并附带初始提示适合一次性任务起步
claude -p "query"非交互命令输出结果后退出适用于脚本/CI/管道
cat file | claude -p "query"管道命令处理标准输入内容注意 shell 转义与编码
claude -c会话命令继续当前目录最近对话目录上下文需一致
claude -r "<session-id>"会话命令按 ID 恢复会话或打开选择器适合跨时段接续任务
claude update / claude upgrade维护命令更新到最新版本更新后建议复核命令兼容性
claude mcp集成命令配置和管理 MCP 服务器涉及权限与外部连接配置
claude doctor诊断命令检查自动更新器健康状态新环境或升级后建议执行
claude install [target]安装命令安装原生构建版本（stable/latest/指定版本）团队环境建议固定版本
claude plugin扩展命令管理 Claude Code 插件第三方插件先做安全评估
claude setup-token认证命令设置长期认证令牌需 Claude 订阅并妥善保管令牌

CLI 标志 (Flags)

关于 --dangerously-skip-permissions

超级好用！但可能删库跑路！请谨慎使用。

交互模式

键盘快捷键

通用控制

快捷键功能
Ctrl+C取消当前输入或生成
Ctrl+D退出 Claude Code 会话
Ctrl+L清除终端屏幕（保持对话历史）
Ctrl+G在默认文本编辑器中打开提示
Ctrl+O切换详细输出（显示工具使用详情）
Ctrl+R反向搜索命令历史
Ctrl+V / Cmd+V粘贴剪贴板图像
Ctrl+B将当前任务移至后台运行
Ctrl+T切换任务列表视图
Esc+Esc撤销/倒回对话，或从选定消息汇总
Shift+Tab / Alt+M切换权限模式（自动接受/计划/代理团队/普通）
Alt+P切换模型（无需清除提示）
Alt+T切换扩展思考模式

文本编辑

快捷键功能
Ctrl+K删除到行尾
Ctrl+U删除整行
Ctrl+Y粘贴已删除的文本
Alt+B / Alt+F光标后退/前进一个单词

多行输入

方法快捷键兼容性
快速转义\ + Enter所有终端
macOS 默认Option+EntermacOS
Shift+EnterShift+EnteriTerm2、WezTerm、Ghostty、Kitty 原生支持
控制序列Ctrl+J行饲料字符
粘贴模式直接粘贴多行所有终端

Shift+Enter 配置

VS Code、Alacritty、Zed、Warp 等终端需要运行 /terminal-setup 来启用 Shift+Enter。

快捷前缀

前缀说明
/触发斜杠命令 / Skills
!Bash 模式：直接运行 shell 命令，输出添加到对话上下文
@文件路径自动补全，快速包含文件内容

Vim 模式

通过 /vim 命令启用，支持完整的 Normal/Insert 模式切换、hjkl 导航、文本对象操作（diw、ci"等）以及 . 重复命令。可通过 /config 永久配置。

斜杠命令 (Slash Commands)

官方文档

Anthropic Docs - Slash Commands

内置命令

动态 MCP 命令

MCP 服务器可动态暴露命令，格式为 /mcp__<server>__<prompt>，如 /mcp__ultra-mcp__analyze-code

命令变更较快（请以本地 /help 与官方文档为准）

  • /output-style 仍可用（用于切换输出风格）
  • /agents 仍可用（用于管理 SubAgent）
  • --add-dir 是当前官方推荐的附加目录方式
  • 不建议维护”已移除命令”静态清单，容易随版本失效

新增命令详解（v2.1.63+）

/btw - 侧链对话（Side-chain Conversations）

命令概述

/btw（“by the way” 的缩写）允许你在主任务运行期间发起不中断当前工作流的侧链对话，实现”一边干活一边提问”。

核心功能

功能说明
并行提问在不中断主任务的情况下提出快速的侧问题
实时补充在长时间运行的任务过程中随时补充想法和需求
减少上下文切换无需等待主任务完成再提问，减少思维中断

适用场景

与普通消息的区别

特性普通消息/btw
对主任务的影响中断当前任务，等待响应后继续不中断主任务的执行
响应时机立即响应在主任务运行间隙处理
上下文关联与主对话上下文强关联独立的侧链上下文

最佳实践

建议说明
简短提问侧链适合快速确认和简短问题，复杂任务建议等主任务完成后再讨论
避免冲突不要在侧链中要求修改主任务正在操作的同一文件
记录想法把临时冒出的想法用 /btw 记录下来，避免遗忘

/simplify - 代码简化与优化

命令概述

/simplify 是 Claude Code 2.1.63 版本新增的内置 Skill，专注于代码重构和简化，帮助提升代码质量和可维护性。

核心功能

功能说明
清理代码差异减少 PR diff 的复杂度，使代码审查更高效
降低复杂度识别并简化过度复杂的代码结构
提升可读性重构代码使其更易理解和维护
PR 准备加速自动化 PR 提交前的代码清理工作

适用场景

工作流程

graph LR
    A[执行 /simplify] --> B[分析代码结构]
    B --> C[识别复杂点]
    C --> D[生成简化方案]
    D --> E[应用重构]
    E --> F[验证功能不变]

最佳实践

建议说明
提交前使用在 git commit 前运行，确保提交的代码质量
配合 CLAUDE.md在项目的 CLAUDE.md 中定义代码风格规范，/simplify 会遵循这些规范
小范围迭代对大型重构，建议分模块逐步简化，而非一次性处理整个项目
结合代码审查简化后的代码仍需人工审查，确保业务逻辑正确

/batch - 批量任务处理

命令概述

/batch 是 Claude Code 2.1.63 版本新增的内置 Skill，专门用于并行执行重复性的代码迁移和批量操作。

核心功能

功能说明
并行执行同时处理多个文件或服务的相同操作
批量重构跨多个文件执行统一的代码变更
大规模迁移自动化处理 API 升级、依赖更新等迁移任务
一致性保证确保所有文件应用相同的变更模式

适用场景

工作流程

graph TD
    A[执行 /batch] --> B[识别目标文件]
    B --> C[生成变更计划]
    C --> D{用户确认?}
    D -->|是| E[并行执行变更]
    D -->|否| F[调整计划]
    F --> C
    E --> G[运行测试验证]
    G --> H[生成变更报告]

并行处理优势

优势说明
速度提升多文件同时处理，大幅缩短迁移时间
一致性所有文件应用相同的变更逻辑，避免遗漏
可追溯生成详细的变更日志，便于审查和回滚
减少人工自动化重复性工作，释放开发者精力

最佳实践

建议说明
先小范围测试在少量文件上验证变更逻辑，确认无误后再全量执行
配合版本控制在独立分支上执行批量操作，便于审查和回滚
明确变更范围清晰描述要处理的文件范围和变更内容
运行测试套件批量变更后务必运行完整测试，确保功能正常
分阶段提交大规模变更建议分多个 PR 提交，便于代码审查

与 Agent Teams 结合

高级用法

/batch 可以与 Agent Teams 代理团队 结合使用，让多个 Agent 并行处理不同模块的批量任务：

创建一个 Agent Team，使用 /batch 并行重构以下模块：
- Agent 1: 处理 frontend/ 目录
- Agent 2: 处理 backend/ 目录
- Agent 3: 处理 shared/ 目录

/insights - 使用洞察与个性化优化报告

命令概述

/insights 会分析你过去 30 天的所有 Claude Code 会话，生成一份交互式 HTML 报告，涵盖使用模式、摩擦点和个性化优化建议。类似于”来自一位非常了解你的技术经理的绩效反馈”。

核心功能

功能说明
使用模式分析统计会话数、Token 消耗、工具调用频率、活跃时间段等
项目维度拆解按项目展示会话摘要，了解各项目的工作分布
摩擦点诊断识别重复劳动、常见错误、低效工作流并按频率排序
个性化建议提供可复制粘贴的 CLAUDE.md 规则、自定义 Skill 和 Hook 配置建议

报告结构

报告输出为单个交互式 HTML 文件，保存在 ~/.claude/usage-data/report.html，包含以下核心章节：

章节内容
At a Glance（概览）四大维度速览：做得好的地方、阻碍你的因素、可快速尝试的优化、面向未来的工作流建议
Stats Overview（统计概览）会话总数、Token 用量、成本等顶层数据
What You Work On（工作内容）按项目展示会话卡片、目标分类、常用工具、编程语言分布
Activity Patterns（活动模式）活跃时段热力图、并行会话分析（支持时区切换）
Impressive Things（亮点）高光操作回顾，展示做得好的实践
Where Things Go Wrong（摩擦分析）按频率排序的摩擦点，附带实际会话中的具体示例
CLAUDE.md Suggestions（建议）可直接复制的 CLAUDE.md 规则和推荐尝试的 Claude Code 功能
Custom Skills & Hooks（技能与钩子）基于你的使用模式推荐的自定义 Skill 和 Hook 配置

工作原理

graph TD
    A[执行 /insights] --> B[收集会话日志]
    B --> C[过滤有效会话]
    C --> D[Facet 提取<br/>使用 Haiku 模型]
    D --> E[缓存 Facets]
    E --> F[生成叙述性分析]
    F --> G[渲染 HTML 报告]
阶段说明
会话收集从 ~/.claude/projects/ 读取过去 30 天的会话日志
过滤规则排除 SubAgent 子会话、内部会话、少于 2 条用户消息或不足 1 分钟的会话
Facet 提取对每个会话（每次最多 50 个新会话）使用 Haiku 模型提取结构化”Facets”——包括目标分类、用户满意度信号等
分块处理超过 30,000 字符的会话会被分成 25,000 字符的块，分别摘要后再提取 Facet
缓存机制Facets 缓存在 ~/.claude/usage-data/facets/，后续运行更快

使用方法

# 直接运行（注释）
/insights

常见问题与解决

  • 如果命令不可用，先退出 Claude Code（Ctrl+C）再重新打开，可能需要更新版本
  • 如果报告中叙述性章节显示”No data”，可删除 ~/.claude/usage-data/facets/ 目录后重新运行
  • 每次最多处理 50 个新会话，会话量大时可能需要多次运行

实际反馈示例

社区增强工具

名称说明
claude-insights社区 CLI 工具，可将 /insights 报告解析为可执行的 CLAUDE.md 规则、Skills、Hook 配置和优先级待办清单

最佳实践

建议说明
定期运行建议每 1-2 周运行一次，持续优化工作流
关注摩擦分析报告中”Where Things Go Wrong”是投入产出比最高的章节
落地建议将报告中的 CLAUDE.md 建议和 Skill/Hook 配置实际应用到项目中
多次运行会话量大时多次运行以覆盖更多历史会话

SubAgent（子代理）

官方文档

Anthropic Docs - Subagents

SubAgent 是独立上下文的专用助手，和 Skills 不是同一套机制：

名称类型用途/适用场景注意事项
SubAgent协作机制将复杂任务委派给专门角色（可配置描述、工具、模型）适合需要独立上下文的子任务
Skills能力封装复用提示词/流程能力便于沉淀可复用能力模块
Agent Teams实验功能多代理并行协作功能演进快，建议按版本验证

当前官方使用方式

  1. 通过 /agents 打开子代理管理
  2. 选择内置子代理，或创建自定义子代理
  3. 子代理文件位于：
    • 项目级：.claude/agents/*.md
    • 用户级：~/.claude/agents/*.md

常见子代理类型（示例）

名称类型用途/适用场景注意事项
Explore内置子代理快速代码库探索（只读）适合前期摸底，不直接改动代码
Plan内置子代理规划模式下的研究代理更偏分析与方案输出
general-purpose内置子代理通用任务处理通用但不如专用子代理聚焦
Bash内置子代理在独立上下文执行终端命令留意命令权限与副作用
statusline-setup内置子代理配置状态栏主要用于 UI/显示配置
Claude Code Guide内置子代理回答 Claude Code 使用相关问题细节仍需结合当前版本核对
code-reviewer自定义示例代码审查需按团队规范调整审查标准
debugger自定义示例调试和错误排查建议配合日志与复现步骤使用

说明

内置列表会随版本变化，请以 /agents 实际显示为准。

SubAgent vs Skills vs Commands

特性Commands（兼容旧格式）Skills（推荐）SubAgent
文件位置.claude/commands/*.md.claude/skills/<name>/SKILL.md.claude/agents/*.md
主要用途复用一段提示词/动作模块化能力封装独立角色处理复杂子任务
上下文隔离❌可选（context: fork）✅
自动委派❌❌✅

一句话决策

名称类型用途/适用场景注意事项
动作标准化、一步到位决策建议推荐 Skills（或兼容 Commands）适合复用高频动作并沉淀团队规范
独立上下文 + 自动委派决策建议推荐 SubAgent适合聚焦型子任务，减少主会话噪声
多代理并行协作决策建议推荐 Agent Teams实验功能，建议先小规模验证

Agent Teams（代理团队）

官方文档

Agent Teams Documentation

核心概念

Agent Teams 是一个实验性功能，允许协调多个 Claude Code 实例协同工作。

组件说明
Team Lead主要会话，负责创建团队、分配任务、综合结果
Teammates独立的 Claude 实例，拥有各自上下文窗口
Task List共享任务列表，带依赖跟踪
Mailbox代理间直接消息传递系统

启用方式

SubAgent vs Agent Teams

特性SubAgentAgent Teams
上下文独立上下文，结果返回调用者完全独立，各自运行
通信仅报告结果给主代理队员间直接消息传递
协调主代理管理所有工作共享任务列表，自协调
Token 成本较低较高（每个队友独立实例）
适用场景专注任务，仅需结果需要讨论协作的复杂工作

团队工作流程

┌─────────────────────────────────────────────────────────┐
│  1. 创建团队                      │
├─────────────────────────────────────────────────────────┤
│  2. 生成队友 (Spawn Teammates)                          │
│     ┌─────────┐ ┌─────────┐ ┌─────────┐                │
│     │ 队友 A  │ │ 队友 B  │ │ 队友 C  │                │
│     └─────────┘ └─────────┘ └─────────┘                │
├─────────────────────────────────────────────────────────┤
│  3. 任务分配 (Task Assignment)                          │
│     - Team Lead 分配或队友自动认领                       │
│     - 支持任务依赖管理                                   │
├─────────────────────────────────────────────────────────┤
│  4. 并行执行 (Parallel Execution)                       │
│     - 队友独立工作                                       │
│     - 直接相互通信                                       │
├─────────────────────────────────────────────────────────┤
│  5. 结果合成 (Synthesize Results)                       │
│     - Team Lead 汇总所有结果                            │
├─────────────────────────────────────────────────────────┤
│  6. 清理团队 (Cleanup Team)                             │
└─────────────────────────────────────────────────────────┘

任务管理

任务结构

{
  "id": "1",
  "subject": "QA: 核心页面返回 200 和有效 HTML",
  "description": "获取 localhost:4321 的所有主要页面...",
  "status": "completed",
  "owner": "qa-pages",
  "blocks": ["2"],
  "blockedBy": []
}

任务状态

状态说明
pending待处理
in_progress进行中
completed已完成

任务依赖

名称类型用途/适用场景注意事项
blocks / blockedBy依赖字段建立任务依赖关系依赖图过深会增加协作成本
解除阻塞流转规则前置任务完成后，被阻塞任务可继续推进建议配合状态同步避免误判

SendMessage 消息类型

类型用法
message发送 DM 给单个队友
broadcast广播消息给所有队友（谨慎使用）
shutdown_request请求队友关闭
shutdown_response批准/拒绝关闭请求
plan_approval_response批准/拒绝队友的计划

实际使用示例

显示模式

// settings.json
{
  "teammateMode": "in-process"
}

或命令行：

claude --teammate-mode in-process

委派模式

按 Shift+Tab 循环进入委派模式，限制负责人只使用协调工具。

质量门限 (Quality Gates)

使用 Hooks 在关键节点强制执行规则：

Hook触发时机用途
TeammateIdle队友即将空闲时退出代码 2 可发送反馈，保持队友继续工作
TaskCompleted任务标记完成时退出代码 2 可防止完成，要求修改

最佳实践

  1. 提供足够上下文：生成提示中包含任务特定细节
  2. 适当任务粒度：每队友 5-6 个任务为宜
  3. 避免文件冲突：确保每个队友操作不同文件集
  4. 从简单任务开始：代码审查、文档编写等边界清晰的任务
  5. 监控和引导：定期检查进度，必要时重定向

局限性

限制说明
无会话恢复/resume 和 /rewind 不恢复 in-process 队友
任务状态滞后队友有时无法标记任务为完成
关闭较慢队友完成当前请求后才会关闭
单团队限制一会话只能管理一个团队
无嵌套团队队友无法生成自己的团队
负责人固定创建会话是终身负责人

清理团队

# 关闭单个队友（注释）
Ask the researcher teammate to shut down
 
# 清理整个团队（注释）
Clean up the team

重要提示

始终使用 Team Lead 来清理团队。队友不应运行清理操作。

自定义命令 (Custom Commands)

把一段”可复用提示词/动作”做成斜杠命令（/xxx），像”宏/脚本”一样快速执行。

最新说明

官方已将 Custom Commands 合并到 Skills 体系；.claude/commands/ 仍可作为兼容目录使用。

文件位置

位置作用域
.claude/skills/<name>/SKILL.md项目级（推荐）
~/.claude/skills/<name>/SKILL.md用户级（推荐）
.claude/commands/<name>.md项目级（兼容旧格式）
~/.claude/commands/<name>.md用户级（兼容旧格式）

创建方式

不带参数

创建 .claude/commands/fix.md：

检查代码中的常见问题并修复它们。

调用：/fix

带参数

使用 $ARGUMENTS 占位符：

查找并修复问题 #$ARGUMENTS。按以下步骤操作：
1. 理解问题
2. 找到相关代码
3. 实现修复
4. 添加测试

调用：/fix 123

参数编号

使用 $0、$1 等引用特定参数：

迁移 $0 组件，从 $1 框架迁移到 $2 框架

调用：/migrate SearchBar React Vue

命令命名

名称类型用途/适用场景注意事项
文件名映射命名规范文件名即命令名：optimize.md → /optimize命名要短且语义清晰
frontmatter 命名命名规范建议显式写 name避免跨目录冲突
作用域命名命名规范用户级与项目级不要同名同名共存时触发可能不符合预期

三方命令库

名称类型用途/适用场景注意事项
wshobson/commandsGitHub 仓库生产级命令集合，可按场景拷贝改造引入前先审查命令是否涉及写文件/执行脚本
Claude Code Commands命令目录站按用途快速检索社区命令模板优先选近期维护、说明完整的命令模板

Tip

先从只读型命令开始引入，再逐步加入会写文件/执行命令的高权限命令。

Skills

Skills 是强大的模块化能力扩展系统，支持 frontmatter 配置、脚本执行、工具限制、模型选择等高级特性。

官方文档

核心能力

能力说明
脚本执行可创建并运行 Python/JavaScript/Bash 等脚本
文件系统访问在虚拟环境中操作文件
工具集成集成 MCP 工具和内置工具
上下文隔离context: fork 实现独立子代理环境
多模型支持为 Skill 指定特定模型

脚本执行模式

执行模式（推荐）：脚本代码不进入上下文，只输出结果

python scripts/analyze_form.py input.pdf

参考模式：读取脚本内容作为参考

See analyze_form.py for the field extraction algorithm

文件位置

位置作用域
.claude/skills/<name>/SKILL.md项目级
~/.claude/skills/<name>/SKILL.md用户级

基本格式

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
allowed-tools: Read, Write, Bash
---
 
# PDF Processing Skill
 
处理 PDF 文件，提取文本和表格...

Frontmatter 完整配置

配置项必填说明
name✅Skill 名称（小写字母+数字+连字符，最大 64 字符）
description✅功能描述（建议写清晰触发场景）
allowed-tools❌限制可用工具（如 Read,Grep,Bash）
disable-model-invocation❌禁止 Claude 自动调用
user-invocable❌仅 Claude 可调用，用户菜单隐藏
model❌指定 Skill 使用的模型
context❌project（默认）或 fork（独立上下文）
agent❌指定子代理类型
argument-hint❌参数提示（如 [issue-number]）
hooks❌在 Skill 内定义 Hook（如果版本支持）

命名约定

名称类型用途/适用场景注意事项
命名格式规范建议使用小写 + 连字符（如 pdf-processing）保持团队内统一命名风格
语义清晰规范建议避免模糊名称（如 helper, utils, tools）名称应可直接推断用途
触发导向规范建议表达“何时调用”而非“如何实现”优先场景名，少用技术细节名

最佳实践

核心原则

  1. 简洁至上：只添加 Claude 不知道的上下文
  2. 适当自由度：根据任务特点选择高/中/低自由度模式
  3. 渐进式披露：将详细信息放在单独文件中
  4. 多模型测试：为所有计划使用的模型创建测试用例

详见：Skill 编写最佳实践

自定义命令 vs Skills

特性自定义命令Skills
文件位置.claude/commands/*.md.claude/skills/<name>/SKILL.md
配置方式纯 MarkdownYAML frontmatter + Markdown
脚本执行不支持支持
工具限制不支持支持 allowed-tools
模型选择不支持支持 model 字段
独立上下文不支持支持（context: fork）
适用场景简单提示词复用复杂功能、脚本执行、权限控制

自带工具

官方文档

Anthropic Docs - Tools available to Claude

核心工具

文件操作

工具用法示例说明
Read读取 src/app.ts 并解释关键逻辑仅读取文件，不修改
Write把修复写入 src/app.ts创建/覆盖文件
Edit把 foo() 替换为 bar()对单/多文件定点修改
MultiEdit批量替换多个片段一次性多点编辑
Glob / GlobTool匹配 src/**/*.ts文件模式匹配
LS列出目录结构目录浏览

搜索与执行

工具用法示例说明
Grep / GrepTool搜索文本 TODO:内容搜索（基于 ripgrep）
Bash运行 npm test执行 shell 命令
BashOutput查看后台命令输出读取 Bash 进程输出
KillBash终止挂起命令结束 Bash 进程

Notebook 与网络

工具用法示例说明
NotebookRead查看 eda.ipynb读取 Jupyter Notebook
NotebookEdit修改第 3 个单元格修改 Notebook 单元格
WebSearch检索 zod vs yup 对比联网搜索
WebFetch抓取文档并总结 API 变化抓取 URL 内容

Note

工具名可能随版本演进，实际可用列表请以当前会话和官方文档为准。

规划与协作

工具用途
Task启动专门的子代理处理复杂任务
ExitPlanMode呈现计划供用户批准

关于 Agent Teams

Agent Teams 为实验性能力，官方文档以概念和工作流为主，不建议依赖未公开稳定的底层工具名。

其他工具

工具用途
LSP语言服务器协议集成
View打开文件/目录视图

常用玩法

UltraThink 模式

来源

Anthropic - Claude Code Best Practices

这是在 Claude Code 中包含了一些魔法触发词，它会把模型的**思考预算（thinking budget）**拉到最高，让 Claude 在回答前花更多计算量做权衡、比对方案和自检，适合复杂架构设计、疑难调试、性能分析这类重思考场景。

从低到高的映射：think < think hard < think harder < ultrathink（逐级增加思考预算）。

触发词列表

怎么触发？

在对话或指令末尾附上 ultrathink 或上述触发词：

先阅读仓库并给出实现方案 ultrathink

关键词 vs /model 命令

  • 关键词（如 ultrathink）：仅对当次回复生效，适合临时提升思考深度
  • /model 命令：切换 effort 级别，对后续所有回复持续生效

并行开发（git worktree）

官方推荐

Claude Code 团队的 Boris Cherny：“我们最大的生产力技巧是打开 3 到 5 个 git worktree，每个运行独立的 Claude 会话。“

为什么使用 Git Worktree？

优势说明
上下文隔离每个 worktree 有独立的 Claude 会话和上下文
并行开发同时在不同分支上工作，互不干扰
方案对比快速测试多种实现方案

原生 Worktree 支持（推荐）

新特性

Claude Code 现已内置 --worktree（-w）标志，一条命令即可创建隔离 worktree 并启动会话，无需手动操作 git。

基本用法

# 创建指定名称的 worktree 并启动会话
claude --worktree feature-auth
 
# 自动生成随机名称（如 "bright-running-fox"）
claude --worktree
 
# 简写
claude -w bugfix-123

工作原理

名称说明
存储位置<repo>/.claude/worktrees/<name>
分支命名自动从默认远程分支创建 worktree-<name> 分支
共享历史每个 worktree 有独立文件副本，但共享仓库历史和远程连接
会话恢复/resume 自动显示同一仓库所有 worktree 的会话

.gitignore 配置

建议在 .gitignore 中添加 .claude/worktrees/ 以防止 worktree 内容显示为未跟踪文件。

智能清理

场景行为
无更改worktree 和分支自动删除
有更改或提交Claude 提示选择保留或删除

SubAgent 中的 Worktree 隔离

在 SubAgent 的 frontmatter 中添加 isolation: worktree，可让子代理在独立 worktree 中运行：

---
name: parallel-worker
description: Worker that needs isolated environment
isolation: worktree
---

也可以在会话中直接要求：

> use worktrees for your agents

非 Git 版本控制

对于 SVN、Perforce、Mercurial 等，可配置 WorktreeCreate 和 WorktreeRemove hooks 提供自定义的 worktree 创建和清理逻辑。

手动 Worktree 管理

原生 vs 手动对比

特性原生 --worktree手动 git worktree
创建方式一条命令自动完成需手动创建 + 切换目录 + 启动 Claude
清理智能清理（无更改自动删除）需手动 git worktree remove
会话集成/resume 自动聚合所有 worktree 会话需记住各目录位置
SubAgent 集成isolation: worktree 一键隔离不支持
存储位置统一在 .claude/worktrees/可自定义任意位置
分支控制自动创建新分支可检出任意现有分支

典型工作流

实践建议

  • 建议限制在 2-3 个活跃 worktree，审查带宽是瓶颈而非 Claude 的速度
  • 每个新 worktree 可能需要初始化开发环境（npm install、虚拟环境等）
  • 确保每个 worktree 操作不同文件集，避免合并冲突

多级 CLAUDE.md

Claude Code 支持多层级 CLAUDE.md 记忆文件，按作用域自动合并。

层级结构

级别位置说明
企业级macOS: /Library/Application Support/ClaudeCode/CLAUDE.md；Linux: /etc/claude-code/CLAUDE.md；Windows: %ProgramData%\ClaudeCode\CLAUDE.md组织级策略（由管理员配置）
用户级~/.claude/CLAUDE.md个人全局偏好
项目级项目根/CLAUDE.md团队共享规则
项目本地级（已弃用）项目根/CLAUDE.local.md本地私有偏好（建议迁移）
子目录级子目录/CLAUDE.md更贴近当前文件，优先级更高

优先级规则

冲突时：更具体（更靠近当前文件） > 更宽泛
名称类型用途/适用场景注意事项
启动会话加载阶段加载企业级、用户级、项目级记忆提供基础全局规则
进入子目录加载阶段继续加载目录及父目录链上的 CLAUDE.md越靠近当前文件优先级越高
文档引用加载机制@路径 引用文档一并载入上下文便于拆分大规范文件
项目记忆自动机制自动维护 ~/.claude/projects/记录项目会话相关记忆

文件夹级示例

项目根/
├── CLAUDE.md              # 项目级：通用规则
├── api/
│   ├── CLAUDE.md         # API 规则：RESTful 设计、文档要求
│   └── ...
├── frontend/
│   ├── CLAUDE.md         # 前端规则：组件规范、样式指南
│   └── ...
└── backend/
    ├── CLAUDE.md         # 后端规则：数据库、缓存策略
    └── ...

文档引用

使用 @ 语法导入其他文档：

# 项目 CLAUDE.md（示例标题）
 
## 编码规范
@docs/coding-standards.md
@docs/api-guidelines.md
 
## 部署流程
@docs/deployment.md

最佳实践

  1. 避免单个大文件：使用文档引用分解内容
  2. 按模块组织：大型项目使用文件夹级 CLAUDE.md
  3. 团队共享：项目级 CLAUDE.md 提交到仓库
  4. 个人定制：用户级 ~/.claude/CLAUDE.md 保留个人偏好

学习模式（输出风格）

Claude Code 支持多种输出风格，其中”学习模式”是一种专门的教学模式。

三种输出风格

风格特点适用场景
Default（默认）工程化简洁输出，专注高效完成任务日常开发、快速实现
Explanatory（解释）提供详细解释和推理过程理解复杂概念、代码审查
Learning（学习）苏格拉底式教学，引导式学习编程初学者、深度学习

如何切换

# 打开交互式菜单选择（注释）
/output-style
 
# 直接切换到特定模式（注释）
/output-style learning      # 学习模式
/output-style explanatory  # 解释模式
/output-style default      # 默认模式

学习模式特点

名称类型用途/适用场景注意事项
提问优先教学特征通过问题引导，而非直接给答案适合想提升独立思考能力的学习者
引导式思考教学特征帮助用户自己收敛方案适合“会做题”导向的训练场景
结对式学习教学特征以交互式结对编程推进实践适合边做边学的任务流程
反依赖学习目标减少对 AI 直接答案的依赖强调长期能力建设

创建自定义风格

/output-style:new

自定义风格存储在 ~/.claude/output-styles/ 目录。

适用人群建议

名称类型用途/适用场景注意事项
初学者人群建议推荐 /output-style learning帮助建立思路与问题分解能力
进阶者人群建议推荐 /output-style explanatory兼顾结论与解释，便于复盘
专家人群建议推荐默认模式输出更精炼，执行效率更高

关于记忆和上下文管理

让 Claude Code 记住你的代码风格和项目惯例。

Note

多级 CLAUDE.md 的加载顺序与作用域规则，详见上文「多级 CLAUDE.md」。本节聚焦实践落地。

记忆层级

机制说明配置方式
会话记忆当前会话中的互动和决策自动，会话结束清除
CLAUDE.md项目/目录级持久记忆手动编写，团队共享
Skills固化的专业知识库YAML + Markdown
Custom Commands可复用的提示词模板纯 Markdown

配置方法

记忆优先级

更具体规则 > 更宽泛规则
（通常：子目录级 > 项目级 > 用户级）

Note

Skills/Custom Commands 是“可调用能力”，不等同于自动记忆层级。

其他 Claude Code 增强项目

Tip

这一节聚焦社区增强工具、插件和集成方案，建议按“用途 → 适用场景 → 风险/门槛”评估后再引入生产环境。

项目清单

名称类型用途/适用场景注意事项
Auto-Claude桌面工具同时管理多个 Claude 会话并看板化跟踪任务，适合并行开发/多人协作/长任务管理第三方工具，建议先在测试项目验证稳定性

常见报错

状态码错误类型说明
400invalid_request_error您的请求格式或内容存在问题。我们也可能对下面未列出的其他 4XX 状态码使用此错误类型。
401authentication_error您的 API 密钥存在问题。
403permission_error您的 API 密钥没有使用指定资源的权限。
404not_found_error未找到请求的资源。
413request_too_large请求超过了允许的最大字节数。建议使用 /compact 命令。
429rate_limit_error您的账户达到了速率限制。
500api_errorAnthropic 系统内部发生了意外错误。
529overloaded_errorAnthropic 的 API 暂时过载。

关于 529 错误

当 Anthropic API 在所有用户中遇到高流量时，可能会出现 529 错误。在极少数情况下，如果您的组织使用量急剧增加，您可能会看到此类错误。为避免 529 错误，请逐步增加流量并保持一致的使用模式。

当通过 SSE 接收流式响应时，可能在返回 200 响应后发生错误，在这种情况下错误处理不会遵循这些标准机制。

相关资源推荐

官方资源

名称类型用途/适用场景注意事项
Claude Code: A Highly Agentic Coding Assistant课程吴恩达 & Anthropic 联合出品，适合系统入门课程会有版本时差，命令细节以最新文档为准
中英文字幕 B 站版本视频搬运对应上面课程的中文字幕版本可能滞后于原始课程更新
Claude Code 最佳实践 (YouTube)官方视频官方实战与工作流演示观看时留意发布时间
How Anthropic teams use Claude Code官方博客团队真实使用方法与经验偏实践经验，参数细节需回到文档核对
Agent Skills with Anthropic课程聚焦 Skills 设计与应用适合在已入门后系统补齐
Claude Code in Action官方培训面向上手和实操的结构化课程只有基础知识，但非常易懂
Intrduction-to-agent-skills官方培训了解什么是 skill，怎么做一个自己的 skill里面还有 skill 跟其他 feature 的对比

三方资源

名称类型用途/适用场景注意事项
Anthropic Courses - Claude Code in Action课程页面官方课程入口聚合，便于统一查找与官方资源有部分重复
一些高级玩法 (X/Twitter)社区帖子高阶技巧速览，适合扩展思路社区经验请二次验证后再落地
everything-claude-codeGitHub 仓库黑客松冠军配置与实践参考配置需结合你自己的权限策略调整
claude-code-best-practiceGitHub 仓库practice made claude perfect结合自己场景使用

好用的 Skills

名称类型用途/适用场景注意事项
news-aggregator-skill社区 Skill新闻聚合与整理涉及外部抓取，注意速率与来源稳定性
baoyu-skills社区 Skill 集多场景技能集合（含图像相关能力）使用前先看每个 Skill 的权限范围
AI-research-SKILLs社区 Skill 集AI 研究与工程类技能库内容较重，建议按主题挑选启用
skills.shSkill 目录站收集可安装 Skills，可快速发现能力目录站展示不代表全部经过安全审计
find-skills发现 Skill按需求检索对应 Skill适合先发现再精装，不要盲装
obsidian-markdown / obsidian-bases / json-canvasObsidian SkillObsidian 官方团队维护的技能方向与你的笔记规范保持一致更佳

Note

引入社区 Skill 前，建议先审查权限、脚本行为和外部依赖。

好用的 SubAgent

名称类型用途/适用场景注意事项
code-simplifier实践案例代码简化与重构思路参考属于案例文章，不是官方内置即装即用包
claude-code-guide内置/本地查询 Claude Code 官方文档与用法输出建议仍需结合当前版本命令核对

One more thing

Tip

后续可补充：大仓库提效、长任务恢复、团队协作规范、成本控制模板等进阶主题。

怎么上车

拼车

名称类型用途/适用场景注意事项
gacCode / store.tu-zi.com服务入口账号拼车与购买入口选择前建议核对服务条款与稳定性（注意别跑路了）
ctok.ai服务入口提供相关购买/服务通道注意价格、节点与售后策略

自己上手

名称类型用途/适用场景注意事项
购买上手环节Apple gift（US 官方购买）+ Apple 内购注意账号区域、支付方式与合规性
部署上手环节US VPS + 中继服务（或 sub2api）先评估网络稳定性、延迟与安全配置

反向链接