Claude Code 使用指南

一、安装与启动§

1
2
3
4
5
6
7
8
9

# 安装
npm install -g @anthropic-ai/claude-code

# 基本用法
claude                    # 进入交互式会话
claude "帮我审查这个 PR"   # 单次任务
claude -p "解释这个函数"   # 非交互模式，直接输出到 stdout
claude -n <名称>          # 命名当前会话，方便后续查找
claude --worktree         # 在隔离 git worktree 中启动

二、会话管理§

会话以 JSONL 文件存储在 ~/.claude/projects/ 下，每个会话拥有独立的上下文窗口。

2.1 终端命令§

2.2 会话内命令§

会话选择器快捷键：

三、权限模式§

3.1 六种模式§

3.2 切换方式§

• Shift+Tab — 终端内循环切换模式
• /plan [描述] — 从提示符进入计划模式
• claude --permission-mode plan — 启动时指定模式
• settings.json: "permissions": { "defaultMode": "plan" } — 设为默认

四、模式切换命令§

五、代码与审查§

六、权限与配置§

七、任务与调度§

7.1 任务（Task）系统§

Claude Code 对复杂多步任务自动创建任务列表，有四个状态：pending → in_progress → completed。

• Ctrl+T — 在状态栏切换显示任务列表（最多 5 条）
• 桌面通知告知 —— “给我列一下所有任务”
• 任务在上下文压缩后依然保留
• 跨会话共享任务列表：CLAUDE_CODE_TASK_LIST_ID=my-project claude

7.2 定时调度细节§

1
2
3

/loop 5m check deploy        # 每 5 分钟检查一次
/loop                         # 自主维护循环（适合 CI 监控等场景）
/loop check the PR            # Claude 自我调节节奏

• /loop 只在当前会话存活期间有效，退出即终止
• /schedule 创建的 routine 是云端持久化的，与当前会话生命周期无关
• 创建 .claude/loop.md 可以自定义默认维护任务的提示词

八、Skills（技能）系统§

技能是扩展 Claude 能力的机制。核心优势：指令按需加载，不用的技能零成本。

8.1 技能 vs CLAUDE.md§

经验法则：长参考文档、专项操作流程放 Skill；项目基础信息、核心约束放 CLAUDE.md。

8.2 内置技能§

8.3 创建自定义 Skill§

在以下路径创建 SKILL.md 文件：

~/.claude/skills/<名称>/SKILL.md    # 个人（所有项目可用）
.claude/skills/<名称>/SKILL.md      # 项目级（可提交到仓库）

文件格式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

---
name: my-skill
description: 这个技能做什么，何时使用
when_to_use: 额外的触发短语
disable-model-invocation: true   # 设为 true 则只能手动调用
user-invocable: false            # 设为 true 则只能 Claude 自动调用
allowed-tools: Bash(git *)       # 技能激活期间预批准的工具
model: sonnet                    # 覆盖模型
effort: high                     # 覆盖努力级别
context: fork                    # 在隔离子代理中运行
agent: Explore                   # 配合 context: fork 指定子代理类型
paths: "*.py"                    # 限制触发路径
---

技能指令内容...

8.4 技能调用与生命周期§

• 手动调用：/技能名 参数1 参数2
• 自动调用：Claude 根据 description 字段自动匹配
• 一旦调用，技能内容作为消息进入对话，保留整个会话
• 上下文压缩时会保留最近一次调用（前 5000 token）
• 技能目录被监视，编辑后即时生效无需重启
• 支持 !命令 语法在 prompt 到达 Claude 前做 shell 预处理
• 变量替换：$ARGUMENTS、$0、$1、${CLAUDE_SESSION_ID}、${CLAUDE_SKILL_DIR}

九、Hooks（钩子）系统§

钩子是用户定义的脚本/HTTP 端点/提示词/代理子进程，在特定生命周期事件时自动执行。

9.1 所有事件一览§

9.2 钩子类型§

9.3 退出码规则§

9.4 配置位置§

• ~/.claude/settings.json — 用户级
• .claude/settings.json — 项目级（可提交）
• .claude/settings.local.json — 本地级（gitignore）
• 插件 hooks/hooks.json
• 企业托管策略设置
• Skill/Agent YAML 头信息

查看所有钩子：/hooks。

9.5 典型用法§

桌面通知钩子（~/.claude/settings.json）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude Code 需要注意\" with title \"Claude Code\"'"
      }]
    }]
  }
}

matcher 可设：permission_prompt、idle_prompt、auth_success、elicitation_dialog。

十、快捷键§

10.1 输入编辑§

10.2 模式与界面§

10.3 输入技巧§

十一、上下文管理§

11.1 核心概念§

• 每次对话有上下文窗口限制，超出后最早的消息会被截断
• /context 以彩色网格直观显示当前使用情况
• /compact 在会话中释放上下文（可附带保留重点的指令）
• /clear 完全重置上下文

11.2 省上下文技巧§

• 长参考文档放入 Skill 而非 CLAUDE.md：Skill 只在调用时加载
• 用 /btw 处理临时疑问：不记入对话历史
• 使用子代理处理大量查询：返回摘要而非全量结果
• 定期 /compact：压缩已完成部分的细节，保留决策和结论

十二、Worktree（工作树）§

在隔离的 git worktree 中工作，实验性修改不影响主工作区。

1
2
3

claude --worktree feature-auth   # 在新分支上创建隔离 worktree
claude --worktree bugfix-123     # 另一个平行会话
claude -w                         # 自动生成名称

• Worktree 创建在 .claude/worktrees/<名称>/
• 子代理也可使用 worktree 隔离（agent frontmatter 中 isolation: worktree）
• 退出后根据选择保留或删除

十三、非交互（Headless）模式§

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 单次问答
claude -p "解释这个函数"

# 管道输入
cat errors.txt | claude -p "找出错误原因"

# 结构化输出
claude -p --output-format json "分析 code.py 的结构" | jq '.'

# 流式 JSON 输出
claude -p --output-format stream-json "查询"

# 约束 JSON Schema
claude -p --json-schema '{"type":"object",...}' "分析并结构化返回"

# 恢复上下文后单次执行
claude --continue -p "检查类型错误"

# 无配置文件快速启动
claude --bare -p "查询"

十四、Checkpoint 与 Rewind§

Claude Code 自动为每一次文件编辑创建检查点。

• /rewind 或 Esc Esc — 回退对话和/或代码到之前某个检查点
• /diff — 查看逐轮 diff，对比每次变更
• /branch — 在当前点创建对话分支，保留原会话继续探索

十五、Agent Teams（代理团队）§

通过 /config 启用。Claude 可并行启动多个队友（teammate）同时处理任务。

• 最适合：并行代码审查、多假设验证、独立工作的并行展开
• --teammate-mode 控制显示方式：in-process、tmux、auto

十六、IDE 与编辑器集成§

• VS Code / JetBrains 插件：直接在 IDE 内使用全部功能，自动识别项目结构
• Ctrl+G：在 $EDITOR/$VISUAL 中打开当前提示
• Vim 模式：/config → 编辑器模式 → Vim（完整 vim 键位）
• macOS Option 键：终端设置中启用 “将 Option 作为 Meta”
• PR 状态底部栏：需要 gh CLI，审查状态以彩色下划线显示

十七、状态栏§

/statusline 配置终端状态栏，显示：上下文窗口使用率、git 状态、当前模型、费用等。支持自定义模板。

十八、账号与费用§

十九、常用工作流实例§

代码审查§

1
2
3

claude --resume       # 恢复当前分支的会话
/review               # 审查变更
/security-review      # 安全审查

持续监控§

1
2
3
4

/loop 3m "检查 CI 状态并报告结果"

# 或创建云端持久化的 routine
/schedule "每天 9:00 检查 main 分支构建状态"

大规模重构§

1

/batch "把所有 React class 组件改成函数组件"

计划优先§

1
2
3

/plan "重构认证模块，支持 OAuth2"
# Claude 会先研究代码库，产出方案供你审查
# 满意后在计划模式下退出，进入编辑模式执行

跨会话工作§

1
2
3
4
5
6
7

# 上午的工作
claude -n auth-refactor
# ... 工作 ...
/exit

# 下午继续
claude --continue      # 或 claude --resume auth-refactor

安全审查§

1
2
3

/security-review
# 审查所有未提交变更的安全问题
# 产生 OWASP Top 10 维度的报告