Claude Code 使用教程

这篇笔记的目标是把 Claude Code 放回一个准确的位置里理解清楚，再给出一套可以直接上手的使用路径。重点不只是“命令怎么敲”，而是它到底解决什么问题、适合放在什么开发环节、与补全型 AI 工具的边界在哪里。

正文会先解释 Claude Code 的产品定位和能力模型，再解释它真正依赖的配置体系，包括 CLAUDE.md、.claude/ 目录、规则、技能、hooks、agents 的职责分工，然后再展开终端与 VS Code 两条使用路径，最后补充高频工作流、权限控制、常见误区与工程化实践建议。这样读完之后，不只是会敲几个命令，还能真正理解 Claude Code 在项目里是怎么长期工作的。

官方文档：Claude Code Overview 、 Claude Code Quickstart 、 Claude Code Common Workflows

配置与记忆：How Claude remembers your project 、 Explore the .claude directory 、 Claude Code settings

IDE 集成：Use Claude Code in VS Code

扩展机制：Extend Claude Code 、 Automate actions with hooks 、 Create custom subagents

社区实践：multica-ai/andrej-karpathy-skills 、 GitHub 10万星 CLAUDE.md 解析

常见问题：Claude Code user FAQ

[TOC]

一、Claude Code 是什么

Claude Code 可以概括为一类 agentic coding tool，也就是“代理式编码工具”。

它和传统聊天框最大的区别，不在于模型本身，而在于它拥有对开发环境的直接操作能力：

• 读取代码仓库
• 搜索和理解跨文件上下文
• 编辑多个文件
• 运行命令
• 调用开发工具链
• 在终端、IDE、桌面应用和浏览器中持续工作

这意味着 Claude Code 不是只负责“回答问题”，而是可以沿着“理解任务 -> 制定方案 -> 修改代码 -> 执行验证 -> 继续修正”这条链路完成真实开发动作。

它更像代理，而不是补全器

很多人第一次接触 Claude Code 时，容易把它和 GitHub Copilot、Cursor Tab 这类补全能力放在同一层比较，但二者的工作单位并不一样。

如果只用一句话概括：

补全型工具更像“续写当前代码”，Claude Code 更像“接手一个开发任务并在仓库里推进它”。

它解决的核心问题

在真实项目里，很多低效并不是“不会写某一行代码”，而是：

• 代码分散在多个文件，定位成本很高
• 修改点涉及配置、实现、测试、文档多个层面
• 排错时需要一边看代码，一边跑命令，一边验证输出
• 开发任务往往不是“写一个函数”，而是“把一个功能真正落地”

Claude Code 的价值正好落在这类跨文件、跨步骤、带验证的任务上。

例如下面这些任务，通常都比较适合交给它：

• “解释这个仓库的结构和主链路”
• “定位登录失败的原因，并跑测试验证修复”
• “为某个模块补测试，并修复测试暴露出的失败点”
• “把旧写法重构成新 API，同时保证行为不变”
• “根据当前变更生成提交说明或 PR 描述”

它不是什么

理解边界比理解能力更重要。Claude Code 并不是下面这些东西：

• 不是无条件可靠的自动程序员，输出仍然需要审查
• 不是架构责任的替代者，需求边界和技术决策仍要人工把关
• 不是对所有命令都能盲目执行的脚本机器人，权限和环境限制始终存在
• 不是“描述一句话就一定能一次成功”的黑箱系统，复杂任务仍然需要分阶段推进

因此，把 Claude Code 当成“有执行能力的开发代理”，通常比把它当成“全自动写代码工具”更符合实际。

二、Claude Code 适合放在开发流程的哪一层

如果把开发过程拆成几个层次，Claude Code 主要覆盖的是“执行层”和“验证层”。

graph TB
    A[需求与边界] --> B[方案与拆解]
    B --> C[代码实现]
    C --> D[命令执行]
    D --> E[测试与验证]
    E --> F[提交与整理]

    U[人工主导] --> A
    U --> B
    CC[Claude Code 协助或接手] --> C
    CC --> D
    CC --> E
    CC --> F

在这个分层里：

• 需求是否正确，仍然主要由人来定义
• 方案是否合理，通常由人主导、工具辅助
• 实现、修改、执行、验证、整理，是 Claude Code 最容易产生价值的环节

这也是为什么它在“修 Bug、补测试、读仓库、做重构”上表现通常比“凭空设计一个完整系统”更稳定。

最适合 Claude Code 的任务特征

下面这几类任务，命中率通常比较高：

一个常见误区

很多失败体验，并不是工具能力不足，而是任务表达方式本身就不适合代理执行。

例如下面两种输入，效果通常会差很多：

1
帮我把这个项目优化一下

1
先分析订单模块的慢查询来源，给出 2 到 3 种修复方案；确认后只修改 SQL 和索引相关代码，并执行现有测试验证没有回归

第二种表达之所以更有效，不是因为“提示词更花哨”，而是因为它补齐了代理最需要的信息：

• 分析对象
• 任务目标
• 输出形式
• 变更边界
• 验证要求

三、真正开始使用前，先理解它会读哪些文件

如果只会 claude、/plan、/compact 这些命令，其实还没有真正学会 Claude Code。

Claude Code 真正和普通聊天工具拉开差距的地方，不只是它能读代码、改文件、跑命令，而是它有一整套 跨会话、跨项目、可沉淀的配置与记忆体系。这一层如果不理解，后面几乎所有“为什么它这次记得、下次又忘了”“为什么这个规则总不生效”“为什么还要建 .claude/ 目录”的问题，都会解释不通。

Claude Code 不是只靠当前对话工作

每次会话开始时，Claude Code 的上下文窗口是新的，但它并不是从完全空白开始。官方文档里，长期知识主要来自两类来源：

有一个很重要的边界必须先说清楚：

CLAUDE.md 和 auto memory 都是“注入上下文”，不是强制执行器。

这意味着：

• 它们负责提高 Claude 的一致性
• 它们不能替代权限控制
• 如果要“无论如何都不允许做某事”，应该考虑 hooks 或权限规则，而不是只写一句自然语言提醒

CLAUDE.md 到底是干什么的

可以把 CLAUDE.md 理解成“项目给 Claude 的长期工作说明书”。

它最适合放的是那些本来每次开新会话都要重新解释一遍的东西，例如：

• 项目使用什么构建、测试、格式化命令
• 代码组织方式和目录约束
• 常见工程约定，例如导出方式、测试位置、接口返回结构
• 某些总是需要遵守的工作流，例如“提交前必须跑测试”

官方文档对 CLAUDE.md 的建议很明确：

• 尽量控制在 200 行以内
• 只放“每次会话都应该知道”的事实
• 太大的内容不要继续堆在里面，应拆到 rules 或 skills

一个最小可用的 CLAUDE.md，通常长这样：

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

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Stack
- TypeScript with strict mode
- React 19, functional components only

## Rules
- Named exports, never default exports
- Tests live next to source: `foo.ts` -> `foo.test.ts`
- All API routes return `{ data, error }` shape

这段示例的价值不在于语法，而在于它说明了 CLAUDE.md 的写法原则：

• 写命令，不写口号
• 写结构事实，不写抽象愿景
• 写可验证规则，不写模糊建议

社区里使用度较高的一类约定：Karpathy 风格 CLAUDE.md

除了官方文档给出的 CLAUDE.md 机制之外，社区里传播度很高的一类实践，是把一组 行为约束 直接写进 CLAUDE.md，用来抑制 AI 编码里最常见的四类失控行为。

multica-ai/andrej-karpathy-skills 这类仓库，本质上就在做这件事：不是再加一堆工具，而是把“Claude 应该如何行动”的约定前置到提示层。wikimind 的解读文章则把这套思路总结成一句更直白的话：核心不是教 AI 更多技巧，而是让它先学会守规矩。

这类约定之所以传播快，是因为它击中的不是某个语言或框架问题，而是代理式编码里非常普遍的四个失控点：

如果拆开看，这四条规则分别在解决不同层的问题。

Think Before Coding 的重点，不是“多想一会儿”，而是要求代理把假设显式说出来。在需求模糊、接口语义不清、边界条件未定义时，先提出多种解释，再请求确认，而不是静默选择一种理解并一路做下去。

Simplicity First 在工程上非常重要，因为很多 AI 编码失败，并不是代码写不出来，而是写得过头。需求只要求局部改动，却顺手补了一层配置抽象、可扩展接口、通用框架和未来场景，这一类“看起来高级、实际上增加维护成本”的产物，正是这条规则要压制的对象。

Surgical Changes 更像对 diff 的纪律要求。它要求每一行改动都能追溯到当前任务，而不是把“顺手优化”混进同一轮提交。这一点和前文提到的“只看 diff，不看总结”是直接一致的。

Goal-Driven Execution 则非常适合 Claude Code 这类代理工具。因为这类工具真正擅长的不是照着口头命令机械执行，而是围绕一个可验证目标迭代闭环。例如把“修 bug”改写成“先写一个能复现 bug 的测试，再让它通过”，就能明显提升代理的自主闭环能力。

这类约定为什么适合写进 CLAUDE.md

这组规则的特点是：它们不是某次任务临时才会用到，而是几乎每次编码都值得默认生效。

因此它们更适合作为 CLAUDE.md 里的长期行为约束，而不是零散地写在某次对话里。可以概括为：

• 它不是单次 workflow，更像常驻行为边界
• 它不是项目特有知识，而是代理执行纪律
• 它和项目自己的构建命令、目录结构、测试约定可以并存

这也是为什么这类仓库通常提供两种集成方式：

• 直接把这套规则合并进项目 CLAUDE.md
• 通过插件或 skills 方式安装，再与项目自身规则叠加

社区版本中文译文：可直接贴进 CLAUDE.md

如果目标就是“找一段社区里已经被大量使用的行为约束，直接放进项目 CLAUDE.md”，那比起再造一份加工过的模板，更直接的做法确实是把那份高传播度内容直接贴进来。

下面这段是按社区流传版本整理后的中文译文，定位就是：

• 可直接复制
• 适合作为项目 CLAUDE.md 中的行为约束段落
• 用来约束代理如何思考、如何改动、如何验证

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
# CLAUDE.md

降低 AI 写代码常见错误的行为准则。可与项目专属规则合并使用。

**权衡：** 这些规则偏向“谨慎”而非“速度”。琐碎任务，请自行判断。

## 动手前先想清楚（Think Before Coding）

**不假设、不藏糊涂、把权衡摊开来说。**

实现之前：
- 把假设明确说出来，不确定就问。
- 有多种理解时，把所有可能列出来，不要擅自挑一个就直接开始做。
- 如果有更简单的方案，说出来；必要时明确指出当前方案过度复杂。
- 哪里不清楚，就停下来，指出困惑点，再继续。

## 最小化原则（Simplicity First）

**只写解决问题的最小代码，不要任何“以防万一”。**

- 不写需求里没要求的功能。
- 不为一次性代码引入抽象。
- 不增加未要求的“灵活性”或“可配置性”。
- 不为不可能发生的场景补无意义的错误处理。
- 如果写了 200 行而 50 行就够，应该重写。

判断标准：
- 如果资深工程师会认为这段实现过度复杂，那它通常就是过度复杂。

## 外科手术式改动（Surgical Changes）

**只动该动的，只清自己的改动产生的问题。**

修改现有代码时：
- 不顺手改周边代码、注释或格式。
- 不重构没有坏的东西。
- 尽量贴合现有风格，即使个人更偏好另一种写法。
- 发现无关死代码时，可以指出，但不要在当前任务里顺手删除。

如果当前改动制造了“孤儿代码”：
- 删除因为本次改动而失去用途的 import、变量、函数。
- 不删除改动前就已经存在的死代码，除非任务明确要求。

判断标准：
- 每一行改动都应能追溯到当前任务。

## 目标驱动执行（Goal-Driven Execution）

**先定义成功标准，再循环到验证通过为止。**

把任务改写成可验证目标：
- “加个校验” -> “先写无效输入的测试，再让它通过”
- “修这个 bug” -> “先写能复现 bug 的测试，再让它通过”
- “重构 X” -> “确保重构前后测试都通过”

多步任务先写简短计划：
1. [步骤] -> 验证：[检查项]
2. [步骤] -> 验证：[检查项]
3. [步骤] -> 验证：[检查项]

强的成功标准会让代理形成闭环；
弱的成功标准，例如“让它跑起来”，通常只会带来更多来回确认。

这段内容更适合被理解成 行为纪律基线，而不是项目完整模板。它最适合解决的是“代理应该怎么行动”，而不是“项目本身长什么样”。

怎样把这段译文和项目规则拼起来

更稳妥的做法通常不是只保留这一段，而是把它和项目自己的事实性规则并排放在同一个 CLAUDE.md 里。

可以概括为两层：

• 上层是行为纪律：先澄清、少过度设计、只做必要改动、必须可验证
• 下层是项目事实：构建命令、测试命令、目录结构、架构边界、接口约定

这样组合的好处是：

• 社区通用纪律和项目专属事实不会混在一起
• Claude Code 既知道“自己该怎么行动”，也知道“这个仓库到底怎么工作”
• 后续继续维护时，能明确区分哪些是通用规则，哪些是本项目私有知识

使用这类约定时的边界

这类社区实践很有价值，但它仍然不是官方唯一标准，也不适合不加判断地原样照搬。

至少有三个边界需要单独说明：

• 它偏向谨慎而不是速度，对极小任务可能显得偏重
• 它解决的是代理行为纪律，不替代项目级事实配置
• 它仍然属于上下文约束，不是权限系统；真正必须强制发生的动作，仍应考虑 hooks 或权限规则

因此，更准确的定位是：

Karpathy 风格 CLAUDE.md 不是 Claude Code 的官方默认模板，但它已经成为当前社区里使用度较高的一类行为约定，尤其适合用来约束“先澄清、少过度设计、只做必要改动、必须可验证”这几件事。

CLAUDE.md 的作用域不是只有一个

很多人会以为 CLAUDE.md 只有项目根目录那一个文件，但官方文档里它实际上有多个作用域。

这里最容易忽略的两个点是：

• CLAUDE.local.md 应该加入 .gitignore
• Claude Code 会沿当前工作目录向上查找 CLAUDE.md，而不是只看当前文件夹

这也解释了为什么在 monorepo 或多层目录里，Claude 的规则有时会带着“父目录的习惯”。

.claude/ 目录结构到底装什么

如果 CLAUDE.md 是“总说明书”，那 .claude/ 目录就是“细分能力和项目配置的落点”。

根据官方目录文档，典型结构可以概括为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── testing.md
    │   └── api-design.md
    ├── skills/
    │   └── deploy/
    │       └── SKILL.md
    ├── commands/
    │   └── fix-issue.md
    ├── agents/
    │   └── code-reviewer.md
    ├── workflows/
    │   └── batch-refactor.js
    └── agent-memory/
        └── reviewer/
            └── MEMORY.md

这棵树的意义，是把“什么应该一直加载”“什么只在需要时加载”“什么属于执行自动化”“什么属于并行代理”拆开。

这些文件各自负责什么

真正重要的不是记住所有文件名，而是记住分工边界：

• 总是要知道的，放 CLAUDE.md
• 局部目录或专题规则，放 rules
• 只有某些任务才需要的知识或流程，放 skills
• 一定要自动发生的动作，放 hooks
• 需要隔离上下文或并行处理的角色，放 agents
• 需要访问外部系统，放 MCP

settings.json、hooks、rules、skills、agents 之间怎么分工

这几个概念最容易混在一起。可以直接用下面这张表来区分：

其中最容易误用的是 CLAUDE.md 和 skills：

• 如果内容是“Claude 每次都应该知道”，放 CLAUDE.md
• 如果内容是“只有某种任务才需要”，放 skills

例如：

• “本项目用 pnpm，提交前必须跑 pnpm test”适合放 CLAUDE.md
• “发布到预发环境的完整流程”更适合做成 /deploy-staging 之类的 skill

Hooks 为什么重要

很多人会把所有规则都写进 CLAUDE.md，然后期待 Claude 每次都完全遵守。但官方文档明确区分了：

• CLAUDE.md 是上下文
• hooks 是确定性自动化

这意味着两者解决的问题不同：

• “尽量按这个规范做”适合写进 CLAUDE.md
• “每次编辑后都自动跑格式化”更适合用 hooks
• “永远不允许改某些受保护文件”更适合用 hooks 或权限规则

如果一个动作必须稳定发生，而不是希望模型“最好记得”，那就应该优先考虑 hooks。

学 Claude Code，真正应该学到什么

到这里为止，真正应该建立起来的不是“我会敲几个命令”，而是下面这套认识：

1. Claude Code 不是一次性聊天工具，而是带持久配置的开发代理
2. CLAUDE.md 负责长期上下文，auto memory 负责自动积累经验
3. .claude/ 目录是项目级扩展能力的承载点
4. rules、skills、hooks、agents、MCP 解决的是不同层的问题
5. 命令只是入口，真正决定体验的是这套配置如何被组织

如果没有这一层，前面的命令就只是“会用一点终端交互”；有了这一层，才开始真正进入 Claude Code 的工程化使用。

四、安装与登录

官方文档当前把 Native Install 作为推荐安装方式，macOS、Linux、WSL 可以直接使用安装脚本。

终端 CLI 安装

1
2
3
4
5
6
7
8
9
10
11
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

几个安装层面的关键信息需要先看清楚：

• 原生安装方式是官方推荐路径
• 原生安装会自动后台更新
• Homebrew 和 WinGet 安装不会自动更新，需要手动升级
• Homebrew 提供 claude-code 和 claude-code@latest 两个渠道，前者更稳定，后者跟进更快

首次登录

安装完成后，在项目目录中启动：

1
2
cd your-project
claude

首次启动时会进入登录流程，浏览器授权完成后，本地会保存凭据，后续通常不需要重复登录。

如果需要重新登录或切换账号，可以在会话里执行：

1
/login

支持的账号来源

根据官方文档，Claude Code 可以通过多种账号体系使用：

• Claude Pro / Max / Team / Enterprise
• Claude Console
• 受支持的第三方云提供方
• 组织自建的 gateway

因此它并不只绑定一种使用方式，但首次上手时，最简单的路径仍然是直接使用官方账号登录。

常见安装问题

五、第一次上手：从终端开始

终端是理解 Claude Code 工作方式最直接的入口，因为它把“读代码、改文件、跑命令、继续对话”放在同一条链路里。

一个最小上手路径

第一次进入一个项目时，可以按下面的顺序走：

1. 进入仓库根目录后执行 claude
2. 先问项目级问题，而不是立刻要求改代码
3. 确认它对代码结构的理解是否可靠
4. 再给一个可验证的小任务
5. 最后让它运行测试或命令验证结果

例如可以从下面这些问题开始：

1
这个项目是干什么的？

1
它使用了哪些核心技术栈？

1
主入口在哪里？

1
解释一下目录结构和主要模块边界

这一步的目的不是“考模型”，而是先让它建立代码库上下文，同时让使用者判断它对仓库的理解是否准确。

第一次让它改代码

在确认它能读懂项目后，再给一个局部且可验证的任务，例如：

1
为 main 文件新增一个 hello world 函数，并解释改动点

根据官方 Quickstart，Claude Code 在要修改文件时会展示拟议变更，并请求授权。也就是说，它的默认工作方式不是“静默改代码”，而是“先提出修改，再等待确认”。

这套机制很关键，因为它直接决定了工具在真实仓库中的可控性。

一个更真实的使用顺序

比“写一个 hello world”更接近日常开发的链路通常是下面这样：

sequenceDiagram
    participant U as 开发者
    participant C as Claude Code
    participant R as 代码仓库
    participant T as 测试/命令环境

    U->>C: 描述问题或任务
    C->>R: 读取相关文件与结构
    C->>U: 说明理解与计划
    U->>C: 确认或修正边界
    C->>R: 提议修改多个文件
    U->>C: 审核并授权
    C->>T: 运行命令或测试
    T-->>C: 返回验证结果
    C-->>U: 汇总改动与剩余问题

真正高效的地方不在“让它一次写完”，而在“让它沿着可审查、可验证的链路推进任务”。

先分清两类命令

如果要把 Claude Code 真正用起来，第一件事不是背命令，而是先分清命令所在的层。

如果这层不分清，后面最常见的问题就是：

• 把 /resume 当成 shell 命令去敲
• 把 claude -p 当成会话内命令输入
• 不知道什么时候该用 /plan，什么时候该重新开一个终端会话

可以把它理解成：

claude ... 负责“怎么进入或管理会话”，/xxx 负责“进入会话之后怎么控制代理行为”。

CLI 命令合集

下面这一组命令属于终端层，应该在 shell 中执行。

启动与恢复

示例：

1
2
cd your-project
claude

1
claude "给我一个这个仓库的整体概览"

1
claude -c

1
claude -r "auth-refactor" "继续昨天的登录重构任务"

一次性查询与脚本化调用

示例：

1
claude -p "解释 src/auth/service.ts 的职责"

1
cat logs.txt | claude -p "概括错误类型，并按优先级排序"

1
claude -c -p "检查当前目录下是否还有类型错误风险"

安装、更新与认证

示例：

1
2
3
claude auth login
claude auth status --text
claude update

后台会话与并行任务

示例：

1
2
3
claude agents --json
claude logs 7c5dcf5d
claude attach 7c5dcf5d

MCP、插件与项目清理

会话内 Slash 命令合集

下面这一组命令属于交互会话内部，只能在已经进入 claude 之后输入。

新手最常用的一组

与代码评审和交付最相关的一组

与并行代理最相关的一组

几个非常容易用上的命令示例

1
/init

1
/plan

1
/compact 只保留当前 Bug 的复现条件、根因、改动文件和验证结论

1
/code-review

1
/background 继续排查这个 flaky test，定位根因后给出最小修复方案

CLI Flags 怎么看

除了命令本体，Claude Code 还有一层很重要的能力来自启动参数，也就是 flag。这部分如果完全不写，教程会停留在“能进入会话”，但无法覆盖自动化、受控权限和大仓库使用。

最常用的 flags

一些高频组合

1
claude --permission-mode plan

1
claude --add-dir ../shared ../infra

1
claude --effort high "先分析支付链路，再给修复方案"

1
claude --bg "调查这个 flaky test，修复后跑相关测试"

需要特别强调的是：

• --dangerously-skip-permissions 很强，但不适合作为默认方式
• --add-dir 解决的是额外目录访问，不等于自动继承这些目录的全部 .claude/ 配置
• --bg 适合长任务，不适合需要频繁交互确认的任务

一条真正可执行的上手流程

如果现在要把本文当教程，而不是当概念笔记，第一次实践最建议直接照着下面这条链路走。

场景一：第一次进入陌生仓库

1
2
cd your-project
claude

进入会话后依次执行：

1
/init

1
给我一个这个仓库的整体概览，重点说明目录结构、主入口、核心模块和构建方式

1
找出认证相关的文件，并说明这些文件之间如何协作

1
/context

如果上下文变长但还想继续：

1
/compact 只保留当前项目结构、认证链路和后续要排查的关键文件

场景二：修一个可复现的 Bug

1
/plan

1
执行 npm test 时 auth 模块有一个稳定失败的用例。先定位根因，给出两种修复思路；确认后只修改服务层和测试，并重新运行相关测试验证。

改动产生后先检查：

1
/diff

准备交付前再做一轮自审：

1
/code-review

如果会话太长：

1
/compact 只保留这个 Bug 的复现命令、根因、修改点和验证结果

场景三：把长任务放到后台

1
/background 继续扫描整个仓库的 deprecated API，用列表输出问题点，并按风险排序

回到 shell 后可以查看：

1
2
3
claude agents --json
claude logs <session-id>
claude attach <session-id>

六、在 VS Code 中使用 Claude Code

如果日常主工作区在 VS Code，官方更推荐直接使用 Claude Code 扩展。

它和终端 CLI 的关系

VS Code 扩展并不是简单把终端包了一层 UI，而是提供了更适合编辑器场景的图形化交互能力：

• 侧边栏或标签页中的会话面板
• 行内或选区级别的上下文引用
• 侧边对比的改动审阅
• 多会话并行
• 会话历史回看
• 在计划模式下直接审阅 plan 文档

同时还要注意一个容易忽略的点：

扩展内置了用于聊天面板的 CLI，但如果要在 VS Code 的集成终端里直接运行 claude 命令，仍然需要单独安装独立 CLI。

安装扩展

在 VS Code 中打开扩展视图，搜索 Claude Code 并安装即可。官方文档要求 VS Code 1.98.0 及以上版本。

安装完成后，可以通过几种入口打开它：

• 编辑器右上角的图标
• 左侧 Activity Bar
• 命令面板中的 Claude Code
• 状态栏入口

VS Code 里的核心使用方式

VS Code 扩展最有价值的地方，在于它把“具体文件上下文”和“代理操作”连接得更紧。

例如：

• 选中一段代码后直接发问
• 通过 @ 引用文件和目录
• 用 Option + K 或 Alt + K 插入带行号的引用
• 在侧边 diff 里直接审改提议内容
• 打开历史会话继续处理上一次没做完的问题

三种常见权限模式

官方文档里提到的权限模式，决定了它每一步能自动做到什么程度。

对于多数生产仓库，默认建议从 Manual 或 Plan mode 开始，而不是直接切到全自动编辑。

@ 引用为什么重要

很多人习惯把问题直接写成自然语言，但在 IDE 场景里，@ 引用文件和目录往往更高效。

例如：

1
请解释 @src/auth/ 的核心职责，并说明登录流程从哪个入口开始

1
检查 @src/user/service.ts#20-80 这段逻辑是否有空指针风险

这样做的价值在于：

• 明确把上下文锚定到具体对象
• 减少代理在仓库里大范围猜测
• 让分析范围与变更范围保持一致

七、Claude Code 的高频工作流

官方 Common Workflows 页面给出的建议非常实用，本质上是在告诉使用者：不要只把它当聊天框，而要把它当成“围绕开发动作组织上下文”的工具。

理解陌生仓库

刚接手一个项目时，不需要自己先把所有目录翻一遍，可以先让它做第一轮结构梳理：

1
给我一个这个代码库的整体概览

1
解释这里的主要架构模式

1
认证相关逻辑分布在哪些文件里？

这里的正确用法不是停留在“一句总结”，而是继续追问关键链路，例如：

• 主入口在哪里
• 核心模块如何协作
• 数据模型怎么流转
• 哪些目录是框架胶水层，哪些目录是业务层

定位 Bug

排错通常是 Claude Code 最容易体现价值的场景之一，因为它能把“错误信息、代码搜索、命令执行、修复验证”串起来。

更有效的表达通常包括：

• 报错信息
• 复现命令
• 复现条件
• 是否稳定复现
• 期望结果是什么

例如：

1
执行 npm test 时 user 模块有一个稳定失败的用例。先定位根因，给出两种修复思路；确认后再改代码并重新跑测试。

这比“帮我修一下测试”更容易收敛。

做重构

重构类任务的关键不是“改成新写法”，而是“行为保持不变”。

因此比较稳妥的提法通常会显式包含两个约束：

• 允许修改哪些层
• 如何证明行为没有回归

例如：

1
把 utils.js 重构为现代 JavaScript 写法，但不要改变对外行为；改完后运行现有测试，并总结每一处重构带来的收益。

补测试

对很多项目来说，“没有人愿意补测试，但测试又必须补”正是代理工具最容易产生复利的点。

典型用法是：

1
先分析 auth 模块哪些核心分支没有覆盖，再为最关键的成功路径、失败路径和边界条件补测试，最后运行相关测试文件验证

这个表达比“给 auth 模块写测试”更有效，因为它把优先级和覆盖目标一起说清楚了。

文档与提交整理

除了代码本身，Claude Code 也适合承担一些工程配套工作，例如：

• 根据变更生成提交说明
• 总结本次 diff 的风险点
• 起草 PR 描述
• 整理模块说明文档

这些工作本身不是最难的工程问题，但非常消耗注意力，交给代理通常能节省大量时间。

八、怎样提需求，Claude Code 更容易成功

Claude Code 的效果，很大程度上取决于任务描述是否包含足够的结构信息。

一个高质量任务描述通常包含五部分

一个更稳妥的提示词模板

1
2
3
4
先分析【对象】的现状和问题，给出【数量】种可选方案；
确认后只修改【允许变更范围】；
不要改动【禁止变更范围】；
完成后执行【验证动作】并总结风险点。

例如：

1
2
3
先分析支付回调处理链路的幂等问题，给出两种修复方案；
确认后只修改服务层和测试，不要改数据库表结构；
完成后运行支付模块测试并总结剩余风险。

为什么“先分析，再修改”通常更稳

这是因为代理类工具最容易出错的地方，不是局部代码能力，而是对问题边界的误判。

先让它分析，再让它提出计划，至少有三个好处：

• 可以先验证它是否理解对了问题
• 可以在变更前修正方向
• 可以避免一上来就把仓库改乱

因此，在复杂任务上，Plan mode 往往比直接自动编辑更稳。

九、权限、验证与安全边界

代理工具最大的价值来自执行能力，但风险也恰好来自执行能力。

为什么权限模式很重要

如果一个工具只能回答问题，最大的风险通常只是回答不准；但如果一个工具可以编辑文件、执行命令、连接开发环境，那么风险维度就会明显增加。

主要风险通常集中在三类：

• 改错文件
• 跑错命令
• 在未充分验证时给出“已经完成”的错觉

因此，实际使用时建议把下面这几个习惯固定下来：

• 默认先用 Manual 或 Plan mode
• 高风险仓库不要直接启用自动编辑
• 每轮修改后要求它执行验证动作
• 自己审查 diff，而不是只看自然语言总结

验证不是可选项

让 Claude Code 改代码时，最容易忽略的一步是验证。

一个更好的习惯是把验证要求直接写进任务中，例如：

• “改完后运行相关单测”
• “修复后重新执行构建”
• “输出复现命令和验证结果”
• “如果无法验证，明确说明阻塞原因”

这样做的意义在于，代理的“完成”不再只是语言声明，而是绑定到具体证据。

敏感信息与环境边界

虽然 Claude Code 能直接操作开发环境，但这并不意味着任何敏感上下文都应该无条件暴露给它。

工程上通常仍然需要保留几条基本纪律：

• 不要把密钥、令牌、生产数据库凭据直接放进提示里
• 不要让代理在不清楚副作用的情况下执行高风险命令
• 不要因为它“看起来懂了”就跳过代码审查
• 对涉及真实外部资源的操作，优先先做只读分析

十、常见误区与问题

误区一：把它当作“会写代码的聊天机器人”

如果只是拿它来回答概念问题，它当然也能用，但这不是它最有价值的位置。

Claude Code 的强项是围绕仓库上下文推进任务，而不是脱离环境给出泛泛解释。

误区二：一上来就给一个特别大的任务

例如“把整个系统重构一下”“把性能全部优化一下”这种任务，通常边界不清，成功率也不会高。

更合适的做法是先切出可验证的子任务：

• 先定位瓶颈
• 再给修复方案
• 再限定变更范围
• 最后逐步验证

误区三：只看总结，不看 diff

代理输出的自然语言总结，本质上只是辅助说明；真正决定结果质量的仍然是：

• 改了哪些文件
• 改了什么逻辑
• 是否引入副作用
• 是否跑过验证

因此最终判断应基于 diff 和验证结果，而不是基于“它说得很像真的”。

误区四：认为提示词必须写得像咒语

真正重要的不是复杂术语，而是任务结构清楚。

比起堆很多修辞，更重要的是把下面几个问题说明白：

• 问题在哪
• 目标是什么
• 允许改什么
• 不能改什么
• 怎么验证

一些常见故障点

十一、一套更实用的日常使用建议

如果目标不是“试一试”，而是把 Claude Code 真正纳入日常开发流，可以采用下面这套更稳妥的节奏。

推荐工作方式

1. 先让它解释项目或模块，确认理解正确
2. 再让它输出计划，而不是立刻修改
3. 对复杂任务明确写出允许变更范围
4. 修改后一定要求执行验证
5. 最后自己审查 diff 和总结

推荐任务类型

优先从这些任务开始积累信任：

• 理解陌生仓库
• 查找某个功能相关文件
• 修复一个可稳定复现的 Bug
• 为已有模块补测试
• 做局部重构
• 整理文档、提交说明、PR 描述

等到对它的行为模式已经足够熟悉，再逐步把更复杂的需求交给它。

不建议一开始就交给它的任务

• 业务边界完全模糊的需求
• 缺乏验证手段的高风险改造
• 涉及生产数据和外部副作用的敏感操作
• 需要重大技术决策的架构迁移

这些任务不是绝对不能用 Claude Code，而是更适合先把它放在“分析与辅助”角色，而不是直接进入“自动执行”角色。

十二、总结

Claude Code 的核心价值，不是“会不会写几行代码”，而是它把 AI 从单次问答推到了真实开发流程里。

可以概括为三点：

• 它适合承担跨文件、跨步骤、可验证的开发任务
• 它的正确使用方式是“任务代理”，而不是“高级补全”
• 它的真正上限，取决于任务边界是否清楚、权限是否受控、验证是否落实

如果只是把它当成一个更聪明的聊天框，价值会被明显低估；如果把它放进“理解代码库、推进小到中型任务、执行验证、整理工程配套产物”这条链路里，它通常会比单纯补全工具更接近真实开发助手。

从上手路径来看，比较稳妥的起点是：

1. 先在终端里完成第一次项目理解和小修改
2. 再在 VS Code 中体验带 diff 审阅的工作方式
3. 接着用一个真实 Bug 或补测试任务建立信任
4. 最后再逐步扩大到重构、文档整理和更长链路任务

这样使用，Claude Code 才更像一个真正可控、可审查、可验证的工程代理，而不是一个“偶尔能写点代码的聊天窗口”。

• Previous
  CC Switch 使用教程