Claude Code 使用指南

Thu, 07 May 2026 00:00:00 +0000

一、安装与启动

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

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

二、会话管理

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

2.1 终端命令

操作	命令
恢复最近会话	`claude --continue`
交互式选择会话	`claude --resume`（方向键选择，空格预览）
恢复指定会话	`claude --resume <名称>`
分支新会话	`claude --continue --fork-session`（保留历史，从旧会话分叉）
按 PR 恢复	`claude --from-pr <编号>`

2.2 会话内命令

命令	作用	别名
`/resume [名称]`	打开会话选择器，或切换到指定会话	`/continue`
`/clear`	清空当前对话上下文，开启新会话	`/reset`、`/new`
`/compact [指令]`	压缩长对话释放上下文窗口，可选保留重点	—
`/rename [名称]`	重命名当前会话，不传名称则自动从历史生成	—
`/branch [名称]`	在当前点分叉出新会话	`/fork`
`/export [文件名]`	导出当前对话为纯文本	—
`/copy [N]`	复制最近一次 AI 回复到剪贴板，`/copy 2` 复制倒数第二次	—
`/btw <问题>`	快速旁提问——不记入对话历史，不消耗上下文，无工具调用	—
`/recap`	按需生成一行会话摘要	—
`/context`	以彩色网格可视化当前上下文占用，附优化建议	—
`/add-dir <路径>`	动态添加会话可访问的工作目录	—
`/rewind`	回退对话和/或代码到之前的检查点	`/checkpoint`、`/undo`

会话选择器快捷键：

快捷键	作用
`Ctrl+A`	显示所有项目的会话
`Ctrl+W`	显示当前仓库所有 worktree 的会话
`Ctrl+B`	按当前 git 分支过滤
`Ctrl+R`	重命名高亮会话
`Space`	预览会话内容
`/` 或任意可打印字符	搜索/过滤会话

三、权限模式

3.1 六种模式

模式	自动批准范围	适用场景
`default`	仅读取	入门、敏感项目
`acceptEdits`	读取 + 文件编辑 + 常见文件系统操作	快速迭代同时保持审查
`plan`	仅读取	先探索再编码
`auto`	全部（分类器安全检查）	长任务、减少授权疲劳
`dontAsk`	仅预批准工具	CI/自动化环境
`bypassPermissions`	除受保护路径外全部	隔离容器/VM

3.2 切换方式

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

四、模式切换命令

命令	作用
`/plan [描述]`	进入计划模式（仅研究不编辑）
`/model [模型]`	选择或切换模型，支持调整 effort 级别
`/effort [low\|medium\|high\|xhigh\|max\|auto]`	设置模型推理力度
`/fast [on\|off]`	快速模式开关（仅 Opus 4.6 可用）
`/color [颜色\|default]`	设置提示栏颜色：red/blue/green/yellow/purple/orange/pink/cyan
`/focus`	专注视图——仅显示上次提示、工具调用摘要和最终回复（全屏模式）
`/tui [default\|fullscreen]`	切换终端 UI 渲染模式
`/voice [hold\|tap\|off]`	语音输入模式
`/sandbox`	沙盒模式开关

五、代码与审查

命令	作用
`/review [PR]`	拉取并审查当前分支或指定 PR
`/security-review`	安全审查当前分支的所有待变更文件
`/diff`	打开交互式 diff 查看器，含未提交变更和逐轮 diff
`/init`	为当前项目自动生成 CLAUDE.md
`/simplify [关注点]`	并发启动 3 个审查子代理审查代码质量，汇总后自动修复
`/autofix-pr [提示]`	远程守护——监控 PR，CI 失败或有评论时自动推送修复
`/install-github-app`	为仓库安装 Claude GitHub Actions 应用
`/pr-comments`	查看 PR 评论
`/ultrareview [PR]`	云端多代理深度审查（Pro/Max 免费 3 次）
`/ultraplan <提示>`	云端起草计划，浏览器审查后执行或返回终端

六、权限与配置

命令	作用	别名
`/permissions`	管理工具的 allow/ask/deny 规则（交互对话框）	`/allowed-tools`
`/config`	打开设置界面：主题、模型、输出风格、偏好	`/settings`
`/hooks`	查看所有钩子配置（按事件分类的只读浏览器）	—
`/memory`	编辑 CLAUDE.md 记忆文件，开关自动记忆	—
`/keybindings`	打开或创建快捷键配置文件	—
`/skills`	列出所有可用技能（按 `t` 按 token 数排序）	—
`/mcp`	管理 MCP 服务器连接与 OAuth 认证	—
`/plugin`	管理插件	—
`/reload-plugins`	热重载所有插件	—
`/ide`	管理 IDE 集成状态	—
`/chrome`	配置 Chrome 浏览器集成	—
`/remote-env`	配置 `--remote` 启动时的默认远程环境	—
`/terminal-setup`	配置 Shift+Enter 键位（VS Code、Cursor、Windsurf 等）	—
`/doctor`	诊断安装和环境问题	—
`/status`	系统状态：版本、模型、账户、连接	—
`/login`	登录 Anthropic 账户	—
`/logout`	退出 Anthropic 账户	—
`/privacy-settings`	隐私设置（Pro/Max）	—

七、任务与调度

命令	作用	别名
`/tasks`	查看和管理后台任务	`/bashes`
`/agents`	管理子代理配置	—
`/loop [间隔] [命令]`	按间隔重复执行，如 `/loop 5m check deploy`；裸 `/loop` 进入自主维护	—
`/schedule [描述]`	创建/更新/列表/运行云端定时代理（routines）	`/routines`
`/usage`	会话费用、用量限制、活动统计	`/cost`、`/stats`
`/extra-usage`	配置超额用量（达速率上限时启用）	—

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

特性	CLAUDE.md	Skill
加载时机	每次对话自动全量加载	仅在调用时加载
适合内容	项目架构、常用命令、关键约束	专项流程、参考手册、长文档
调用方式	自动	用户 `/技能名` 或 Claude 自动匹配

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

8.2 内置技能

命令	作用
`/batch <指令>`	大规模并行修改：分解 5-30 个任务，在隔离 worktree 中并发执行，每个开 PR
`/claude-api`	加载 Claude API 参考（Python/TS/Java/Go/Ruby/C#/PHP/curl）
`/debug [描述]`	开启调试日志并辅助排查问题
`/fewer-permission-prompts`	扫描历史记录，为常用只读命令生成项目 allowlist 减少授权弹窗
`/insights`	分析使用数据生成 Claude Code 会话报告
`/simplify [关注点]`	并发启动 3 个审查子代理审查代码质量，汇总后自动修复
`/statusline`	配置终端状态栏
`/team-onboarding`	根据你过去 30 天的使用历史生成团队入职指南
`/loop`	循环执行命令
`/schedule`	云端定时任务
`/init`	初始化 CLAUDE.md
`/review`	PR 审查
`/security-review`	安全审查

8.3 创建自定义 Skill

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

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

文件格式：

---
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 所有事件一览

事件	触发时机	可阻断
`SessionStart`	会话开始或恢复	否
`SessionEnd`	会话终止	否
`UserPromptSubmit`	用户提交提示	是
`UserPromptExpansion`	斜杠命令展开为提示	是
`PreToolUse`	工具调用执行前	是（allow/deny/defer）
`PostToolUse`	工具调用成功执行后	否
`PostToolUseFailure`	工具调用执行失败后	否
`PostToolBatch`	所有并行工具调用完成后	是
`PermissionRequest`	权限对话框弹出时	是
`PermissionDenied`	auto 模式分类器拒绝工具时	否（可设重试）
`Notification`	Claude 发送通知时	否
`SubagentStart`	子代理启动时	否
`SubagentStop`	子代理完成时	是
`TaskCreated`	任务创建时	是
`TaskCompleted`	任务标记完成时	是
`Stop`	Claude 完成回复时	是
`StopFailure`	因 API 错误结束轮次时	否
`TeammateIdle`	队友即将空闲时	是
`InstructionsLoaded`	CLAUDE.md 或规则文件加载时	否
`ConfigChange`	会话中配置文件变更时	是
`CwdChanged`	工作目录变更时	否
`FileChanged`	被监视的文件在磁盘上变更时	否
`WorktreeCreate`	Worktree 被创建时	是
`WorktreeRemove`	Worktree 被删除时	否
`PreCompact`	上下文压缩前	是
`PostCompact`	上下文压缩后	否
`Elicitation`	MCP 服务器请求用户输入时	是
`ElicitationResult`	用户响应 elicitation 后	是

9.2 钩子类型

类型	机制	适用场景
`command`	Shell 命令，通过退出码和 stdout JSON 通信	本地检查、格式验证
`http`	POST JSON 到 HTTP 端点	外部服务集成
`mcp_tool`	调用已连接 MCP 服务器的工具	复用 MCP 能力
`prompt`	单轮 Claude 评估（yes/no 决策）	内容审查、是否放行
`agent`	启动子代理（有 Read/Grep/Glob 工具）	复杂前置检查（实验性）

9.3 退出码规则

退出码	含义
`0`	成功。stdout 解析为 JSON 决策
`2`	阻断性错误。操作被阻止，stderr 展示给 Claude
其他	非阻断性错误。继续执行

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）：

{
  "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 输入编辑

快捷键	作用
`Enter`	提交消息（换行用 `Shift+Enter` 或 `Alt+Enter`）
`Ctrl+O`	切换详细查看器（显示思考过程）
`Ctrl+J`	在消息中插入换行（备选）
`Ctrl+I`	在消息末尾插入文件内容
`Ctrl+K`	将选中文字转为代码块
`Ctrl+L`	清空当前输入并重绘屏幕
`Ctrl+G`	在外部文本编辑器打开当前提示
`Ctrl+R`	反向搜索命令历史
`Ctrl+C`	取消当前输入/生成
`Ctrl+D`	中断正在执行的工具调用
`Esc`	取消当前输入
`Esc + Esc`	打开 rewind/checkpoint 菜单

10.2 模式与界面

快捷键	作用
`Shift+Tab`	循环切换权限模式
`Ctrl+E`	打开/关闭思考模式
`Ctrl+V`	打开/关闭详细模式
`Ctrl+B`	后台运行任务（tmux 下按两次）
`Ctrl+T`	切换任务列表显示
`Ctrl+S`	保存当前对话到文件
`Ctrl+W`	查看当前 worktree 信息
`Option+P` / `Alt+P`	切换模型
`Option+T` / `Alt+T`	切换扩展思考

10.3 输入技巧

快捷键/字符	作用
`! 命令`	直接运行 shell 命令，输出加入上下文
`@ 文件路径`	文件路径自动补全
输入 `/`	列出所有可用斜杠命令

十一、上下文管理

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）模式

# 单次问答
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 状态、当前模型、费用等。支持自定义模板。

十八、账号与费用

命令	作用
`/usage`	会话费用、用量限制、活动统计
`/extra-usage`	达速率上限时启用超额用量
`/login`	登录 Anthropic 账户
`/logout`	退出账户
`/upgrade`	升级到更高计划套餐

十九、常用工作流实例

代码审查

1
2
3

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

持续监控

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

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

大规模重构

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

计划优先

1
2
3

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

跨会话工作

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

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

安全审查

1
2
3

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

Claude on Xiang's Blog