Claude Code 从入门到实战：完整学习笔记

一、Claude Code 简介

Claude Code 是 Anthropic 官方推出的一款基于终端的 AI 编程代理（Coding Agent），深度集成在命令行环境中，能够理解自然语言指令，自主完成代码编写、文件操作、终端命令执行、项目重构等一系列开发任务。

💡 同类产品：Codex、Open Code、Cursor 等，核心原理相通，掌握 Claude Code 后同类产品也能快速上手。

二、安装与环境配置

2.1 前置条件

组件	要求
Node.js	18+ 版本
Git	推荐安装（版本控制）v9.0.0+
VS Code	可选（编辑体验）

2.2 安装步骤

安装 Node.js
官网下载 LTS 版本的 .msi 文件。下载地址：https://nodejs.org/zh-cn/download/

安装后验证：

node --version  # 需 v18.0.0+
npm --version   # 需 v9.0.0+

安装 Claude Code：

npm install -g @anthropic-ai/claude-code

速度慢可配置国内镜像：npm config set registry https://registry.npmmirror.com

验证安装：

claude --version

2.3 登录与认证

(第一种方式) 国外：首次执行 claude 会提示登录，有两种方式：

• 订阅制：购买 Claude Pro / Max 会员，浏览器授权
• API Key 计费：使用 Anthropic API，按 Token 计费

(第二种方式) 国内：可以选用代理，下载 CC Switch工具
下载地址：https://www.ccswitch.io/zh/

AI 大模型免费体验：阿里云百炼

注意： 需要手动开启【免费额度用完即停】，避免token超出，产生费用。

然后通过CC Switch 对claude code进行配置，可以绕过登录，接入阿里百炼大模型或者其他第三方大模型

获取API Key

任意选一个模型：

2.4 配置第三方模型（DeepSeek 等）【如果已用CC Switch工具代理可以跳过此步骤】

Claude Code 不与 Claude 模型强制绑定，可配置 DeepSeek、GLM、MiniMax 等国产模型。

核心环境变量：

• ANTHROPIC_BASE_URL：API 基础地址
• ANTHROPIC_API_KEY：API 密钥
• ANTHROPIC_MODEL：模型名称

Windows (CMD)：

set ANTHROPIC_BASE_URL=https://api.deepseek.com
set ANTHROPIC_API_KEY=你的API_Key
set ANTHROPIC_MODEL=deepseek-v4-flash[1M]
claude

macOS/Linux：

export ANTHROPIC_BASE_URL=https://api.deepseek.com
export ANTHROPIC_API_KEY=你的API_Key
export ANTHROPIC_MODEL=deepseek-v4-flash[1M]
claude

三、基础交互与三种模式

3.1 启动与基础使用

mkdir my-todo
cd my-todo
claude

在输入框中直接输入自然语言需求即可，例如：「给我做一个待办软件，使用HTML实现」。

3.2 三种交互模式（Shift+Tab 切换）

模式	文件操作	终端命令	适用场景
默认模式	每次询问	每次询问	新手、谨慎操作
自动模式	自动执行	每次询问	日常开发
规划模式	不执行	不执行	方案讨论

💡 输入框底部提示文字会显示当前模式：? For shortcuts（默认）、Accept edits on（自动）、Plan mode（规划）。

3.3 终端命令执行

在输入框中以 ! 开头执行终端命令：

!ls              # 列出文件（Windows: dir）
!open index.html # 打开文件（macOS）
!start index.html # Windows打开文件

执行：!start index.html 进行浏览页面

💡 按 Ctrl+G 可打开记事本/编辑器编辑内容，保存后自动填充到输入框。

四、复杂任务处理

4.1 Plan Mode 架构设计流程

1. 切换到 Plan Mode：按 Shift+Tab
2. 描述需求：例如「将当前的待办应用重构为 React + TypeScript + Vite」
3. 审阅计划：Claude Code 生成详细实施计划（项目目标、目录结构、技术方案、实施步骤）
4. 完善计划（可选）：提出修改意见
5. 执行计划：选择「执行并进入自动模式」或「执行并进入默认模式」

💡 多行输入用 Shift+Enter 换行，Enter 提交。

4.2 权限管理

权限类型	行为
文件操作（自动模式）	自动执行
文件操作（默认模式）	每次询问
终端命令	始终需要确认（高风险）

完全绕过权限（⚠️ 慎用）：
如果你希望 Claude Code 完全自主执行任何命令，可以在启动时添加参数：
该命令尽量不要尝试，以免带来不必要的损失！！！

claude --dangerously-skip-permissions 
# 或 `claude --permission-mode bypassPermissions`

添加此参数后，模式会变为 Bypass permissions on，Claude Code 不再征求你的任何意见。可能会把你的电脑中重要文件删除，所以要⚠️ 慎用！！！

警告：该参数名中的 dangerously 已经说明了一切。这会让 Claude Code 拥有和你一样的终端权限，理论上存在安全风险。仅在完全信任且需要全自动化的场景下使用。

4.3 后台任务管理

• Ctrl+B：将当前任务放到后台
• /tasks：查看所有后台任务
• 在 /tasks 界面按 K 结束指定任务

4.4 回滚操作

两种方式进入回滚模式：

• 快速按两下 ESC
• 执行 /rewind

回滚选项：

• 回滚代码和对话
• 仅回滚对话
• 仅回滚代码
• 放弃回滚

⚠️ 重要：只能回滚 Claude Code 自身写入的文件，终端命令（如 npm install）生成的文件无法回滚。精确回滚建议使用 Git。

4.5 上下文压缩与管理

命令	功能
/compact	压缩上下文，保留核心信息
/compact 策略说明	按指定策略压缩
/clear	清空所有上下文（不可逆）
Ctrl+O	查看压缩后的上下文

五、高级功能扩展与定制

5.1 MCP（Model Context Protocol）

MCP 是 Claude Code 与外部工具、API、数据源进行标准化交互的协议，让 AI 能够「感知」和「操作」外部世界。

实战：Figma MCP 还原设计稿

# 安装 Figma MCP Server
npm install -g @anthropic-ai/mcp-server-figma

# 启动并恢复对话
claude -c

认证与使用：

1. /mcp 查看已安装的 MCP
2. 选择 Figma MCP → authenticate（浏览器授权）
3. 粘贴 Figma 设计稿链接，Claude Code 自动调用 MCP 获取设计数据

💡 MCP 能获取精确的组件尺寸、间距、字体样式和颜色值，比图片还原精度更高。

基本命令：

比如：claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
注：--scope user 表示所有项目都可以使用
--scope project 表示仅当前项目可以使用,可与团队共享
--scope local 表示仅当前项目可以使用，不能与团队共享

作用域分析：

MCP实战组合编程清单：
新功能开发全流程

---

步骤	阶段目标	核心 MCP	典型操作（可直接对 Claude 说）
1	逻辑梳理 （拆解复杂需求，避免遗漏）	Sequential Thinking	“请分步骤思考：我要实现一个用户积分过期提醒功能，需考虑哪些边界条件、数据流和异常处理？”
2	查阅最新文档 （确保使用最新 API，不依赖过时知识）	Context7	“查阅 Next.js 15 最新文档，告诉我 App Router 下如何正确使用 cookies() 和 headers()。”
3	编写/修改代码 （生成、重构或批量更新源文件）	Filesystem	“在 /src/features 下创建积分模块，生成 service.ts、types.ts 和对应的 React Hook。”
4	浏览器验证 （交互测试、UI 截图、动态内容抓取）	Playwright	“打开本地 dev 环境，登录测试账号，进入积分页面，点击‘刷新’按钮，截图并检查是否正常显示过期时间。”
5	数据层校验 （确认读写正确，查询真实数据）	Postgres	“连接测试数据库，查询积分变动日志表，验证刚才触发的过期操作是否生成了正确的记录。”
6	提交与协作 （生成 PR 描述，发起代码审查）	GitHub	“对比当前分支与 main 的差异，生成规范 PR 标题和描述，并关联相关 Issue #123，然后创建 PR。”

---

这 6 个 MCP 正好覆盖了 “设计 → 文档 → 编码 → 验证 → 数据 → 协作” 的全链路。

工作流结构图：

💡 提示：每一步完成后，Claude 都可以根据结果决定是否回退到上一步（比如验证失败则返回步骤 3 修改代码），形成 闭环开发。如果某个环节缺少对应 MCP，只需去掉或替换即可，流程依然通用。

5.2 CLAUDE.md 项目配置

CLAUDE.md 是项目级配置文件，相当于「给 Claude Code 看的说明书」。

文件层次：

• 项目级：项目根目录 .claude/CLAUDE.md，对当前项目生效
• 用户级：~/.claude/CLAUDE.md，对所有项目生效

生成与编辑：

• /init：自动分析项目生成配置
• /memory：打开配置文件编辑

示例内容：

# 项目说明
这是一个待办事项管理应用，使用 React + TypeScript + Vite 构建。

# 编码规范
- 使用函数式组件
- 样式使用 CSS Modules
- 所有文本使用中文

5.3 Hook 自动化钩子

Hook 在工具执行前后自动运行自定义逻辑（如自动格式化）。

配置流程（/hooks）：

1. 选择执行时机：Pre-tool use / Post-tool use / Tool use failed
2. 选择目标工具：Write、Edit 等
3. 编写 Hook 逻辑（Shell 命令）

自动格式化示例：

# 安装依赖
brew install jq        # Mac
sudo apt install jq    # Ubuntu
npm install -g prettier

# Hook 命令：提取文件路径并格式化
jq -r '.tool_input.file_path' | xargs prettier --write

配置存储位置：

级别	路径
本地项目级	.claude/settings.local.json（自动加入 .gitignore）
项目级	.claude/settings.json（随 Git 分发）
用户级	~/.claude/settings.json

5.4 Agent Skill 技能系统

Skills 是 Claude Code 的可复用能力单元，将常见工作流封装成可调用的命令。它们是预定义的提示词模板，配合特定的工具和上下文完成特定任务。

核心特性：

• 可复用性：一次定义，随处调用
• 参数化：支持动态参数传递
• 上下文感知：自动适配项目环境
• 可组合：Skills 可以调用其他 Skills
• 版本控制：可纳入 Git 管理

目录结构：

.claude/
└── skills/
    ├── commit/
    │   └── SKILL.md      # 生成规范 Git 提交信息
    ├── review-pr/
    │   └── SKILL.md      # 审查 Pull Request
    ├── refactor/
    │   └── SKILL.md      # 安全重构代码
    └── test-gen/
        └── SKILL.md      # 生成单元测试

每个 Skill 占用一个独立子目录，子目录名称即 Skill 名称，核心定义文件必须命名为 SKILL.md（可在其中通过 frontmatter 声明名称、描述、参数等元数据）。

创建 Skill（以代码审查 Skill 为例）：

---
name: review
description: 对代码变更进行全面审查
args:
  - name: target
    description: 审查目标（文件路径或 git diff）
    required: false
---

# 代码审查 Skill
请对以下内容进行代码审查：
{{#if target}}目标：{{target}}{{else}}当前 Git 工作区的所有变更{{/if}}

## 审查清单
1. **代码质量** - 编码规范、命名清晰度、重复代码
2. **潜在问题** - 边界条件、错误处理、性能瓶颈
3. **安全性** - 输入验证、敏感信息、权限检查
4. **可维护性** - 代码复杂度、注释、测试覆盖

调用方式：

• 自动触发：对话中提出匹配请求，Claude Code 自动识别
• 手动触发：/review 或 /review src/auth/login.ts

Skills 查找顺序：

1. .claude/skills/（项目级，优先级最高）
2. ~/.config/claude/skills/（用户级）
3. 内置 Skills

实用 Skill 示例：

• Git 提交 Skill：分析暂存区变更，生成 Conventional Commits 规范提交信息
• 测试生成 Skill：为指定代码生成单元测试
• 重构 Skill：安全地重构代码，含前置检查、分析、执行、验证流程
• API 文档生成 Skill：生成 OpenAPI/Markdown/Postman 格式文档

最佳实践：

• 命名使用动词开头（review、generate、analyze），连字符分隔
• 必需参数放前面，提供合理默认值
• 提示词明确任务目标、清晰步骤、质量标准和输出示例

5.5 Sub Agent 子代理

Sub Agent 是拥有独立上下文的子代理，与主代理共享工具但不共享上下文。

创建（/agent）：

1. 选择作用范围：项目级 / 用户级
2. 选择创建方式：推荐 Claude Code 初始化
3. 描述职责：例如「代码审核 Sub Agent」
4. 配置工具权限（建议只读工具）
5. 选择模型和标识颜色

Agent Skill vs Sub Agent：

维度	Agent Skill	Sub Agent
上下文	共享主对话上下文	完全独立
中间过程	全部进入主上下文	只回传最终结果
Token 消耗	高	低
适用场景	与上下文关联大的任务	与上下文关联小的任务
典型用途	写每日总结、生成特定格式文档	代码审查、大规模重构

5.6 插件系统

Plugin 是将 Skill、Sub Agent、MCP、Hook 等能力打包的「全家桶安装包」。

管理（/plugin）：

• Discover：发现和安装新插件
• Installed：查看已安装插件
• Marketplaces：插件市场

安装 frontend-design 插件后，Claude Code 拥有 Anthropic 官方沉淀的 UI 设计直觉，生成的页面排版更高级、色彩更协调。

5.7 图片输入与 UI 还原

上传方式：

• 拖拽图片到输入框
• Ctrl+G 打开编辑器后粘贴图片（⚠️ 直接 Ctrl+V 粘贴不可用）

使用：上传后输入「请根据这个图片修改当前页面」

⚠️ 局限性：图片还原对字体大小、间距等细节把控不够精确。高精度还原建议使用 Figma MCP。

5.8 Claude Code 高级功能架构关系图

下面是 Claude Code 高级功能架构关系图：

六、常用命令速查

会话管理

命令	功能
claude	启动 Claude Code
claude -c	启动并恢复上次对话
/resume	恢复上一次对话
Ctrl+C（两次）	退出
/login / /logout	登录/退出

上下文控制

命令	功能
/compact	压缩上下文
/clear	清空所有上下文
Ctrl+O	查看压缩后的上下文

配置与项目管理

命令	功能
/init	生成 CLAUDE.md
/memory	编辑 CLAUDE.md
/hooks	管理 Hook 配置
/mcp	查看 MCP 工具
/skills	查看可用 Skill
/agent	管理 Sub Agent
/plugin	管理插件

快捷键

快捷键	功能
Shift+Tab	切换三种模式
Shift+Enter	换行（非提交）
Enter	提交请求
Ctrl+G	在编辑器中编辑输入
Ctrl+B	将任务放到后台
ESC（两次）	进入回滚模式

七、最佳实践总结

1. 从小开始：先用小任务熟悉工作流程
2. 规划先行：复杂需求先用 Plan Mode 讨论方案
3. 善用 Git：不依赖内置回滚，用 Git 做版本管理
4. 保持上下文精简：定期 /compact 或 /clear
5. 持续积累：通过 CLAUDE.md、Agent Skill、Hook 积累项目资产
6. 团队共享：将配置打包为 Plugin 或写入项目级配置
7. 关注安全：谨慎使用 --dangerously-skip-permissions
8. 选对工具：共享上下文用 Agent Skill，独立上下文用 Sub Agent

能力矩阵

能力	使用场景	配合工具
基础编码	日常开发	三种模式切换
架构设计	重构、技术选型	Plan Mode
设计还原	UI 稿编码	Figma MCP + 图片输入
自动化	格式化、代码检查	Hook + Prettier/ESLint
知识持久化	项目规范	CLAUDE.md
技能复用	日报生成、固定格式	Agent Skill
任务隔离	代码审查、独立调研	Sub Agent
能力扩展	外部工具集成	MCP
能力打包	分享配置、团队协作	Plugin

参考文档

Claude Code 开发文档