Claude Code 使用指南¶

一份独立参考手册：快捷键、上下文管理、项目组织、与 VS Code 协作，以及背后的模型思维。

适用：已按 05 开发环境搭建安装好 Claude Code 的读者。关联：07 AI 编码与多 Agent 并行开发、附录 B 提示词与模板合集。

1. 先搞清楚：客户端与模型是两件事¶

很多人把「Claude Code」和「Claude 模型」混为一谈。实际上：

┌─────────────────────────────────────────────┐
│  Claude Code CLI（客户端 / Agent 框架）      │
│  - 读写文件                                  │
│  - 执行命令                                  │
│  - 调用 MCP / Skills / 子 Agent              │
│  - 管理上下文、权限、会话                    │
└───────────────────┬─────────────────────────┘
                    │ 兼容 Anthropic API 的请求
                    ▼
┌─────────────────────────────────────────────┐
│  后端模型（可替换）                          │
│  - Anthropic 模型                            │
│  - DeepSeek V4 Flash                         │
│  - 其他兼容 Anthropic API 的模型             │
└─────────────────────────────────────────────┘

关键认知：

Claude Code CLI 是「Agent 的手脚和工作流」，模型是「大脑」。
换模型不等于换工作流：CLAUDE.md、MCP、Skills、文件所有权、门禁都不变。
中国区的常见实践是：Claude Code CLI + DeepSeek V4 Flash。按当前路由，DeepSeek Pro 的流量也会走 Flash；Flash 的生成速度和能力都足够强。
模型的路由、名称、可用性会变化，最终以你本地 /models、claude mcp list 和厂商文档为准。

不要把「模型能力」当成全部。真正决定产能的是：模型能力 × 上下文质量 × 任务分解 × 反馈速度 × 验证强度 × 人的判断。

2. 安装与启动速查¶

# 官方安装脚本
curl -fsSL https://claude.ai/install.sh | bash

# 或 npm
sudo npm install -g @anthropic-ai/claude-code

# 验证
claude --version

进入项目目录再启动：

cd ~/projects/my-app
claude

常用启动方式：

命令	用途
`claude`	进入交互式会话
`claude "帮我解释这个项目"`	带初始任务启动
`claude -p "总结当前改动"`	非交互模式，输出结果后退出
`claude --continue`	继续最近一次会话
`claude --resume`	选择并恢复历史会话
`claude --dangerously-skip-permissions`	接 DeepSeek 做自动化时通常必须用：跳过每个子命令的确认。前提是 Git + 文件审查 + 隔离环境

完整安装、模型配置、代理、WSL 设置见 05 开发环境搭建。

3. 常用快捷键与命令¶

这是最常用的一张速查表：

操作	快捷键 / 命令	说明
初始化项目，生成 `CLAUDE.md`	`/init`	扫描项目结构，生成初始约定；生成后要人工精简
切换模式	`Shift + Tab`	在默认 / 自动接受 / Plan 等模式间切换（不同版本可能不同）
退出 Claude Code	两次 `Ctrl + C`	第一次中断当前生成，第二次退出
输入框换行	`Ctrl + J`	写多行提示词时使用
引用文件或目录	`@/path-to-file`、`@relative-path/folder/`	把文件/目录精确加入上下文
切换模型	`/models`	上下选择模型；建议架构/审查用强模型，机械任务用快模型
把长对话压成摘要省 token	`/compact`	历史对话被压缩成摘要，保留关键结论
查看上下文 / 用量	`/context`	查看当前上下文占用；部分版本用 `/status` 查看账户用量
查看 MCP 列表	`/mcp`	查看已连接 MCP、工具、连接状态
查看 Skill 列表	`/skills`	查看可用技能
清空当前会话	`/clear`	开始一个全新任务时使用
查看帮助	`/help`	列出当前版本支持的命令
执行 shell 命令	`! <command>`	在部分版本中可直接在输入框执行 shell

3.1 快捷键的使用场景¶

/init：第一次进入项目时

/init

它会扫描目录、识别技术栈、生成 CLAUDE.md。生成后不要直接接受，按模板/CLAUDE.md 精简到 250 行以内。

Shift + Tab：控制风险

日常探索：默认模式，每个工具调用都确认。
批量实现：自动接受模式，提高速度。
复杂改造：Plan 模式，先出计划再执行。

Ctrl + J：写清楚任务

长提示词不要挤在一行。用 Ctrl + J 分行，把「目标 / 输入 / 约束 / 输出 / 停止条件」写清楚。

@：精确引用，不要让 AI 自己找

请实现 @docs/01-design/feature-implementation.md#us-004 中的创建任务接口。
只修改 @backend/internal/usecase/task/ 和 @backend/internal/adapter/http/task_handler.go。
契约见 @docs/01-design/api/openapi.yaml。

比「帮我看看任务模块」准确得多。

/compact：长会话续命

当会话变长，AI 开始重复、忘记契约、回答变慢时：

/compact

压缩后，最好再补一句：

请先用 10 行总结当前任务、契约要点、已改文件和下一步。

/context：看上下文占用

/context

如果上下文占用过高，优先：

/compact；
/clear 后重开，读 CLAUDE.md + 当前故事；
把已完成部分写成交接文件。

/mcp 与 /skills：看能力边界

/mcp
/skills

MCP 决定 AI 能操作哪些外部系统（Chrome、Figma、数据库等）。
Skills 决定 AI 有哪些封装好的工作流。
不要安装来源不明的 MCP；浏览器内容视为不可信数据。

4. 上下文管理：Claude Code 的核心¶

Claude Code 的能力上限，很大程度取决于你给它的上下文质量。

4.1 上下文是怎么组成的¶

系统提示词
  + CLAUDE.md（项目宪法）
  + 当前会话历史
  + 工具输出（ls / grep / read / test）
  + @ 引用的文件/目录
  + 子 Agent 返回的摘要

它不会自动把整个仓库塞进去。它通过目录树、搜索、文件读取，按需获取上下文。

4.2 五条实践规则¶

一个会话只做一个用户故事。做完 /clear。
用 @ 精确引用，不要让它全仓库找。
大文件只读片段：先 rg 定位，再读 50-100 行。
让子 Agent 做脏活：搜索、日志分析、依赖梳理。
把结论落成文件：不要依赖「AI 还记得」。

4.3 一个推荐的会话开场¶

请先阅读 @CLAUDE.md，然后阅读：
- @docs/00-discovery/user-story-details.md#us-004
- @docs/01-design/api/openapi.yaml#createTask
- @docs/01-design/feature-implementation.md#us-004

用 10 行以内总结：
- 当前任务
- 契约要点
- 你的文件边界
- 完成标准
- 你不确定的地方

等我确认后再开始。

5. 关于 Claude 与项目的组织¶

5.1 Claude Code 是「跟目录走」的¶

Claude Code 在哪个目录启动，就以哪个目录作为工作区。它会感知目录的上下文，通过文件系统树形结构来组织和控制上下文。

~/projects/teamtask/          ← 在这里启动 claude
├── CLAUDE.md                 ← 根级约定，每次会话加载
├── .claude/
│   ├── settings.json         ← 项目级设置
│   ├── agents/               ← 自定义子 Agent
│   └── skills/               ← 项目技能
├── docs/                     ← 需求、设计、QA
├── backend/
└── frontend/

正确做法：

cd ~/projects/teamtask
claude

不建议：

cd ~            # 家目录太大，上下文会失控
claude

cd /            # 更不要
claude

5.2 `CLAUDE.md` 的层级¶

Claude Code 支持多层 CLAUDE.md：

根目录：项目级约定（技术栈、命令、禁令、DoD）。
子目录：该模块的额外约定（例如 backend/CLAUDE.md）。
用户级：~/.claude/CLAUDE.md，放个人偏好（谨慎使用，不要放项目密钥）。

建议：

根级 CLAUDE.md 控制在 250 行以内。
详细契约放 docs/，用链接引用。
子目录 CLAUDE.md 只写该模块的特殊规则。
不要把临时状态（当前做到哪）写进 CLAUDE.md，放 CSV 或交接文件。

5.3 多项目 / Monorepo¶

多项目：每个项目一个独立仓库，在各自根目录启动。
Monorepo：在仓库根目录启动，用 @ 引用具体包；或在包目录启动。
跨项目：不要让一个会话同时改两个仓库；用 worktree 或分开会话。

5.4 会话边界¶

场景	建议
一个用户故事	一个会话
一个 bug	一个会话
跨模块重构	一个会话，串行
多个功能并行	多 worktree + 多会话
只问一个问题	快速会话，问完退出

6. 模型切换策略¶

6.1 常用命令¶

/models

上下选择模型。也可以用环境变量固定默认模型（见 05 开发环境搭建）：

{
  "env": {
    "ANTHROPIC_MODEL": "<强模型>",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "<中模型>",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<快模型>",
    "CLAUDE_CODE_SUBAGENT_MODEL": "<快模型>"
  }
}

6.2 什么时候用强模型，什么时候用快模型¶

任务	建议
需求访谈、架构设计、契约设计	强模型
复杂 bug、并发问题、安全审查	强模型
代码审查、方案批判	强模型
普通功能实现	中/强模型
模板化 CRUD、格式转换	快模型
搜索、日志摘要、文件定位	快模型 + 子 Agent

6.3 中国区的实践¶

客户端：Claude Code CLI。
模型：DeepSeek V4 Flash。
当前路由下，DeepSeek Pro 的流量也会走 Flash；Flash 是 DeepSeek 当前最强的模型之一，生成速度和能力都很强。
相比 GLM / Kimi，体感上 Flash 的生成速度明显更快（以你的实际网络和版本为准）。

换模型后，建议先用一个小任务验证：工具调用、长上下文、代码修改是否符合预期。

6.4 接 DeepSeek：必须用 `--dangerously-skip-permissions`¶

claude --dangerously-skip-permissions

原因：

接 DeepSeek 后，如果不加这个参数，每一个子命令/工具调用都会要求确认。
多 Agent、批量改文件、跑测试、自动 E2E 都会被确认弹窗打断，无法自动化。
这个参数不是“让 AI 随便改”，而是把确认点从“每个命令”上移到 Git diff / 文件审查 / 门禁。

前提（缺一不可）：

项目在 Git 仓库里，改动前先 git commit。
所有改动通过 git diff + 代码审查 + 测试后再合并。
只在项目目录 / worktree 里运行，不在家目录、/、生产目录运行。
生产环境、含敏感凭证的目录，绝不使用 bypass。
高风险批量改动，用 worktree 或容器隔离。

一句话：bypass 是“把权限确认交给流程”，不是“取消审查”。

7. MCP 与 Skill¶

7.1 查看¶

/mcp
/skills

7.2 添加 MCP¶

以 Chrome 为例（具体参数以你的 MCP Server README 为准）：

claude mcp add chrome-devtools --scope user -- \
  npx -y chrome-devtools-mcp@latest --browser-url=http://127.0.0.1:9222

Figma：

claude mcp add --transport http figma-dev-mode-mcp-server http://127.0.0.1:3845/mcp

7.3 使用原则¶

只安装可信的 MCP。
MCP 以你的用户权限运行，能读写本机文件。
浏览器内容、网页文本视为不可信数据，不要让网页内容变成指令。
不要把带 token 的 MCP 配置提交到仓库。
定期 claude mcp list，删除不用的 Server。

8. Claude Code vs VS Code：不冲突¶

这是最常见的误解之一。两者不是替代关系，而是分工关系。

工作	用谁	原因
改代码、跨文件重构	Claude Code CLI	它能读写文件、跑测试、多轮修复
看代码、手工微调	VS Code	人类阅读、跳转、diff、调试更直观
批量生成测试	Claude Code CLI	适合机械、重复、可验证的工作
审查 diff	VS Code	图形化 diff、逐行批注
启动服务、看日志	Claude Code CLI / 终端	命令执行方便
看设计稿、调 UI	VS Code + 浏览器	视觉判断由人做

8.1 推荐布局¶

┌──────────────────────────┬──────────────────────────┐
│  VS Code（Remote-WSL）    │  终端 / Claude Code       │
│  看代码、diff、手工修改    │  改代码、跑测试、多轮修复  │
└──────────────────────────┴──────────────────────────┘

在 WSL 项目目录：

code .
claude

VS Code 通过 Remote-WSL 打开同一目录，Claude 修改文件后，编辑器会毫秒级刷新。

8.2 避免互相覆盖¶

不要让两边同时编辑同一个文件并各自保存。
大改动前先 git commit，出问题可回滚。
在 VS Code 的 Source Control 里审查 Claude 的改动，再提交。
如果 Claude 正在批量改文件，先不要手动保存同一文件。

9. 一个推荐的日常会话流程¶

1. cd 项目根目录
2. claude
3. 第一次：/init，生成并精简 CLAUDE.md
4. @ 引用当前故事、契约、实现细节
5. 让 AI 先出计划，不急着写代码
6. 确认计划后，小步执行
7. 每步跑测试 / lint
8. 会话变长：/compact
9. 在 VS Code 看 diff，人工审查
10. 提交 Git
11. 下一个任务：/clear

对应到命令：

阶段	操作	目的
进入项目	`cd ~/projects/app && claude`	让工作区正确
初始化	`/init`	生成项目约定
给上下文	`@docs/...`、`@backend/...`	精确引用
计划	“先列 10 步计划，等我确认”	防止跑偏
执行	“按计划执行，每步报告测试”	小步验证
压缩	`/compact`	控制上下文
审查	VS Code diff	人工判断
收尾	`git commit`	留下版本
切换	`/clear`	避免上下文污染

10. 权限与安全¶

10.1 权限模式¶

默认模式：每个工具调用需要确认，安全但慢。
自动接受 / bypass 模式：不确认就执行。接 DeepSeek 做自动化时通常必须用，否则每个子命令都要确认，无法自动化。
Plan 模式：先出计划，不改文件。

建议：

需求、设计、审查：默认模式。
接 DeepSeek 做自动化：使用 claude --dangerously-skip-permissions，但必须满足：
在项目目录 / worktree 内运行；
改动前先 git commit；
所有改动通过 git diff 审查；
测试通过再合并；
生产环境不使用 bypass。
永远不要在生产环境、含敏感凭证的目录使用 bypass 模式。

10.2 安全底线¶

不把密码、token、密钥贴进对话。
不让 AI 在日志里输出敏感信息。
生产操作必须人工批准。
大改动前先提交 Git。
不安装来源不明的 MCP。
不运行看不懂的 shell 命令。

11. 常见问题¶

Q1：Claude 好像不了解我的项目？¶

确认在项目根目录启动。
第一次运行 /init。
用 @ 引用关键文件。
检查 CLAUDE.md 是否存在、是否太旧。

Q2：会话越长越糊涂？¶

/context 看占用。
/compact 压缩。
或 /clear 后重开，先读 CLAUDE.md + 当前故事。
把已完成内容写成交接文件。

Q3：切换模型后行为变了？¶

强模型和快模型的能力不同。
任务书要写得更具体。
复杂任务不要用快模型。
切换后先让它复述任务和契约。

Q4：Claude 改的文件在 VS Code 里没刷新？¶

确认用 Remote-WSL 打开的是同一目录。
检查文件监听限制（见 05 的 inotify 设置）。
不要用 \\wsl.localhost\ 直接打开大项目。

Q5：`/mcp` 显示未连接？¶

看 claude mcp list。
手动运行 MCP Server 命令，看报错。
检查端口、token、代理。
重启 Claude Code。

Q6：`/context` 和 `/status` 有什么区别？¶

/context 看当前上下文占用。
/status 看账户、版本、用量等信息。
不同版本命令可能略有差异，以 /help 为准。

Q7：Claude 改了不该改的文件？¶

在任务书里写清楚「可改 / 禁改」。
用 git diff 检查。
大任务用 worktree 隔离。
发现越权，先还原，再补边界。

Q8：权限确认太频繁？¶

在项目 .claude/settings.json 里配置允许的命令。
不要把全局 bypass 当成日常设置。
高风险操作保留人工确认。

12. 思维：大模型的本质与本地 Agent 的工具¶

这一节是理解 Claude Code 为什么有效的底层视角。

12.1 大模型的本质：压缩的世界知识 + 个性化的输出¶

大模型本质上是对世界知识的高度压缩，再通过提示词进行个性化的条件生成。理论上，它也是一种「强化版的自动补全」。

这意味着：

它知道很多，但不一定知道你的项目。
它会生成「看起来合理」的内容，包括错误。
它的输出质量，很大程度取决于你给的条件（上下文、约束、例子）。

12.2 量变引起质变¶

当模型规模、训练数据、工具生态达到一定程度，它不再只是「聊天」，而变成了知识数据的工业母机：

能写代码；
能读文档；
能操作浏览器；
能调用命令行；
能通过多轮迭代修正自己。

12.3 Agent 是「手」¶

模型本身只能输出文本。Agent 给它装上了手：

模型（大脑）
  + 文件系统（读写）
  + 终端（执行命令）
  + 浏览器（CDP / Chrome MCP）
  + 测试框架（验证）
  + Git（版本与回滚）
  = 能交付的工程能力

Claude Code 就是这样一个 Agent 框架。

12.4 多轮迭代处理幻觉¶

单次生成一定会有幻觉。解决办法不是「换一个不会错的模型」，而是：

生成 → 编译 → 测试 → 集成 → E2E → 人工判断
  ↑                                      │
  └──────────── 反馈与修复 ←─────────────┘

编译器抓语法/类型错误；
单元测试抓业务规则；
集成测试抓数据库/事务；
契约测试抓前后端不一致；
E2E 抓真实用户流程；
人做最终判断。

12.5 为什么编程是 Agent 最好的战场¶

代码是可执行的，对错可以被验证。
编译器、测试、lint 提供快速反馈。
Git 提供版本和回滚。
需求可以拆成小步，逐步验收。
价值高、重复多、适合自动化。

12.6 五个直接推论¶

不要指望它记住：给它文件、给它契约。
不要指望它永远正确：用编译器和测试证伪。
不要指望一次成功：小步、多轮、可回滚。
不要指望它替你做判断：目标、边界、审美、上线由人定。
瓶颈会从「写」转移到「看」：所以要让 AI 生成证据和人性化报告。

这正是本教程反复强调的：

模型能力 × 上下文质量 × 任务分解 × 反馈速度 × 验证强度 × 人的判断

13. 一页速查卡¶

进入项目：      cd ~/projects/app && claude
接 DeepSeek：   claude --dangerously-skip-permissions
初始化：        /init
看上下文：      /context
压缩上下文：    /compact
清空会话：      /clear
引用文件：      @path/to/file
引用目录：      @path/to/folder/
切换模型：      /models
查看 MCP：      /mcp
查看 Skill：    /skills
换行：          Ctrl+J
切模式：        Shift+Tab
退出：          两次 Ctrl+C

三条铁律：
1. 在项目根目录启动。
2. 一个会话只做一个故事。
3. 改代码用 Claude，看代码用 VS Code。

接 DeepSeek 做自动化时，必须用 claude --dangerously-skip-permissions；否则每个子命令都要确认，无法自动化。前提：Git 可回滚 + 文件审查 + 隔离环境。

14. 与教程其他章节的关系¶

章节	关系
05 开发环境搭建	安装、WSL、Chrome、MCP、模型配置
07 AI 编码与多 Agent 并行开发	如何把 Claude Code 用在多 Agent 并行开发
08 质量保证与 Word 验收报告	如何用 Chrome MCP 做 E2E、生成 Word 报告
附录 A Chrome MCP / CDP 实战手册	浏览器自动化的具体工具和 JS 断言
附录 B 提示词与模板合集	各阶段可直接复制的提示词
模板/CLAUDE.md	项目宪法模板