Claude Code 使用指南

写在前面

为简化表达，本文使用cc代指Claude Code。希望另一个cc看完以后也能有所收获🤪。

带有Note标记的链接是十分推荐阅读学习的，比如下面的官方文档，本文的很多内容也是直接取自官方文档。

📝 备注

官方文档（支持中文）

标题中带有【重点】的章节，请认真阅读学习。

Claude Code介绍

核心概念

CLI命令

这部分命令在终端中直接执行。

以下仅列出常用命令，查看完整参考。

命令	描述	示例
claude update	更新到最新版本
claude –version, -v	输出版本号
claude –continue, -c	继续当前目录中最近的对话
claude –resume, -r	按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话	claude –resume auth-refactor
claude mcp list	列出所有配置的MCP服务器
claude –permission-mode	以指定的权限模式开始	claude –permission-mode plan
claude –name, -n	为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。	claude -n “my-feature-work”

交互模式

这部分命令需要在终端中启动cc后，在cc交互页面中执行。

以下仅列出常用命令，完整参考请查看对应链接。

快速命令

完整参考

符号	描述	示例
?	查看当前环境中可用的快捷键
@	感知：将文件/资源注入上下文	解释 @src/auth.ts 的逻辑
!	行动：在提示框中直接执行 Shell	! git log –oneline -5（结果注入上下文）

💡 提示

输入!执行持续性命令后，想再继续对话，需要敲击Esc键。若想后台运行命令，可使用以下方式：

提示 Claude Code 在后台运行命令

按 Ctrl+B 将常规 Bash 工具调用移到后台

在命令的最后添加 &

内置命令

完整参考

以下各表中，<arg> 表示必需的参数，[arg] 表示可选参数。

设置与配置

命令	描述
/help	显示帮助和可用命令
/model [model]	选择或更改 AI 模型。对于支持的模型，使用左/右箭头调整努力级别。更改立即生效，无需等待当前响应完成
/status	打开设置界面（状态选项卡），显示版本、模型、账户和连接性
/config	打开设置界面以调整主题、模型、输出样式和其他首选项。别名：`/settings`
/permissions	查看或更新权限。别名：`/allowed-tools`
/mcp	管理 MCP server 连接和 OAuth 身份验证
/skills	列出可用的 skills
/agents	管理 agent 配置
/plugin	管理 Claude Code plugins
/hooks	管理工具事件的 hook 配置

会话相关

命令	描述
/rename [name]	重命名当前会话。不使用名称时，从对话历史自动生成
/add-dir	将新的工作目录添加到当前会话
/resume [session]	按 ID 或名称恢复对话，或打开会话选择器。别名：`/continue`
/init	使用 `CLAUDE.md` 指南初始化项目
/compact [instructions]	压缩对话，可选的焦点说明
/clear	清除对话历史并释放上下文。别名：`/reset`、`/new`
/export [filename]	将当前对话导出为纯文本。使用文件名时，直接写入该文件。不使用时，打开对话框以复制到剪贴板或保存到文件
/plan	直接从提示进入 plan mode
/tasks	列出和管理后台任务
/diff	打开交互式差异查看器，显示未提交的更改和每轮差异。使用左/右箭头在当前 git 差异和单个 Claude 轮次之间切换，使用上/下浏览文件
/btw	提出快速附加问题，无需添加到对话中

使用情况

命令	描述
/context	将当前上下文使用情况可视化为彩色网格
/cost	显示令牌使用统计信息
/stats	可视化每日使用情况、会话历史、连胜和模型偏好

其他

命令	描述
/doctor	诊断并验证您的 Claude Code 安装和设置
/exit	退出 CLI。别名：`/quit`

键盘快捷键

完整参考

常规控制

快捷键	描述	上下文
`Ctrl+C`	取消当前输入或生成	标准中断
`Ctrl+F`	终止所有后台代理。在 3 秒内按两次以确认	后台代理控制
`Ctrl+D`	退出 Claude Code 会话	EOF 信号
`Ctrl+G`	在默认文本编辑器中打开	在默认文本编辑器中编辑您的提示或自定义响应
`Ctrl+L`	清除终端屏幕	保留对话历史
`Ctrl+O`	切换详细输出	显示详细的工具使用和执行情况
`Ctrl+R`	反向搜索命令历史	交互式搜索以前的命令
`Ctrl+B`	后台运行任务	后台运行 bash 命令和代理。Tmux 用户按两次
`Ctrl+T`	切换任务列表	在终端状态区域中显示或隐藏任务列表
`Up/Down arrows`	导航命令历史	回忆以前的输入
`Esc` + `Esc`	回退或总结	将代码和/或对话恢复到上一个点，或从选定的消息进行总结
`Shift+Tab` 或 `Alt+M`（某些配置）	切换权限模式	在自动接受模式、Plan Mode 和正常模式之间切换。

文本编辑

快捷键	描述	上下文
`Ctrl+K`	删除到行尾	存储已删除的文本以供粘贴
`Ctrl+U`	删除整行	存储已删除的文本以供粘贴
`Ctrl+Y`	粘贴已删除的文本	粘贴用 `Ctrl+K` 或 `Ctrl+U` 删除的文本

多行输入

快捷键	上下文	方法
`\` + `Enter`	在所有终端中工作	快速转义
`Ctrl+J`	多行的换行符	控制序列

配置

设置

完整参考

如何配置：允许全部操作，不需要每次确认

权限模式

Claude Code 支持多种权限模式来控制工具的批准方式。在您的设置文件中设置 defaultMode：

模式	描述
`default`	标准行为：在首次使用每个工具时提示权限
`acceptEdits`	自动接受会话的文件编辑权限
`plan`	Plan Mode：Claude 可以分析但不能修改文件或执行命令
`dontAsk`	自动拒绝工具，除非通过 `/permissions` 或 `permissions.allow` 规则预先批准
`bypassPermissions`	跳过所有权限提示（需要安全环境，请参见下面的警告）

自定义状态行

状态行是 Claude Code 底部的可自定义栏，可以运行你配置的任何 shell 脚本。它通过 stdin 接收 JSON 会话数据，并显示你的脚本打印的任何内容，为你提供一个持久的、一目了然的上下文使用情况、成本、git 状态或任何其他你想跟踪的内容的视图。

https://code.claude.com/docs/zh-CN/statusline

语音输入

Plugin组件

plugin 是一个自包含的组件目录，用于扩展 Claude Code 的自定义功能，包括 Skills、Agents、Hooks、MCP servers 和 LSP servers。

Skills

Skills 扩展了 Claude 能做的事情，skill是一个对外提供功能的“能力单元”，接收输入，执行逻辑，返回结果。

https://code.claude.com/docs/zh-CN/skills

Agents

Subagents 是处理特定类型任务的专门 AI 助手。每个 subagent 在自己的 context window 中运行，具有自定义系统提示、特定的工具访问权限和独立的权限。当 Claude 遇到与 subagent 描述相匹配的任务时，它会委托给该 subagent，该 subagent 独立工作并返回结果。

https://code.claude.com/docs/zh-CN/sub-agents

Hooks

Hooks 是用户定义的 shell 命令、HTTP 端点或 LLM 提示，在 Claude Code 生命周期中的特定点自动执行。

https://code.claude.com/docs/zh-CN/hooks-guide

https://code.claude.com/docs/zh-CN/hooks

MCP servers

Plugins 可以捆绑 Model Context Protocol (MCP) servers 以将 Claude Code 与外部工具和服务连接。

连接 MCP 服务器后，您可以要求 Claude Code：

从问题跟踪器实现功能：“添加 JIRA 问题 ENG-4521 中描述的功能，并在 GitHub 上创建 PR。”
分析监控数据：“检查 Sentry 和 Statsig 以检查 ENG-4521 中描述的功能的使用情况。”
查询数据库：“根据我们的 PostgreSQL 数据库，查找使用功能 ENG-4521 的 10 个随机用户的电子邮件。”
集成设计：“根据在 Slack 中发布的新 Figma 设计更新我们的标准电子邮件模板”
自动化工作流：“创建 Gmail 草稿，邀请这 10 个用户参加关于新功能的反馈会议。“

https://code.claude.com/docs/zh-CN/mcp

LSP servers

Plugins 可以提供Language Server Protocol (LSP) servers，在处理代码库时为 Claude 提供实时代码智能。

https://code.claude.com/docs/zh-CN/plugins-reference#lsp-servers

实用仓库

ccusage

https://github.com/ryoppippi/ccusage

A CLI tool for analyzing Claude Code/Codex CLI usage from local JSONL files.

opcode

https://github.com/winfunc/opcode

A powerful GUI app and Toolkit for Claude Code - Create custom agents, manage interactive Claude Code sessions, run secure background agents, and more.

everything-claude-code

https://github.com/affaan-m/everything-claude-code

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

superpowers

https://github.com/obra/superpowers

An agentic skills framework & software development methodology that works.

claude-code-tips

https://github.com/ykdojo/claude-code-tips

45 tips for getting the most out of Claude Code, from basics to advanced - includes a custom status line script, cutting the system prompt in half, using Gemini CLI as Claude Code’s minion, and Claude Code running itself in a container. Also includes the dx plugin.

skills

https://github.com/anthropics/skills

Public repository for Agent Skills.

最佳实践

编写有效的 CLAUDE.md

运行 /init 根据你的当前项目结构生成启动 CLAUDE.md 文件，然后随时间精化。

CLAUDE.md 是一个特殊文件，Claude 在每次对话开始时读取。包括 Bash 命令、代码风格和工作流规则。这给 Claude 提供了它无法从代码中推断的持久上下文。/init 命令分析你的代码库以检测构建系统、测试框架和代码模式，为你提供坚实的基础来精化。CLAUDE.md 文件没有必需的格式，但保持简短和易读。例如：

CLAUDE.md

1
2
3
4
5
6
7


# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md 在每个会话中加载，所以只包括广泛适用的东西。对于仅有时相关的域知识或工作流，改用 skills。Claude 按需加载它们，不会使每次对话都膨胀。保持简洁。对于每一行，问自己：“删除这个会导致 Claude 犯错吗？” 如果不会，删除它。膨胀的 CLAUDE.md 文件会导致 Claude 忽略你的实际指令！

✅ 包括	❌ 排除
Claude 无法猜测的 Bash 命令	Claude 可以通过读取代码弄清楚的任何东西
与默认值不同的代码风格规则	Claude 已经知道的标准语言约定
测试指令和首选测试运行器	详细的 API 文档（改为链接到文档）
存储库礼仪（分支命名、PR 约定）	经常变化的信息
特定于你的项目的架构决策	长解释或教程
开发者环境怪癖（必需的环境变量）	自明的实践，如”编写干净的代码”
常见陷阱或非显而易见的行为	文件逐个描述代码库

如果 Claude 继续做你不想要的事情，尽管有反对的规则，该文件可能太长，规则被遗漏了。如果 Claude 问你在 CLAUDE.md 中回答的问题，措辞可能不明确。像对待代码一样对待 CLAUDE.md：当事情出错时审查它，定期修剪它，并通过观察 Claude 的行为是否实际改变来测试更改。你可以通过添加强调（例如”IMPORTANT”或”YOU MUST”）来调整指令以改进遵守。将文件检入 git，以便你的团队可以贡献。该文件随时间增加价值。CLAUDE.md 文件可以使用 @path/to/import 语法导入其他文件：

CLAUDE.md

1
2
3
4
5


See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

你可以在多个位置放置 CLAUDE.md 文件：

主文件夹（~/.claude/CLAUDE.md）：适用于所有 Claude 会话
项目根目录（./CLAUDE.md）：检入 git 以与你的团队共享
父目录：对于 monorepos 有用，其中 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会自动拉入
子目录：当处理这些目录中的文件时，Claude 按需拉入子 CLAUDE.md 文件

有效沟通

你与 Claude Code 沟通的方式显著影响结果的质量。

提出代码库问题

问 Claude 你会问资深工程师的问题。

当加入新代码库时，使用 Claude Code 进行学习和探索。你可以问 Claude 你会问另一个工程师的相同类型的问题：

日志如何工作？
我如何创建新的 API 端点？
foo.rs 第 134 行的 async move { ... } 做什么？
CustomerOnboardingFlowImpl 处理哪些边界情况？
为什么这段代码在第 333 行调用 foo() 而不是 bar()？

以这种方式使用 Claude Code 是一个有效的入职工作流，改进了加入时间并减少了对其他工程师的负担。无需特殊提示：直接提问。

让 Claude 采访你【重点】

对于更大的功能，让 Claude 先采访你。从最小的提示开始，要求 Claude 使用 AskUserQuestion 工具采访你。

Claude 会问你可能还没有考虑过的东西，包括技术实现、UI/UX、边界情况和权衡。

1
2
3
4
5


I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

一旦规范完成，启动新会话来执行它。新会话有干净的 context，完全专注于实现，你有一个书面规范可以参考。

管理你的会话

对话是持久的和可逆的。利用这一点！

尽早且经常改正方向

一旦你注意到 Claude 偏离轨道，立即改正它。

最好的结果来自紧密的反馈循环。虽然 Claude 有时会在第一次尝试时完美地解决问题，但快速改正它通常会更快地产生更好的解决方案。

Esc：使用 Esc 键在中途停止 Claude。Context 被保留，所以你可以重定向。
Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 来打开 rewind 菜单并恢复之前的对话和代码状态，或从选定的消息进行总结。
"撤销那个"：让 Claude 恢复其更改。
/clear：在不相关的任务之间重置 context。长会话与无关的 context 可能会降低性能。

如果你在一个会话中对同一问题改正了 Claude 两次以上，context 就充满了失败的方法。运行 /clear 并使用更具体的提示重新开始，该提示包含你学到的东西。干净的会话与更好的提示几乎总是优于长会话与累积的改正。

积极管理 context【重点】

在不相关的任务之间频繁运行 /clear 来重置 context。

当你接近 context 限制时，Claude Code 会自动压缩对话历史，这保留了重要的代码和决策，同时释放空间。在长会话中，Claude 的 context window 可能会充满无关的对话、文件内容和命令。这可能会降低性能，有时会分散 Claude 的注意力。

在任务之间频繁使用 /clear 来完全重置 context window
当自动压缩触发时，Claude 总结最重要的东西，包括代码模式、文件状态和关键决策
为了更多控制，运行 /compact <instructions>，如 /compact Focus on the API changes
要仅压缩对话的一部分，使用 Esc + Esc 或 /rewind，选择消息检查点，并选择 从这里总结。这会压缩从该点开始的消息，同时保持早期 context 完整。
在 CLAUDE.md 中使用像 "When compacting, always preserve the full list of modified files and any test commands" 这样的指令来自定义压缩行为，以确保关键 context 在总结中存活
对于不需要留在 context 中的快速问题，使用 /btw。答案出现在可关闭的覆盖层中，永远不会进入对话历史，所以你可以检查细节而不增加 context。

使用 subagents 进行调查

使用 "use subagents to investigate X" 委托研究。它们在单独的 context 中探索，为实现保持你的主对话干净。

由于 context 是你的基本约束，subagents 是可用的最强大的工具之一。当 Claude 研究代码库时，它读取许多文件，所有这些都消耗你的 context。Subagents 在单独的 context windows 中运行并报告摘要：

1
2


Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

subagent 探索代码库、读取相关文件并报告发现，所有这些都不会使你的主对话混乱。你也可以在 Claude 实现某些东西后使用 subagents 进行验证：

1

use a subagent to review this code for edge cases

使用检查点进行 Rewind

Claude 进行的每个操作都会创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。

Claude 在更改前自动检查点。双击 Escape 或运行 /rewind 来打开 rewind 菜单。你可以仅恢复对话、仅恢复代码、恢复两者或从选定的消息进行总结。有关详细信息，请参阅 Checkpointing。与其仔细规划每一步，你可以告诉 Claude 尝试一些冒险的事情。如果不起作用，rewind 并尝试不同的方法。检查点在会话中持续，所以你可以关闭你的终端并稍后仍然 rewind。

检查点仅跟踪 Claude 进行的更改，不跟踪外部进程。这不是 git 的替代品。

恢复对话

运行 claude --continue 来继续你离开的地方，或 --resume 来从最近的会话中选择。

Claude Code 在本地保存对话。当任务跨越多个会话时，你不必重新解释 context：

1
2


claude --continue    # Resume the most recent conversation
claude --resume      # Select from recent conversations

使用 /rename 给会话起描述性名称，如 "oauth-migration" 或 "debugging-memory-leak"，以便你稍后可以找到它们。像对待分支一样对待会话：不同的工作流可以有单独的、持久的 context。

处理大型输入

处理大量代码或长指令时：

避免直接粘贴：Claude Code 可能难以处理非常长的粘贴内容
使用基于文件的工作流：将内容写入文件并要求 Claude 读取它
注意 VS Code 的限制：VS Code 终端特别容易截断长粘贴

常见错误和解决方法

1、API Error: The model has reached its context window limit.

达到上下文窗口限制。

使用/clear清空当前会话的上下文，但这会导致cc不再记得之前聊过什么，可能会影响它对项目的理解。

也可以先使用/compact压缩上下文，直到无法再压缩后，再使用/clear。

2、Unable to connect

检查 .claude.json 文件的 hasCompletedOnboarding 参数，该参数含义为是否已完成新手引导，配置为true时可跳过登录等环节。

MacOS & Linux 为 ~/.claude.json， Windows 为用户目录/.claude.json。

⚠️ 警告

该参数需要配置在最高层级。

1
2
3


 {  
 	"hasCompletedOnboarding": true
 }

3、Usage Policy

暂不清楚是何原因导致的，但是换种问法，就能正常继续对话。

附录

📝 备注

🔗https://zhuanlan.zhihu.com/p/2009744974980331332

📝 备注

🔗https://code.claude.com/docs/zh-CN/best-practices