Claude Code 全流程通俗讲解：小白也能看懂的 AI 编程助手入门指南

阅读路线建议：只想快速上手 → 直接跳转【四、安装教程】；想弄懂原理和工具差异 → 从头阅读；遇到报错 → 跳转【六、常见问题与避坑指南】。

---

前言：你需要的不是"更聪明的 ChatGPT"，而是"能帮你干活的程序员"

如果你用过 ChatGPT 或者 DeepSeek 网页版写代码，你一定经历过：复制需求过去 → 复制代码回来 → 发现少了什么 → 再问 → 再粘贴……循环往复。

这个流程最大的问题是：ChatGPT 只能"说"，不能"做"。它不知道你的项目里有什么文件，更不会帮你跑命令、改文件、执行测试。

Claude Code 的设计思路正是打破这个限制。 它不是网页上的聊天机器人，而是一个终端里的编程搭档——能直接读写你的文件、执行命令、理解整个项目结构。

读完这篇文章，你会明白：

• Claude Code 到底是什么？ —— 不是聊天工具，是终端里的 AI 编程 Agent
• 它和 Cursor、Copilot 有什么区别？ —— 调度模式不同，自主性不同
• 怎么安装？怎么接入 DeepSeek？ —— 三步搞定，国内直连
• 它有哪些核心功能？怎么用？ —— 从启动到实战，完整演示

---

一、Claude Code 到底是什么？

命名说明：本文介绍的 claude 命令行工具，官方名叫 Claude CLI，大家日常都叫它 Claude Code。下文统一用 Claude Code。

1.1 一句话定义

Claude Code 是 Anthropic 公司推出的命令行 AI 编程 Agent，能直接在你的项目目录里读写文件、执行终端命令、运行测试，像一个真正理解你代码库的协作者一样参与开发。

用人话翻译：打开终端，进入项目目录，输入 claude，然后说"帮我写一个登录接口"——它就会在你的项目里创建文件、写代码、跑测试，不需要你复制粘贴。

1.2 它不是"更强的代码补全"，而是"能自主干活的 Agent"

很多人会问：“它和 GitHub Copilot、Cursor 有什么区别？”

区别的核心在于调度模式和自主性：

工具	调度模式	自主性
GitHub Copilot	编辑器内嵌补全，你写一行它补一行，无法理解项目全局	无自主性，纯被动响应
Cursor	编辑器内对话 Agent，受编辑器沙箱限制，任务规划能力较弱，需要人工切割任务	有限自主性，跨文件操作需人工协调
Claude Code	原生终端运行，拥有完整项目文件读写 + 终端执行权限，自主任务规划更强	高度自主，能自己决定先读哪个文件、再改哪个文件、最后跑什么测试

关键区别：Cursor 本质上受限于编辑器沙箱，它的"Agent"能力是在编辑器框架内实现的；Claude Code 直接跑在操作系统层面，拥有和开发者完全一样的文件系统和终端权限，因此自主规划能力更强。这不是"谁更好"的问题，而是设计哲学不同——Cursor 更安全但受限，Claude Code 更强大但需要你懂得控制它。

1.3 一个具体例子感受一下

假设你对 Claude Code 说：“帮我给这个 Spring Boot 项目加上 JWT 登录功能。”

Claude Code 会自己做以下事情：

1. 先读 pom.xml，看看项目已有的依赖
2. 读现有的 Security 配置和 User 实体类
3. 自己决定需要创建哪些文件（JwtUtil、AuthController、SecurityConfig……）
4. 逐个创建文件，写入代码
5. 在 pom.xml 里添加 jjwt 依赖
6. 运行 mvn compile 验证能不能编译通过
7. 编译报错？自己读错误日志，自己修复

整个过程你只需要在终端里看着它干活，偶尔点一下"确认"就行。

---

二、背景：为什么需要终端 AI 编程助手？

2.1 一句话讲清楚

Anthropic 的 Claude 模型代码能力很强，但只放在网页聊天框里，能力被严重限制——它只能"说"不能"做"。Claude Code 的设计理念就是：把 AI 能力从网页搬到终端，并给它装上"手脚"（文件操作 + 命令执行）。

2.2 关键变化：DeepSeek 兼容让成本降了 10 倍

到了 2025-2026 年，DeepSeek V4 系列在代码能力上追平国际一流水平，并且提供了 Anthropic API 兼容接口。只需改几个环境变量，就能用 DeepSeek V4-Flash 驱动 Claude Code，费用约为官方 Claude API 的十分之一。

---

三、相比于其他工具的优势

3.1 核心优势一览

维度	Claude Code	Cursor / Copilot
运行环境	终端（CLI），不依赖任何 IDE	绑定在特定编辑器里
项目理解	自动读取项目结构，理解全局架构	受编辑器沙箱限制，需要人工协调跨文件理解
任务自主性	能自主规划多步任务、跨文件操作	需要用户逐步引导、人工切割任务
工具调用	原生支持 MCP，可接入任意第三方工具	工具生态相对封闭
上下文管理	支持压缩、清空、CLAUDE.md 项目配置	上下文管理相对简单
Hook 机制	工具执行前后可插入自定义逻辑	大多不支持
SubAgent	可创建独立上下文的子智能体，并行处理任务	不支持或支持有限
成本	接入 DeepSeek 后较低（400万 Token 约 ¥2）	通常是固定订阅制

3.2 最关键的三个差异化优势

优势一：真正的 Agent 级自主性

Claude Code 的核心能力不是"回答问题"，而是**“自主完成任务”**。它有三种运行模式（按 Shift+Tab 切换）：

模式	说明	适用场景
默认模式	每次创建/修改文件前询问你，最稳妥	不确定的任务、新项目
自动模式（Accept Edit On）	自动创建修改文件，无需确认，效率最高	信任的任务、批量操作
规划模式（Plan Mode）	只讨论方案不执行，适合架构设计	大改前对齐、设计评审

⚠️ 风险警示：自动模式下 AI 可以无确认修改任意代码文件，严禁在未 Git 提交、无备份的项目中随意开启。建议先 git commit 再切自动模式，出问题可以 git reset --hard 恢复。

优势二：MCP + Hook + SubAgent 的扩展体系

Claude Code 不是"一个孤立的工具"，而是一个可扩展的 Agent 平台：

• MCP（模型上下文协议，让 AI 调用外部工具的通用标准）：可接入数据库、浏览器、Figma 等任意第三方工具
• Hook 机制（工具执行前后的拦截器，类比 Java AOP 切面）：写完代码自动格式化
• SubAgent（独立上下文的子智能体，不污染主对话）：专门做代码审核的 AI 分身
• Plugin 插件体系：把以上能力打包成一键安装的插件

优势三：终端原生，不绑定 IDE

• 不挑编辑器：你用 VS Code、Vim、IntelliJ 都行
• 适合 CI/CD：可以在自动化流水线里跑
• 学习成本低：开发者本来就天天用终端

---

四、安装教程

4.1 准备工作

三样东西：

准备项	说明	怎么获取
Node.js 18+	运行环境	去 nodejs.org 下载 LTS 版本，一路"下一步"
Git	版本管理（Mac/Linux 自带）	Windows 去 git-scm.com 下载
DeepSeek API Key	调用模型的"钥匙"	去 platform.deepseek.com 注册后创建

装完后验证：

node -v        # 看到版本号就对了
npm -v         # 同上
git --version  # 同上

4.2 安装 Claude Code

⚠️ 官方说明：npm 包 @anthropic-ai/claude-code 已被 Anthropic 标记为 deprecated（废弃），属于可用但不再主推，短期数月内不会失效。

推荐方式：npm 安装（国内首选）

npm 包托管在 npm 仓库，可切换淘宝镜像，国内直连下载，速度稳定：

npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code

为什么 npm 更适合国内用户：

优势	说明
国内直连	切淘宝镜像后下载不走海外服务器，速度快且稳定
不依赖 claude.ai	不需要访问 claude.ai 域名，规避运营商拦截
排查成熟	依赖 Node.js 环境，报错信息明确，社区方案多

备选方式：官方原生安装脚本（国内网络不推荐）

官方脚本存在以下三个痛点，国内用户谨慎使用：

痛点	说明
下载慢 / 中断	脚本直连谷歌海外存储下载 claude.exe（约 235MB），国内网络波动大，经常中断
域名拦截	访问 claude.ai 会被运营商拦截，返回的不是脚本而是网页 HTML，PowerShell 尝试把网页当脚本执行，直接语法崩溃
默认连不上	即使安装成功，不加环境变量时默认连接 api.anthropic.com，国内直连失败

如果仍想尝试官方脚本：

Windows PowerShell：

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

Mac / Linux：

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

懒人方式：让 AI 帮你装

如果你已经有支持终端操作的 AI 编程助手，可以直接对它说：

“帮我在电脑上安装 Claude Code，用 npm 淘宝镜像安装，然后配置 DeepSeek 的环境变量。”

AI 会自动执行安装命令、配置环境变量，你只需要确认就行。

验证：

claude --version   # 看到版本号就说明装好了

Windows 用户：如果提示"找不到 claude 命令"，在 PowerShell 中执行以下命令修复 PATH，然后重开终端：

$npmPath = npm config get prefix
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$npmPath", "User")

4.3 接入 DeepSeek-V4-Flash（核心步骤）

DeepSeek 提供了 Anthropic API 兼容接口，设三个环境变量即可。

临时配置（仅当前终端有效）

Windows PowerShell：

$env:ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="你的DeepSeek-sk-密钥"
$env:ANTHROPIC_MODEL="deepseek-v4-flash"

Mac / Linux：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="你的DeepSeek-sk-密钥"
export ANTHROPIC_MODEL="deepseek-v4-flash"

⚠️ 重要提醒：直接在终端执行 export / $env: 仅临时生效，关闭终端就丢失。新手经常关了终端重新打开，配置失效然后疯狂报 401。下面两种持久化方案任选其一。

持久化方案一（推荐）：项目 .env 文件

在项目根目录创建 .env 文件，内容如下：

ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_AUTH_TOKEN=sk-你的DeepSeek密钥
ANTHROPIC_MODEL=deepseek-v4-flash

每次启动 Claude Code 前，在终端执行一行命令加载：

Windows PowerShell：

Get-Content .env | ForEach-Object { if ($_ -match '^([^=]+)=(.*)') { [Environment]::SetEnvironmentVariable($matches[1], $matches[2], 'Process') } }

Mac / Linux：

export $(cat .env | xargs)

优点：按项目隔离，不会污染全局环境；换项目换配置互不影响。务必把 .env 加入 .gitignore，防止 API Key 泄露到 Git 仓库。

注意：.env 文件内不要写 # 注释，PowerShell 简易加载脚本无法识别注释行，会导致加载失败。

持久化方案二（备选）：写入 Shell 配置文件

把三行 export 加到你的 Shell 配置文件中，每次打开终端自动生效：

• Mac / Linux：写入 ~/.zshrc（Zsh 用户）或 ~/.bashrc（Bash 用户）
• Windows PowerShell：写入 $PROFILE 文件（如果没有，先执行 New-Item -Path $PROFILE -Force 创建）

⚠️ 兼容性说明：DeepSeek 的 Anthropic 兼容接口属于协议适配层，并非官方原生 Claude 模型。具体兼容情况：

场景	兼容性	说明
读写文件、执行命令、项目改造	完全可用	日常开发核心功能，稳定
代码生成、重构、Git 操作	完全可用	主要使用场景，无问题
原生 MCP 流式能力	部分受限	部分高级 MCP 插件可能报错
高级工具权限控制	部分受限	细粒度权限可能不生效
部分 Agent 原生高级特性	可能不兼容	如某些 SubAgent 高级参数

如果你只需要日常编码，DeepSeek 完全够用；如果需要完整高级特性，建议使用 Anthropic 官方 API。

4.4 验证是否成功

终端输入 claude，看到交互界面后问它"你现在用的是什么模型？"，回答 deepseek-v4-flash 就对了。

---

快捷键速查卡片

以下快捷键贯穿日常使用，建议先扫一眼，用的时候回来查。

快捷键/命令	作用
claude	启动交互模式
claude -p "xxx"	单次命令模式，执行完退出
claude -c	启动并恢复上次对话
Shift+Tab	切换运行模式（默认 → 自动 → 规划）
ESC ESC 或 /rewind	回滚操作
Ctrl+B	当前任务放入后台
/tasks	查看后台任务
/compact	压缩对话历史（释放上下文空间）
/clear	清空对话历史
/resume	查看并恢复历史对话
/agent	创建 SubAgent
/plugins	打开插件市场
/help	查看帮助

---

五、核心功能详解

这部分是本文的重点。每个功能都会讲清楚"怎么用、什么时候用、用了能干啥"。

5.1 启动方式：两种进入方法

方式一：交互模式（最常用）

cd 你的项目目录
claude

进入后像聊天一样下指令，比如"帮我看看这个项目是干什么的"——Claude Code 会自动读取项目文件并分析。

方式二：单次命令模式（适合脚本/自动化）

# 解释代码
claude -p "解释一下 src/main.js 这个文件做了什么"

# 生成 Git 提交信息
claude -p "根据 git diff 生成一条中文 commit message"

5.2 三种运行模式：控制 AI 的"自主程度"

按 Shift+Tab 循环切换，这是你控制 AI"有多大胆子"的核心开关：

模式	行为	适合场景	举例
默认模式	每次创建/修改文件前弹确认框	新项目、不确定 AI 怎么改	“帮我重构这个模块”——逐步审核
自动模式	自动创建修改文件，不问你	信任的任务、批量操作	“把项目里所有 var 改成 let”
规划模式	只讨论方案，不动手	架构设计、技术选型	“单体拆微服务怎么拆？”——先讨论

⚠️ 自动模式风险警示：自动模式下 AI 可无确认修改任意文件。务必在 git commit 之后再开启，出问题用 git reset --hard 恢复。不要在未备份的项目中使用自动模式。

实操演示——给 Spring Boot 项目加用户注册功能：

# 第一步：切规划模式讨论方案
按 Shift+Tab 切到 Plan Mode
输入："我想给这个项目加用户注册功能，需要哪些步骤？"
→ AI 输出：1. 检查依赖 2. 创建实体类 3. 创建 Controller/Service...

# 第二步：确认方案后切默认模式执行
按 Shift+Tab 切回 Default Mode
输入："按刚才的方案开始做吧"
→ AI 逐步执行，每步让你确认

5.3 回滚（Rewind）：AI 改错了？一键回到过去

按两下 ESC 或输入 /rewind，Claude Code 会列出操作记录，选择回滚点即可恢复。

真实场景：

你说："帮我重构 UserService.java"
它改了 5 个文件，你发现第 3 个改错了。

按 ESC ESC，看到：
  [1] 修改 UserService.java
  [2] 修改 UserController.java
  [3] 修改 UserMapper.java  ← 这个改错了
  [4] 修改 UserDTO.java
  [5] 修改 application.yml

选择回滚到 [2]，[3][4][5] 全部撤销，[1][2] 保留。
然后告诉它："UserMapper 不要动，其他的重做。"

限制：回滚只能撤销 Claude Code 直接写入的文件，终端命令生成的文件（如 npm install 产生的 node_modules）无法回滚。建议搭配 Git 使用——大改动前先 git commit。

5.4 终端命令执行：AI 能帮你跑命令

Claude Code 能执行编译、测试、Git 操作等终端命令。默认安全机制：每条命令执行前必须你确认。

命令类型	举例
编译构建	mvn compile、npm run build
运行测试	mvn test、npm test
Git 操作	git status、git diff
包管理	npm install xxx

主动要求它执行命令的示例：

"帮我把这个项目跑起来"
→ 读 package.json → 找到启动命令 → 执行 npm run dev → 报错？读日志自己修

"跑一下单元测试，看看有没有失败的"
→ 执行 npm test → 分析结果 → 有失败？读测试代码尝试修复

"帮我看看 git 有哪些改动，生成一条 commit message"
→ 执行 git diff → 分析改动 → 生成中文 commit message

5.5 后台任务：同时干多件事

操作	快捷键/命令
放入后台	Ctrl+B
查看任务	/tasks
终止进程	任务列表里按 K

5.6 上下文管理：解决"聊多了就忘"

命令	作用	什么时候用
/compact	把对话压缩成摘要	聊了很久，AI 开始"忘事"
/clear	清空对话历史	开始全新任务，不想被前面干扰

CLAUDE.md 项目配置文件：放在项目根目录，启动时自动加载，适合放"每次都要交代"的规则：

# CLAUDE.md 示例

## 项目规范
- 本项目使用 Spring Boot 3.3.3 + MyBatis-Plus
- 所有接口返回统一格式 Result<T>
- 实体类放 entity 包，VO 放 vo 包

## 注意事项
- 数据库连接信息在 application-dev.yml
- 不要改 application.yml

有了这个文件，每次启动 Claude Code 都会自动记住这些规则。

⚠️ 安全提醒：CLAUDE.md 只存放项目规范、代码风格等公共规则，禁止写入数据库账号、API 密钥等敏感信息。CLAUDE.md 通常会被提交到 Git 仓库，一旦包含密钥会造成泄露。

5.7 多模态能力 + 对话恢复

多模态：拖拽设计稿截图到终端，说"帮我用 HTML + CSS 还原这个页面"，Claude Code 会分析图片并生成代码。

对话恢复：输入 claude -c 启动，自动恢复上次没做完的对话，不用重新交代背景。

5.8 Hook 钩子机制

⚠️ 安全提醒：Hook 可执行自定义脚本，不要直接运行网上复制的第三方 Hook 配置，先审阅脚本内容，确保没有恶意代码。

Hook 在 AI 执行操作前后自动触发自定义逻辑。例如：AI 每次写入文件后自动格式化代码：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "prettier --write $CLAUDE_TOOL_FILE_PATH"
      }]
    }]
  }
}

5.9 Agent Skill vs SubAgent

场景	用什么	原因
“写代码时遵循编码规范”	Agent Skill	轻量规则约束
“审查整个项目的代码安全漏洞”	SubAgent	过程长，独立上下文不污染主对话
“生成项目周报”	Agent Skill	模板化输出
“全量代码重构审计”	SubAgent	独立上下文，可并行跑

创建 SubAgent：输入 /agent → 新建 Agent，可配置独立模型和工具权限。

5.10 Plugins 插件

输入 /plugins 进入插件市场，一键安装功能包（类比 Maven Starter 依赖）。

---

六、常见问题与避坑指南

Q1：安装时提示 command not found: claude

npm 全局路径没加入 PATH。参考 4.2 节的修复命令。

Q2：启动后报错 401 Unauthorized

API Key 配置错误。检查 ANTHROPIC_AUTH_TOKEN 是否完整（sk- 开头）、Key 是否过期、账户余额是否充足。常见翻车点：用了临时环境变量，关终端重开后配置丢失。

Q3：启动后报错 404 Not Found

ANTHROPIC_BASE_URL 末尾不要加 /v1，正确值是 https://api.deepseek.com/anthropic。

Q4：部分高级功能报错（自定义 MCP、SubAgent 参数调用失败）

DeepSeek 的 Anthropic 兼容接口属于协议适配层，无法 100% 对齐原生 Claude 模型能力。具体来说：

• 完全可用：读写文件、执行命令、代码生成、项目改造、Git 操作等日常核心功能
• 部分受限：原生 MCP 流式能力、高级工具权限控制、部分 Agent 原生高级特性

如果只做日常编码，DeepSeek 完全够用；需要完整高级特性请用 Anthropic 官方 API。

Q5：API Key 安全

• 绝对不要把 API Key 提交到 Git 仓库
• 泄露后立即去 DeepSeek 控制台撤销（Revoke）并创建新 Key
• 推荐用 .env 文件管理，并在 .gitignore 中添加 .env

Q6：Windows PowerShell 脚本被拦截

以管理员身份打开 PowerShell，执行：

Set-ExecutionPolicy RemoteSigned

---

七、完整实战演示：从零给 Spring Boot 项目加 JWT 登录

下面是一个完整的实操流程，从启动 Claude Code 到功能完成，每一步都列出来了。新手可以照着复刻。

前置条件

• 已安装 Claude Code 并接入 DeepSeek-V4-Flash（参考第四节）
• 有一个 Spring Boot 项目（空壳即可，有 pom.xml 和基本的 Application.java）
• 项目已 git init && git commit -m "init"（保险）

实战步骤

第 1 步：启动 Claude Code

cd your-spring-boot-project
claude

第 2 步：先用规划模式讨论方案

按 Shift+Tab 切到 Plan Mode，输入：

"我想给这个 Spring Boot 项目加 JWT 登录功能，包括：
- 用户注册接口
- 用户登录接口（返回 JWT token）
- JWT 拦截器校验
请先帮我分析需要做哪些步骤，不要动手。"

Claude Code 会读取 pom.xml 和项目结构，然后输出：

需要以下步骤：
1. 在 pom.xml 添加依赖：spring-boot-starter-security、jjwt
2. 创建 User 实体类
3. 创建 UserMapper 和数据库表
4. 创建 JwtUtil 工具类（生成/校验 token）
5. 创建 AuthController（注册 + 登录接口）
6. 创建 JwtAuthenticationFilter 拦截器
7. 创建 SecurityConfig 配置类
8. 运行 mvn compile 验证

第 3 步：确认方案，开始执行

按 Shift+Tab 切回 Default Mode，输入：

"方案没问题，开始做吧。"

Claude Code 会逐步执行，每步弹确认框：

第 1 步：修改 pom.xml，添加 jjwt 和 security 依赖
  → 你点"确认"
第 2 步：创建 User.java 实体类
  → 你点"确认"
第 3 步：创建 UserMapper.java
  → 你点"确认"
...（依次确认每个文件）
第 7 步：创建 SecurityConfig.java
  → 你点"确认"
第 8 步：执行 mvn compile
  → 你点"确认"

第 4 步：编译报错？AI 自己修

如果 mvn compile 报错，Claude Code 会自动读错误日志、分析原因、修改代码、重新编译，直到通过。

第 5 步：验证结果

输入："帮我写一个 curl 命令测试登录接口是否正常"

Claude Code 会输出类似：

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

你复制到终端执行，看到返回 JWT token，功能完成。

整个过程你做了什么？

• 描述需求（2 句话）
• 确认方案（1 次）
• 逐步确认文件创建（约 7 次）
• 没写一行代码，没手动改一个文件

---

八、总结

Claude Code 代表了 AI 编程工具从"代码补全"到"自主 Agent"的进化方向。接入 DeepSeek-V4-Flash 后，你得到的是：

• 自主任务执行能力：自主规划、多文件操作、命令执行、错误修复
• 低成本：400 万 Token 约 ¥2，是官方 Claude 的 1/10
• 可扩展体系：MCP、Hook、SubAgent、Plugin

---

参考资料

• Anthropic Claude Code 官方文档
• DeepSeek API 开放平台
• DeepSeek Anthropic 兼容接口说明