Claude Code 使用指南

面向第一次使用 Claude Code、希望稳定完成真实开发任务的用户。
更新日期：2026-07-13

1. Claude Code 是什么

Claude Code 是运行在终端和 IDE 中的智能编程代理。它不仅能回答问题，还可以读取项目文件、搜索代码、执行命令、修改文件、运行测试并协助完成 Git 工作流。

它适合：

• 理解陌生项目和定位代码
• 修复 Bug、实现功能、重构代码
• 编写测试、文档和脚本
• 分析日志、构建失败与测试失败
• 查看 Git diff、审查改动和整理提交

Claude Code 会根据任务按需读取文件，一般不需要把整个项目手动粘贴进对话。

2. 安装与启动

macOS、Linux、WSL（官方推荐的原生安装）

curl -fsSL https://claude.ai/install.sh | bash

macOS 也可以使用 Homebrew：

brew install --cask claude-code

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

检查安装

claude --version
claude doctor

进入项目目录并启动：

cd /path/to/project
claude

首次启动时按照浏览器提示登录。原生安装通常会后台自动更新；也可以手动运行：

claude update

参考：官方安装文档

3. 推荐的基本工作流

第一步：先让 Claude 理解项目

请先阅读项目结构和相关文档，说明：
1. 项目采用的技术栈
2. 主要入口和核心模块
3. 构建、测试、代码检查命令
4. 与当前任务最相关的文件
暂时不要修改代码。

第二步：复杂任务先规划

/plan 修复登录后偶发跳回登录页的问题

或者直接说明约束：

先分析原因并给出实施计划，不要修改文件。列出风险、涉及文件和验证方法。

第三步：明确授权实施

按照刚才的计划实施。保持改动范围最小，不修改无关文件。完成后运行相关测试。

第四步：检查结果

请检查当前改动：
- 是否真正解决根因
- 是否引入回归或安全问题
- 是否遗漏边界情况
- 测试是否覆盖关键路径

可以使用：

/diff

最后仍应自己查看 git diff、测试结果和即将提交的文件。

4. 如何写好任务提示

一个有效的任务说明通常包含五项：

1. 目标：最终需要实现什么。
2. 现象：当前发生了什么，期望是什么。
3. 范围：允许修改哪些模块，不要碰哪些内容。
4. 约束：兼容性、技术栈、代码风格、安全要求。
5. 验收：用什么测试或可观察结果证明完成。

示例：

修复用户重复点击“提交”时产生两笔订单的问题。

要求：
- 先定位根因，再修改代码
- 不改变现有 API 响应格式
- 后端必须保证幂等，不能只禁用前端按钮
- 添加并发请求测试
- 完成后运行订单模块测试，并总结修改文件和验证结果

避免只说“优化一下”“帮我改好”。任务越可验证，结果通常越稳定。

5. CLAUDE.md：项目长期说明

CLAUDE.md 用于保存每次会话都应该知道的项目规则。第一次配置项目时可以运行：

/init

常见位置：

范围	位置	用途
用户级	~/.claude/CLAUDE.md	所有项目通用的个人习惯
项目级	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队共享的项目规则
项目本地	./CLAUDE.local.md	不提交到 Git 的个人项目配置

推荐内容：

# 项目概况
- 前端使用 React + TypeScript，后端使用 FastAPI。
- API 路由位于 `backend/api/`。

# 常用命令
- 安装依赖：`pnpm install`
- 单元测试：`pnpm test`
- 类型检查：`pnpm typecheck`

# 修改约束
- 不直接修改生成文件。
- 数据库结构变更必须提供迁移脚本。
- 修复 Bug 时添加对应的回归测试。

# 完成标准
- 运行与改动相关的测试。
- 最终说明修改文件、验证结果和遗留风险。

查看当前加载的说明和记忆：

/memory

注意：

• 规则应具体、简短、无冲突。
• 官方建议每个 CLAUDE.md 尽量控制在 200 行以内。
• @path/to/file 可以导入其他说明文件，但导入仍会占用上下文。
• CLAUDE.md 是行为指导，不是强制安全策略；真正禁止某些命令应使用权限规则。

参考：项目记忆与 CLAUDE.md

6. 上下文窗口与“100% context used”

上下文窗口是 Claude 当前能够同时参考的信息总量，包括：

• 对话历史
• 已读取的文件
• 命令和工具输出
• CLAUDE.md 与自动记忆
• MCP 工具说明、技能和系统指令

状态栏显示：

100% context used

表示当前会话的上下文窗口已经用满或因取整接近用满。它不是账户使用额度，也不是电脑内存或磁盘占用。

查看是谁占用了上下文

/context

继续同一任务：压缩上下文

/compact 只保留任务目标、关键决策、已修改文件、测试结果和剩余工作

/compact 会把历史替换为摘要。项目根目录的 CLAUDE.md 和不限定路径的规则会从磁盘重新注入，因此会读取其最新内容。

需要注意：

• 子目录中的嵌套 CLAUDE.md 会在 Claude 再次读取该子目录文件时重新加载。
• 带 paths: 条件的规则也要等匹配文件再次被读取。
• 只在聊天中口头说过的规则可能在压缩时丢失；重要规则应写入项目根目录的 CLAUDE.md。

切换无关任务：清空上下文

/clear

这会开启空白会话，但之前的会话仍然保存，可以通过 /resume 找回。新会话会重新加载项目说明。

上下文已满时的稳妥交接流程

先让当前会话创建精简交接文档：

请把当前任务整理到 HANDOFF.md，内容仅包括：
1. 任务目标和验收标准
2. 已确认的根因与关键决策
3. 已修改文件及修改内容
4. 已运行的测试及结果
5. 当前阻塞和下一步操作
不要复制完整聊天记录。

然后执行：

/clear

在新会话输入：

请读取 @HANDOFF.md 和最新的 @CLAUDE.md，检查当前 git diff，然后继续完成剩余工作。

这种方式比导入完整历史更节省上下文，也更不容易携带已经失败的思路。

如果 /compact 因窗口完全满而失败，可按两次 Esc 打开回退界面，退回几条消息后重试；仍失败则使用 /clear。

参考：上下文窗口、错误处理

7. 会话管理

操作	命令	说明
继续当前目录最近会话	claude --continue	从终端继续最近会话
选择历史会话	claude --resume 或 /resume	打开会话选择器
命名当前会话	/rename 登录问题排查	方便以后查找
清空当前上下文	/clear	原会话仍然保留
从当前对话创建副本	/branch 新方案	原会话不变，切换到副本
导出可读记录	/export 文件名.txt	导出对话文本

恢复与分支的区别：

• /resume：继续原来的会话。
• /branch：复制当前历史，创建新的独立会话。
• /clear：创建不含聊天历史的空白会话。

会话默认保存在：

~/.claude/projects/<project>/<session-id>.jsonl

不要依赖 JSONL 的内部结构编写长期脚本；官方建议使用 /export 或正式的脚本接口。

参考：会话管理

8. 权限模式

按 Shift+Tab 可以在可用权限模式间切换，也可以使用启动参数。

模式	适合场景
default	日常使用，关键操作逐项确认
acceptEdits	自动接受工作目录内的编辑，事后统一审查 diff
plan	只分析和规划，不修改源文件
dontAsk	未预先允许的操作直接拒绝
bypassPermissions	跳过绝大多数确认，只适合隔离容器或虚拟机

启动时指定：

claude --permission-mode plan
claude --permission-mode acceptEdits

管理允许、询问和拒绝规则：

/permissions

不建议在真实工作目录或包含重要凭据的环境中开启 bypassPermissions。即使使用自动模式，也应检查 Git diff、测试和外部副作用。

参考：权限配置、权限模式

9. 常用命令速查

命令	用途
/help	查看当前版本可用命令
/init	初始化或改进项目 CLAUDE.md
/memory	查看和编辑说明、规则及自动记忆
/context	查看上下文占用
/compact [要求]	压缩对话并指定需要保留的信息
/clear	开启空白会话
/resume	选择历史会话
/rename 名称	命名当前会话
/branch 名称	从当前对话创建独立副本
/plan [任务]	进入只读规划模式
/diff	查看当前改动
/rewind	回到之前的对话或代码检查点
/model	选择模型
/permissions	管理工具权限
/mcp	查看和管理 MCP 连接
/doctor	检查安装、配置和上下文问题
/export	导出当前会话
/usage	查看使用量和活动统计
/exit	退出 Claude Code

命令会随版本和套餐变化；以本机 /help 的结果为准。完整列表见官方命令参考。

10. 中断、回退与恢复

• 按一次 Esc：中断 Claude 当前操作，上下文仍保留。
• 按两次 Esc 或运行 /rewind：选择恢复对话、代码或两者。
• 输入“撤销刚才的修改”：让 Claude 主动回退自己的更改。
• Git 仍然是最终保障：重要工作应使用分支并及时提交。

检查点主要追踪 Claude 自己执行的编辑，不能代替 Git，也不一定覆盖其他程序对文件的修改。

11. 常见问题

修改 CLAUDE.md 后为什么没有立即生效？

会话中途修改项目说明，不一定立即替换已经加载的版本。运行：

/compact

或：

/clear

项目根目录的最新 CLAUDE.md 会重新加载。随后用 /memory 检查加载情况。

Claude 总是不遵守某条规则怎么办？

1. 确认 /memory 中确实加载了对应文件。
2. 删除冲突或过时的规则。
3. 把模糊要求改成可验证的具体要求。
4. 将最重要的规则放进项目根目录 CLAUDE.md。
5. 强制安全限制使用 /permissions，不要只依赖文字提示。

Claude 读取了太多无关内容怎么办？

• 使用 /context 找出主要占用项。
• 新任务使用 /clear。
• 让 Claude 精确读取相关文件，不要一次导入大目录或长日志。
• 禁用暂时不用的 MCP 服务。
• 缩短 CLAUDE.md，将特定规则改为按路径加载。
• 大量调查工作可放到独立子代理，主会话只接收摘要。

Claude 一直走错方向怎么办？

尽早按 Esc 中断并指出具体错误。如果同一问题连续纠正多次，建议把已经确认的信息写入 HANDOFF.md 或任务规格文件，然后 /clear 后用更准确的提示重新开始。

会话找不到怎么办？

会话通常按项目目录保存。在 /resume 选择器中：

• Ctrl+W：扩大到当前仓库的所有 worktree。
• Ctrl+A：扩大到本机所有项目。

养成使用 /rename 命名重要会话的习惯。

12. 推荐习惯

1. 一个会话尽量只处理一个明确任务。
2. 复杂任务先规划，再授权修改。
3. 把长期规则放入精简的 CLAUDE.md。
4. 把阶段成果写入 SPEC.md、PLAN.md 或 HANDOFF.md，不要只依赖聊天历史。
5. 上下文接近满载时主动 /compact，不要等到完全用尽。
6. 切换无关任务时使用 /clear。
7. 及时中断错误方向，不要让错误尝试持续堆积。
8. 每次交付前检查 diff、运行测试并确认没有无关修改。
9. 使用 Git 分支和提交保护重要工作。
10. 定期运行 claude doctor 检查安装、配置和上下文负担。

官方资料

• Claude Code 快速入门
• 安装与更新
• 最佳实践
• 命令参考
• 会话管理
• 上下文窗口
• CLAUDE.md 与记忆
• 权限配置