Claude Code 实战全流程：从入门到生产环境

文档结构概览

本教程将 Claude Code 从环境搭建到生产可用的完整流程拆成四部分，便于按需查阅。

内容目录

第 1 部分：环境搭建与基础交互

安装 Claude Code
登录与授权
第一个本地任务
三种模式详解（默认/自动/规划）

第 2 部分：复杂任务处理与终端控制

执行终端命令（Bash）
使用规划模式（Plan Mode）
跳过权限确认（dangerously-skip-permissions）
后台任务管理（Background Tasks）
常见问题与解决方案
扩展思考与模型选择
成本优化技巧

第 3 部分：多模态与上下文管理

回滚（Rewind）
用户托管
安装 MCP Server（以 Figma 为例）
恢复历史会话（Resume）
使用 MCP 工具重新设计
上下文管理与剪贴板
持久化上下文（CLAUDE.md）- 包含配置优先级与层次化加载
上下文压缩与清理（/compact、/clear）

第 4 部分：高级功能扩展与定制

Hook
Agent Skill
SubAgent
Skill 与 SubAgent 的区别
Plugin
Custom Command（自定义命令）
Rules（规则文件夹）
Git Worktree 多 Claude 协作
规范驱动开发（SDD）
MCP Server 实用集成示例

市场上其他编程 Agent（如 Cursor、Windsurf、OpenCode 等）在功能与使用方式上与 Claude Code 类似，掌握本教程后便于举一反三。

环境搭建与基础交互

安装 Claude Code

打开 Claude Code 官网，在页面中复制安装命令：

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

Windows 用户请使用 PowerShell 执行上述命令。

安装完成后，用 mkdir my-todo 创建项目目录，执行 cd my-todo 进入目录，再执行 claude 启动 Claude Code。

登录与授权

Claude Code 会提示登录；若未提示，可执行 /login 命令主动触发。

官方提供两种接入方式：

Claude account with subscription：Pro、Max、Team 或 Enterprise 订阅账户
Anthropic Console account：按量计费的 API 账户

选择后在浏览器中完成授权，回到终端按回车即可。

第一个本地任务

若无法使用 Claude 官方订阅或 API，也可用国产模型（如 GLM、MiniMax 等）驱动 Claude Code；Claude Code 不绑定特定模型。国产模型的配置方法请自行查阅官方或社区文档。

在 Claude Code 中输入需求，例如：

给我做一个待办软件，使用 HTML 实现

Claude Code 会提议创建 index.html 并询问确认。选项含义如下：

第一项 Yes：仅同意当前这一次操作。
第二项 Yes, allow all edits during this session (shift+tab)：本会话内后续修改自动通过。
第三项 No：拒绝。

选择后，输入框下方会出现 >> accept edits on (shift+tab to cycle)，表示已开启自动同意模式。可用 Shift + Tab 在三种模式间循环切换。

当底部没有模式标识、只显示灰色提示 ? for shortcuts 时，表示当前为默认模式（并非"快捷键模式"，该提示只是说明可按 ? 查看快捷键）。默认模式下，Claude Code 每次修改前都会询问用户。 Claude Code 三种工作模式切换界面 三种模式小结：

模式	底部提示	行为	适用场景
默认模式	`? for shortcuts`	修改前必询问	最稳妥
自动模式	`>> accept edits on`	自动修改文件	最省事
规划模式	`>> plan mode on`	只讨论不写文件	最适合方案讨论

切回自动模式后，在 Claude Code 中执行 !open index.html 即可打开生成的文件。Windows 下将 open 改为 start。

待办软件初始界面

待办软件初版

单文件 HTML 适合演示，但项目变大后难以维护，建议尽早迁移到 React + TypeScript。可向 Claude Code 提出重构需求。

在终端按 Shift + Tab 进入规划模式（Plan Mode），输入：

将当前的待办应用重构为使用 React + TypeScript + Vite 的项目

换行继续写需求时按 Shift + 回车；例如补充：「保留所有现有功能，且 UI 风格保持一致。」也可按 Ctrl + g 在 VS Code 中编辑大段需求，Claude Code 会读取该内容作为上下文（无需事先安装 VS Code）。编辑完成后按回车提交。

Claude Code 规划模式界面

工作流与模式运用

工作流基础操作

基础操作技巧：

指令要具体：清晰明确地描述需求，减少误解
及时纠正：发现问题立即反馈，让 Claude Code 快速调整
使用回滚：当 Claude Code 偏离方向时，使用 /rewind 回退
图片输入：直接粘贴截图（Ctrl+V，不是 Cmd+V）提供视觉参考
文件明确指向：使用 @文件名 明确要处理的文件
MCP 文档供给：通过 MCP 工具给 Claude Code 提供知识库文档
保持上下文聚焦：使用 /compact 和 /clear 管理对话历史

代码库理解与问答

代码库理解是新项目上手和代码维护的基础工作流。官方推荐的实践是：

从宽泛问题开始：先了解项目整体状况
逐步缩小到特定领域：聚焦具体模块或功能
重点关注编码约定、架构模式和项目特定术语

探索路径： 探索 → 规划 → 编码 → 提交

TDD 工作流

Claude Code 在 TDD（测试驱动开发）工作流中表现优异。典型流程包括：

1. 识别未测试代码
    ↓
2. 生成测试脚手架
    ↓
3. 添加有意义的测试用例
    ↓
4. 运行并验证测试
    ↓
5. 生成让测试通过的最精简代码
    ↓
6. 迭代优化和重构

TDD 实践要点：

先写失败的测试用例
Claude Code 能生成让测试通过的最精简代码
确保测试覆盖率（建议 70% 以上）
写测试、提交；编码、迭代、提交

待办软件实战与模式运用

规划模式下的计划确认

在 Plan Mode 下，Claude Code 会输出详细计划，包含目标、现有功能清单、项目结构等。

计划内容示例：

目标：将单页 HTML 待办应用重构为 React + TypeScript + Vite 项目
现有功能：添加/删除/完成任务、点击按钮或回车完成、筛选查看（全部/未完成/已完成）、新增加标签（工作/个人/健康）和时间显示、页面刷新自动保存到 localStorage、UI 风格保持一致
项目结构：src/components, src/types, src/hooks, src/App.tsx, src/main.tsx, vite.config.ts 等

计划完成后，Claude Code 会询问：

Would you like to proceed?

Yes, and auto-accept edits (shift+tab)

Yes, and manually approve edits

Type here and tell Claude what to change

关键区别：

第一种模式（Yes, auto-accept）：后续修改文件时不再询问用户，直接执行。
第二种模式（Yes, manually approve）：每次修改文件仍需用户确认。
第三种模式（Type to change）：允许用户在执行前修改计划细节。

若选第三项，可在执行前修改计划，例如补充：给每个待办增加优先级（高/中/低）并用不同颜色区分。

Claude Code 会按计划执行，例如：

创建 src/types/todo.ts 类型定义文件
创建 src/components/EmptyState.tsx, TodoItem.tsx, TodoList.tsx 等组件
创建 src/hooks/useTodo.ts 自定义 Hook
创建 src/App.tsx 主应用文件
创建 vite.config.ts 配置文件

创建目录或执行敏感操作时，Claude Code 会询问：

Do you want to proceed?

Yes

Yes, and always allow access to src/ from this project

No

选第二项可使后续对 src/ 的操作不再重复确认。 Claude Code 目录权限确认界面

终端权限控制

接下来，Claude Code 需要执行终端命令（如 npm install），这时会出现新的提示：

Do you want to proceed?

Yes

Yes, and always allow access to src/ from this project

No

执行终端命令属于敏感操作，因此没有“自动执行所有终端命令”的选项。若希望跳过权限确认，可在启动时加上 --dangerously-skip-permissions：

cd WebProjects/my-todo
claude --dangerously-skip-permissions

启动后按 ? 可见 bypass permissions on (shift+tab to cycle)，此后安装依赖、删文件、建目录等都不会再询问。

慎用跳过权限

该参数赋予 Claude Code 与当前用户相同的终端权限，能显著提升效率，但风险较高。建议仅在受控环境（如临时沙箱、专用开发机）下使用。

后台任务管理

npm run dev 启动后，服务占满前台，Claude Code 会询问是否需要帮助。此时按 Ctrl + b 可将该进程放到后台，即可继续在终端输入其他命令。

输入 /tasks 可查看后台任务列表（含运行时长、命令、输出等）。在任务详情中按 k 可终止对应任务。

/tasks 命令输出示例：

# 查看后台任务
/tasks

# 输出示例：
Background Tasks:
┌─────┬──────────────────┬──────────┬─────────────────────────────────┐
│ ID  │ Command          │ Status   │ Output (last 3 lines)           │
├─────┼──────────────────┼──────────┼─────────────────────────────────┤
│ 1   │ npm run dev      │ Running  │ Local: http://localhost:5173/   │
│     │                  │ (5m 23s) │ Network: use --host to expose   │
│     │                  │          │ ready in 342 ms                 │
├─────┼──────────────────┼──────────┼─────────────────────────────────┤
│ 2   │ npm test         │ Complete │ Tests: 15 passed, 15 total      │
│     │                  │          │ Time: 3.421s                    │
│     │                  │          │ Ran all test suites.            │
└─────┴──────────────────┴──────────┴─────────────────────────────────┘

Press 'k' to kill a task, 'v' to view full output, 'q' to quit

常用操作：

按 k 然后输入任务 ID 可终止对应任务
按 v 然后输入任务 ID 可查看完整输出
按 q 退出任务列表

语言切换功能实现

若需增加语言切换（右上角中/英文，默认中文），可直接向 Claude Code 提出需求。Claude Code 会执行类似以下步骤：

创建 src/types/i18n.ts 国际化类型文件
创建 src/components/LanguageSwitch.tsx 语言切换组件
修改 src/App.tsx 和 src/components/Header.tsx 集成语言切换功能
更新 src/main.tsx 添加全局状态管理

在浏览器中可看到右上角出现语言切换按钮。若不需要该功能，可执行回滚：

按 ESC 退出当前对话
输入 /rewind 进入回滚模式
选择 1. Restore code and conversation（代码与会话一并回滚）

回滚后再次打开页面，语言切换功能会被移除。

文件系统与回滚机制

用 ls 可见除项目文件外，还有 node_modules、package-lock.json、vite.config.ts 等。其中部分由 Claude Code 创建，部分由 mkdir、npm install 等命令创建。

重要：Claude Code 只能回滚它自己写入的文件，无法回滚由外部命令产生的文件。因此不要过度依赖回滚，尤其涉及依赖安装、构建产物时。对仅由 Claude Code 改动的文件（如 index.html）回滚是安全的。

Figma 设计稿集成

现在假设你对 Claude Code 做的页面不满意，你想用 Figma 设计稿来指导开发。

在 Figma 中设计好待办应用界面
导出 PNG 图片到 Downloads 文件夹
将图片拖拽到 Claude Code 终端中（或复制图片后按 Ctrl+V 粘贴）

Claude Code 接收到图片后，会开始分析设计稿，并根据设计稿重新生成代码。

更精确的方法：使用 MCP (Model Communication Protocol)

Figma 提供官方 MCP Server，需先安装：

claude mcp add --transport http figma https://mcp.figma.com/mcp

安装 Figma MCP Server 安装成功后，重新启动 Claude Code，并执行 /mcp 命令管理 MCP 服务器。 MCP 服务器管理界面首次连接需要认证：选择 Authenticate，在浏览器中授权后，返回终端输入 /mcp figma 连接成功。 Figma MCP 认证流程 Figma MCP 授权页面 Figma MCP 连接成功然后在 Figma 中，右键选择要同步的设计稿 -> Copy/Paste as -> Copy link to selection。

将链接粘贴到 Claude Code 中，可调用 MCP 工具，例如：

figma get_design_context ...
figma get_screenshot ...

Claude Code 会获取设计稿的完整信息（包括颜色、字体、间距、组件结构等），然后精准地按照设计稿生成代码。

最终效果：浏览器中显示的页面与 Figma 设计稿几乎完全一致，连毛玻璃效果、渐变色、组件间距等细节都完美还原。

多模态与上下文管理

CLAUDE.md 文件管理

完成 Figma 集成后，每次重启 Claude Code 会丢失之前的对话与配置。

为了解决这个问题，Claude Code 提供了 CLAUDE.md 文件来持久化上下文。

CLAUDE.md 核心概念：

CLAUDE.md 是项目的「说明书」和「记忆系统」，在 Claude Code 启动时自动加载到上下文中。核心功能包括：

项目上下文提供：为 AI 提供项目背景、架构说明和技术栈信息
命令文档化：记录常用的 bash 命令、构建脚本和开发工具使用方法
代码规范定义：确立编码风格、命名约定和代码质量标准
工作流程指导：定义开发流程、测试策略和部署规范
环境配置说明：记录开发环境设置、依赖要求和特殊配置

配置位置优先级（从高到低）：

位置	路径	说明	是否提交 Git
项目根目录	`./CLAUDE.md`	推荐，团队共享	✅ 是
项目本地配置	`./CLAUDE.local.md`	个人配置，不共享	❌ 否
全局配置	`~/.claude/CLAUDE.md`	用户全局设置	❌ 否

层次化加载机制：

Claude Code 会自动加载从当前工作目录向上所有父目录中的 CLAUDE.md 文件。这适用于：

Monorepo 项目：可在子目录中放置专门的 CLAUDE.md
多模块项目：不同模块可以有各自特定的上下文加载

创建/初始化 CLAUDE.md：

在 Claude Code 会话中输入 /init 命令（不是 /memory）
Claude Code 会分析当前项目（package 文件、现有文档、配置文件、代码结构等），并生成一份针对该项目的 CLAUDE.md 初稿
生成内容通常包括：构建命令、测试说明、关键目录、检测到的编码约定等

可将 /init 视为起点而非终稿：初稿会捕捉明显模式，但可能遗漏你工作流中的细节。建议生成后人工审阅，按团队实际实践增删改。若项目已有 CLAUDE.md，再次执行 /init 会基于当前代码库建议改进。

更新 CLAUDE.md 的方式：

使用 /memory 命令在会话中快速添加内容到 CLAUDE.md
通过 /init 命令自动生成/更新基础配置（推荐使用 Opus 模型以获得更准确的分析）
定期运行配置审查，移除过时信息

编辑与查看记忆：

使用 /memory 可在会话中打开记忆文件选择器，编辑已有的项目记忆（CLAUDE.md）、用户记忆或 Auto memory 等，用于增补或整理内容
/memory 也可用于查看当前加载了哪些记忆文件

/memory 命令使用示例：

# 查看和管理记忆文件
/memory

# 输出示例：
Memory Files:
┌──────────────────────┬──────────┬─────────────────────────────────┐
│ Type                 │ Status   │ Location                        │
├──────────────────────┼──────────┼─────────────────────────────────┤
│ Project Memory       │ Loaded   │ ./CLAUDE.md                     │
│ User Memory          │ Loaded   │ ~/.claude/user-memory.md        │
│ Auto Memory          │ Active   │ (session-based)                 │
└──────────────────────┴──────────┴─────────────────────────────────┘

Options:
1. Edit project memory (CLAUDE.md)
2. Edit user memory
3. View auto memory
4. Clear auto memory
5. Exit

# 选择 1 会在默认编辑器中打开 CLAUDE.md
# 选择 3 可查看当前会话中自动记录的上下文

使用要点：

将 CLAUDE.md 放在项目根目录，或放在 .claude/CLAUDE.md
每次启动 Claude Code 会自动读取并加载该文件
可在文件末尾添加自定义说明（如 Happy Coding!）

修改 CLAUDE.md 后重启 Claude Code 即可生效；输入 /memory 可确认当前加载的记忆文件。

扩展思考与模型选择

Think Hard 模式

Claude Code 支持扩展思考功能，可以通过 Tab 键在会话期间切换思考的开启和关闭。

思考深度触发方式：

触发方式	思考深度	适用场景
`think`	基本扩展思考	一般性问题探索
`keep hard` / `think more` / `think a lot` / `think longer`	更深层思考	需要深入分析时
`think ultra hard`	最深层思考	最复杂问题

从扩展思考中获得最大价值的提示：

扩展思考对于复杂任务最有价值，例如：

复杂的逻辑问题
调试棘手/疑难问题
算法挑战/算法类问题

切换话题时，使用 /clear 清除上下文，让思考不受之前对话污染。

模型选择指南

模型概览：

Claude 提供多个模型版本，不同模型在能力和成本上有所差异：

模型	能力	成本	适用场景
Opus	最强	最高	最复杂问题，Sonnet 无法解决时
Sonnet	强力	中等	日常开发任务，平衡性能与成本
Haiku	快速	最低	简单任务，快速响应

选择建议：

不要使用 Opus 模型：非常贵，能力差异不大，仅在 Sonnet 4.5 解决不了的情况下才切换到 Opus 4.5 尝试
日常开发使用 Sonnet：性价比最高，适合绝大多数场景
快速简单任务使用 Haiku：如格式化代码、简单查询

成本优化技巧

核心原则：

最大化利用缓存
最小化上下文
合理切换模型

具体技巧：

一次性说清楚需求，避免频繁提问
使用引用文件，给出明确文件路径（使用 @文件名）
切换话题时使用 /clear 清除上下文
注意配置的 MCP 占用的上下文空间，及时关闭不需要的 MCP 配置
使用 --continue 参数立即跳回到最近一次的会话中
使用 --resume 参数列出过去的所有会话，从上次中断的地方继续

会话恢复对比：

命令	功能
`claude --continue`	立即跳回到最近一次的会话中
`claude --resume`	列出过去的所有会话，选择从上次中断的地方继续

常见问题与解决方案

代码生成反复改不对

问题现象： 同一个问题反复（2次及以上）改不对，或 Claude 始终理解错需求。

解决方案：

切换模型：切换到 Opus 模型尝试
提供明确反馈：给出明确的修改思路和预期效果
测试驱动：提供测试脚本或验证正确性的方法，让 Claude 先写测试
补充知识：提供知识库文档或让其互联网搜索（框架 API、技术方案选择）
Plan 模式确认：人工 Review 方案，与模型讨论架构选择，确认后才执行
技术方案先行：写好技术方案，然后在 Plan 模式中确认 Claude Code 完全理解后再执行

忘记约束条件

问题现象： Claude Code 忘记了 CLAUDE.md 中定义的约束要求。

解决方案：

适当重复重要约束：在对话中适当提及关键约束
上下文管理：建议使用 /compact 或 /clear 清理污染的上下文
趣味技巧：在 CLAUDE.md 中约束「每次回答前叫你老公」，等哪次回复不叫你了，说明需要 /clear 了（虽然是玩笑，但原理是有效的上下文检测）
Skills 封装约束：将重要规则封装成可复用的 Skill

出现大量幻觉

问题现象： Claude Code 输出完全错误的或不存在的信息。

解决方案：

切换模型：尝试 Opus 模型
验证机制：提供测试脚本或验证正确性的方法
引用要求：要求引用来源和直接引用
分步处理：将复杂任务拆分为多个子任务，逐步验证和迭代
自动验证：使用 Hooks 自动验证关键操作
并行处理：使用 subagent 先分析或并行处理不同部分

代码质量下降（「降智」）

问题现象： 出现明显的低级错误或代码质量大幅下降。

解决方案：

立即 /clear：清理污染的上下文，这是最直接的解决方法
切换模型：换一个模型尝试
重新建立上下文：明确当前任务目标，重新提供必要的上下文
增加约束：提供更多明确的编码要求和约束条件

上下文压缩与清理

随着开发进行，对话历史会越来越长，影响 Claude Code 的性能和准确性。为此，Claude Code 提供了 compact 和 clear 命令：

/compact 命令： 压缩对话历史，保留核心信息与文件引用。

# 压缩对话历史
/compact

# 输出示例：
Compacted conversation history
✓ Preserved 15 file references
✓ Preserved 3 plan summaries
✓ Compressed 127 messages into 8 key points

Summary (press ctrl+o to see full details):
  - Referenced files: index.html, App.tsx, package.json, ...
  - Plan file: ~/claude/plans/rosy-churning-rose.md
  - Key decisions: Migrated to React, Added i18n support, Integrated Figma
  - Active context: 2.3K tokens (reduced from 45K)

Press any key to continue...

适用场景：

长期项目开发，对话历史超过 100 条消息
感觉 Claude Code 响应变慢或出现"幻觉"
需要保留历史引用但释放上下文空间

/clear 命令： 清空对话历史，但保留压缩后的摘要与文件引用。

# 清空对话历史
/clear

# 输出示例：
Clear conversation history?
This will:
  ✓ Remove all conversation messages
  ✓ Keep file references and project context
  ✓ Preserve CLAUDE.md and memory files
  ✗ Cannot be undone

Options:
1. Clear and keep summary (recommended)
2. Clear everything (fresh start)
3. Cancel

# 选择 1：清空对话但保留摘要，适合开始新功能开发
# 选择 2：完全清空，适合切换到完全不同的任务

/compact vs /clear 对比：

特性	`/compact`	`/clear`
对话消息	压缩保留	完全清空
文件引用	保留	保留
计划摘要	保留	可选保留
上下文大小	显著减少	最小化
适用场景	长期项目	切换任务
可逆性	可查看摘要	不可逆

最佳实践：

每完成一个大功能后执行 /compact
切换到新项目或新功能前执行 /clear
定期检查上下文大小（Claude Code 会在接近限制时提示）

Agent Skills 与 Hooks 机制

Agent Skills（代理技能）

Agent Skills 是 Claude Code 的高级功能，允许你创建可复用的"技能"，这些技能可以在不同项目中调用。

创建 Skill 示例：每日总结

创建 claude/skills/daily-report 目录

在其中创建 SKILL.md 文件，内容如下：

name: daily-report
description: 生成每日开发进度日报，当用户想要总结今天的工作、写日报或汇报进度时使用此技能。

在 SKILL.md 中定义具体逻辑和触发条件

在 Claude Code 中输入 /skills 可查看已注册技能，输入 daily-report 即可触发，自动生成当日开发总结。

/skills 命令输出示例：

# 查看已注册的技能
/skills

# 输出示例：
Available Skills:
┌────────────────────┬──────────────────────────────────────────────┬──────────┐
│ Name               │ Description                                  │ Scope    │
├────────────────────┼──────────────────────────────────────────────┼──────────┤
│ daily-report       │ 生成每日开发进度日报，当用户想要总结今天的   │ Project  │
│                    │ 工作、写日报或汇报进度时使用此技能           │          │
├────────────────────┼──────────────────────────────────────────────┼──────────┤
│ code-review        │ 对代码进行全面审查，检查规范、安全性和可维护 │ User     │
│                    │ 性问题                                       │          │
├────────────────────┼──────────────────────────────────────────────┼──────────┤
│ frontend-design    │ 创建独特的、生产级前端界面，具有高设计质量   │ User     │
└────────────────────┴──────────────────────────────────────────────┴──────────┘

Usage:
  /skills <skill-name>  - Execute a skill
  /skills list          - Show this list
  /skills create        - Create a new skill

# 执行技能
/skills daily-report

# 或直接输入技能名称
daily-report

Skill 与普通请求的区别：

Skill 是预定义的、结构化的任务模板
普通请求是临时的、一次性的指令
Skill 可以被多次调用，且上下文独立

Hooks（钩子）

Hooks 允许你在特定事件发生时自动执行命令，实现自动化工作流。

/hooks 命令完整交互流程：

# 管理 Hooks
/hooks

# 输出示例：
Hooks Management:
┌────┬─────────────────┬──────────────┬─────────────────────────────┬──────────┐
│ ID │ Event           │ Matcher      │ Command                     │ Scope    │
├────┼─────────────────┼──────────────┼─────────────────────────────┼──────────┤
│ 1  │ PostToolUse     │ WriteEdit    │ prettier --write {file}     │ Project  │
│ 2  │ PreToolUse      │ Bash         │ echo "Running: {command}"   │ User     │
└────┴─────────────────┴──────────────┴─────────────────────────────┴──────────┘

Options:
1. Create new hook
2. Edit hook
3. Delete hook
4. Enable/Disable hook
5. Exit

# 选择 1 创建新 Hook

创建 Hook 示例：代码格式化

# 步骤 1：选择事件类型
Select hook event:
1. PreToolUse - Before tool execution
2. PostToolUse - After tool execution
3. OnError - When an error occurs
4. OnSuccess - When operation succeeds

> 2

# 步骤 2：设置匹配器（指定触发条件）
Enter matcher (tool name or pattern):
Examples:
  - WriteEdit (matches Write and Edit tools)
  - Bash (matches all bash commands)
  - * (matches everything)

> WriteEdit

# 步骤 3：设置命令
Enter command to execute:
Available variables:
  {file} - File path
  {command} - Original command
  {output} - Command output

> jq -r '.tool_input.file_path' | xargs prettier --write

# 步骤 4：选择作用域
Select scope:
1. Project settings (local) - Only this project
2. User settings - All your projects
3. Global settings - All users (not recommended)

> 1

✓ Hook created successfully!
  Event: PostToolUse
  Matcher: WriteEdit
  Command: jq -r '.tool_input.file_path' | xargs prettier --write
  Scope: Project (.claude/settings.local.json)

Hook 工作示例：

创建单行 HTML 的 test.html：

<!DOCTYPE html><html><head><title>Test</title></head><body><h1>Hello World!</h1><p>This is a test page.</p></body></html>

Claude Code 执行 Write(test.html) 后，Hook 会自动将文件格式化为多行：

<!DOCTYPE html>
<html>
  <head>
    <title>Test</title>
  </head>
  <body>
    <h1>Hello World!</h1>
    <p>This is a test page.</p>
  </body>
</html>

Hook 的三种作用域：

Project settings (local)：仅对当前项目生效，配置文件保存在 .claude/settings.local.json
User settings：对当前用户所有项目生效，配置文件保存在 ~/.claude/settings.json
Global settings：全局生效（不推荐，容易冲突）

MCP Server 与 Figma 集成深度

Figma MCP 的认证与使用流程如下：

认证：通过 /mcp 连接 Figma Server，在浏览器中完成授权。
工具：连接成功后 /mcp figma 会列出可用工具，常用包括：

工具	说明
`get_screenshot`	获取设计稿截图
`get_design_context`	获取设计上下文（颜色、字体、间距等）
`create_design_system_rules`	创建设计系统规范
`get_metadata`	获取元数据
`get_variable_defs`	获取变量定义

典型工作流：在 Figma 中设计界面 → 右键选区选择 Copy link to selection → 在 Claude Code 中粘贴链接并调用 figma get_design_context、figma get_screenshot → Claude Code 根据设计稿生成代码。

高级功能扩展与定制

Agent 与 SubAgent 机制

Agent 概念

Agent 是 Claude Code 的高级功能，可以理解为一个"子智能体"，用于处理特定类型的复杂任务。它有自己的角色定义、工具集和工作流程。

/agent 命令完整交互流程：

# 创建和管理 Agent
/agent

# 输出示例：
Agent Management:
┌────┬─────────────────┬──────────────────────────────────────────┬──────────┐
│ ID │ Name            │ Description                              │ Scope    │
├────┼─────────────────┼──────────────────────────────────────────┼──────────┤
│ 1  │ code-reviewer   │ 代码审查专家，检查规范和最佳实践         │ Project  │
│ 2  │ test-writer     │ 自动编写单元测试和集成测试               │ User     │
└────┴─────────────────┴──────────────────────────────────────────┴──────────┘

Options:
1. Create new agent
2. Edit agent
3. Delete agent
4. Test agent
5. Exit

# 选择 1 创建新 Agent

创建 Agent 示例：代码审查员

# 步骤 1：选择创建位置
Select agent scope:
1. Project scope (.claude/agents/) - Only this project
2. User scope (~/.claude/agents/) - All your projects

> 1

# 步骤 2：选择创建方法
Select creation method:
1. Generate with Claude (recommended) - AI-assisted configuration
2. Manual configuration - Edit JSON directly

> 1

# 步骤 3：描述 Agent 职责
Describe the agent's role and responsibilities:
(Be specific about when and how this agent should be invoked)

> 这是一个代码审查的 agent，当用户要求代码审查的时候调用它。
> 它应该检查代码规范、安全性、性能和可维护性问题。

Generating agent configuration...

✓ Agent created successfully!

Agent Configuration:
  Name: code-reviewer
  Description: 当用户请求代码审查时，此代理将根据团队约定的规范对代码进行审查
  Model: sonnet
  Color: green

Tools enabled:
  ✓ Read-only tools (Read, Glob, Grep)
  ✓ Analysis tools (WebSearch, WebFetch)
  ✗ Edit tools (disabled for safety)
  ✗ Execution tools (disabled for safety)

Triggers:
  - "代码审查"
  - "审查代码"
  - "code review"
  - "review my code"

Configuration saved to: .claude/agents/code-reviewer/agent.json

生成的配置文件示例（agent.json）：

{
  "name": "code-reviewer",
  "description": "当用户请求代码审查时，此代理将根据团队约定的 JS 和 CSS 规范对代码进行审查",
  "model": "sonnet",
  "color": "green",
  "systemPrompt": "你是一位资深代码审查专家，具备软件工程最佳实践、代码质量、安全性与可维护性方面的专业知识。",
  "tools": {
    "read": true,
    "glob": true,
    "grep": true,
    "webSearch": true,
    "edit": false,
    "bash": false
  },
  "triggers": [
    "代码审查",
    "审查代码",
    "code review"
  ],
  "autoInvoke": true
}

Claude Code 会自动生成 Agent 配置文件，包含：

name: code-reviewer
description: "当用户请求代码审查时，此代理将根据团队约定的 JS 和 CSS 规范对代码进行审查"
model: sonnet
color: green
工具配置（Read-only tools, Edit tools, Execution tools 等）

SubAgent 机制

SubAgent 是 Agent 的子类型，专门用于在用户明确要求时触发，例如当用户说"代码审核"、"审查我的代码"时自动调用。

关键区别：

Agent Skill：共享主对话上下文，适合日常开发任务（如每日总结）
SubAgent：独立上下文，适合专业性任务（如代码审查），不会污染主对话

创建名为 code-reviewer 的 SubAgent 时，可设置绿色背景、角色描述为「资深代码审查专家，具备软件工程最佳实践、代码质量、安全性与可维护性方面的专业知识」。

启动后输入「给我做下代码审核」，Claude Code 会调用该 SubAgent 进行审查，并输出报告，包括：

代码规范检查（JS/TS/CSS）
安全性问题
可维护性建议
具体修改建议

Plugin 机制

Plugin 是 Claude Code 的插件系统，可以将多个 Skill、SubAgent 和 Hook 打包成一个可复用的模块，类似于 macOS 的 DMG 或 Windows 的 EXE 文件。

安装 Plugin 示例：frontend-design

输入 /plugin 命令
切换到 Discover 标签页
搜索 frontend-design
查看插件详情：
- 作者：Anthropic
- 功能：创建独特的、生产级前端界面，具有高设计质量
- 包含的 Skill：frontend-design
- 安装范围：用户级（user scope）或项目级（project scope）
选择安装范围：
- Install for you (user scope)：对当前用户所有项目生效
- Install for all collaborators on this repository (project scope)：仅对当前项目生效
- Install for you, in this repo only (local scope)：仅对当前项目本地生效

选择"对当前用户生效"并安装后，重启 Claude Code。

Plugin 的工作原理：

实际上是安装了一个 Agent Skill
包含预定义的工具集（如 Figma MCP 工具）
可以被其他 Agent 或 SubAgent 调用
支持版本管理和更新

安装 frontend-design 后，在 /skills 中会出现 frontend-design。请求「按照 frontend-design 的要求做一个待办软件，使用 HTML 实现」时，Claude Code 会调用该插件，生成符合设计规范的代码，例如：

精美的毛玻璃效果
渐变色背景
响应式布局
符合设计系统的组件样式

Custom Command（自定义命令）

Custom Command 是预先定义好的命令，需要手动触发。

创建自定义命令：

在项目根目录创建 .claude/commands/ 目录（如果不存在）

在该目录下创建命令文件，如 review.md：

---
name: review
description: 对当前更改进行代码审查
---
请审查以下更改：
1. 检查代码是否符合团队编码规范
2. 检查是否有潜在的安全问题
3. 检查是否有性能优化空间
4. 提供具体的修改建议

在 Claude Code 会话中输入 /review 即可触发该命令

使用场景：

团队常用的代码审查流程
标准化的部署准备检查
重复性的文档生成任务

Rules（规则文件夹）

Rules 文件夹包含 .md 文件，其中包含 Claude 应该始终遵循的最佳实践。这是一种模块化的规则管理系统。

两种组织方式：

方式	描述	适用场景
单个文件	所有内容在一个文件中	小型项目，规则简单
Rules 文件夹	按关注点分组的模块化 `.md` 文件	大型项目，规则复杂

Rules 文件夹结构示例：

~/.claude/rules/
  security.md      # 不要硬编码密钥，验证输入
  coding-style.md  # 不可变性，文件组织
  testing.md       # TDD 工作流，70% 覆盖率
  git-workflow.md  # 提交格式，MR 流程
  agents.md        # 何时委派给 subagents
  performance.md   # 模型选择，上下文管理

示例规则内容：

# coding-style.md

团队代码风格规则：
- 代码库中不使用表情符号
- 前端避免使用紫色色调
- 部署前始终测试代码
- 优先考虑模块化代码而不是超大文件
- 永远不要提交 console.logs
- 单个文件不要超过 2000 行，单个方法不要超过 150 行
- 使用 2 空格缩进
- 使用单引号

规则加载优先级： 项目规则 > 用户全局规则

Rules 与 Skills 的区别：

Rules：自动生效的规则，不需要手动调用
Skills：需要手动触发或由 AI 根据描述主动调用
Rules 更适合强制性的、必须遵守的规范
Skills 更适合可选的工作流程和任务模板

多 Claude 协作

Git Worktree

Git Worktree 是一个非常实用的工具，适合多个独立任务的开发。它是多检出（多个分支同时工作）的轻量替代方案。

工作原理：

Git Worktree 允许你将同一仓库的多个分支检出到不同目录。每个 worktree 有独立工作目录和文件，但历史和 reflog 共享。

使用场景：

用 Git Worktree 可让你同时在项目不同部分运行多个 Claude，每个专注于独立任务：

一个 Claude 重构认证系统
另一个构建数据可视化组件

任务互不干扰，各自高效推进，无需等待或处理冲突。

操作步骤：

# 1. 创建 worktree
git worktree add .worktree/quality_feature

# 2. 在每个 worktree 启动独立的 Claude
cd .worktree/quality_feature && claude

# 3. 按需创建更多 worktree（在新终端标签页重复 1-2 步）

# 4. 完成后清理
git worktree remove .worktree/quality_feature

使用建议：

每个 worktree 保持一个终端标签页
不同 worktree 用不同 IDE 窗口
Claude Code 可以自主解决合并和冲突

规范驱动开发（Spec-Driven Development, SDD）

理念概述

Spec KIT 采用「意图主导开发」的理念，将稳定的「做什么」与灵活的「怎么做」分离。

核心创新：

规范成为可执行文件，直接生成工作实现
不仅仅是指导实现，而是能够直接生成实现的可执行源头
从「代码是王者」的传统模式转向「规范成为主导」的新模式

四阶段流程

┌─────────────────────────────────────────────────────────────┐
│                     Spec KIT 流程                             │
├──────────────┬──────────────┬──────────────┬───────────────┤
│  1. Specify  │   2. Plan    │   3. Tasks   │  4. Implement │
│   （规范）    │   （计划）    │   （任务）    │   （实现）     │
├──────────────┼──────────────┼──────────────┼───────────────┤
│ 提供高层级描述│ 提供技术栈和  │ 将规范和计划  │ AI 按顺序执行  │
│ AI 生成详细  │ 架构约束      │ 分解为具体    │ 任务，开发者   │
│ 规范，关注    │ AI 生成综合  │ 可测试的      │ 审查聚焦的变更 │
│ 用户旅程和体验│ 技术计划      │ 任务块        │               │
└──────────────┴──────────────┴──────────────┴───────────────┘

Specify（规范）：提供高层级描述，AI 生成详细规范，关注用户旅程和体验
Plan（计划）：提供技术栈和架构约束，AI 生成综合技术计划
Tasks（任务）：将规范和计划分解为具体的、可测试的任务块
Implement（实现）：AI 按顺序执行任务，开发者审查聚焦的变更

核心原则

闭环（Closing the Loop）：

自我验证、测试和迭代是高效 AI 辅助编程的关键。AI 必须能够：

编译代码
运行测试
执行程序
验证输出

这个机制确保生成的代码不是空中楼阁，而是实际可运行的。

MCP Server 实用集成示例

除了前面介绍的 Figma MCP，这里补充更多实用的 MCP Server 集成示例。

GitLab MCP

用于连接 GitLab 仓库，进行代码审查、PR 管理等操作。

claude mcp add git_mcp -s project \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=xxxxxxx \
  -e GITLAB_API_URL=https://git.example.com \
  -e GITLAB_READ_ONLY_MODE=true \
  -- npx @zereight/mcp-gitlab

MySQL MCP

连接 MySQL 数据库，允许 Claude Code 直接查询数据库结构和内容。

npx -y @benborla29/mcp-server-mysql@2.0.3

Jina MCP

获取 URL 内容和网页搜索，适合爬取网页内容或快速搜索信息。

claude mcp add --transport sse jina https://mcp.jina.ai/sse \
  --header "Authorization : Bearer xxxxx"

Context7 MCP

获取语言 API 的上下文信息。

npx -y @upstash/context7-mcp

Playwright MCP

操作浏览器进行自动化测试、网页截图等。

npx -y @playwright/mcp@latest --extension

Lark MCP

获取飞书文档内容，适合将飞书知识库集成到开发流程中。

npx -y @larksuiteoapi/lark-mcp

Jira MCP

操作 Jira 进行任务管理。

pip install g7-jira-mcp -i https://mirrors.aliyun.com/pypi/simple
claude mcp add jira-mcp -s user \
  -e JIRA_USERNAME=xxx \
  -e JIRA_PASSWORD=xxx \
  -- g7-jira-mcp --transport stdio

MCP 管理注意事项：

注意配置的 MCP 占用的上下文空间，及时关闭不需要的 MCP 配置
使用 /mcp 命令查看已安装的 MCP 服务器
可以按需启用或禁用 MCP 服务器

安装 Plugin 示例：frontend-design

输入 /plugin 命令
切换到 Discover 标签页
搜索 frontend-design
查看插件详情：
- 作者：Anthropic
- 功能：创建独特的、生产级前端界面，具有高设计质量
- 包含的 Skill：frontend-design
- 安装范围：用户级（user scope）或项目级（project scope）
选择安装范围：
- Install for you (user scope)：对当前用户所有项目生效
- Install for all collaborators on this repository (project scope)：仅对当前项目生效
- Install for you, in this repo only (local scope)：仅对当前项目本地生效

选择“对当前用户生效”并安装后，重启 Claude Code。

Plugin 的工作原理：

实际上是安装了一个 Agent Skill
包含预定义的工具集（如 Figma MCP 工具）
可以被其他 Agent 或 SubAgent 调用
支持版本管理和更新

精美的毛玻璃效果
渐变色背景
响应式布局
符合设计系统的组件样式

综合实战：完整待办应用

可将上述能力组合，搭建完整待办应用：

基础结构：使用 frontend-design 插件生成专业 UI
功能实现：通过 Agent Skills 添加任务管理、优先级标记等功能
国际化：使用 SubAgent 实现中英文切换
代码质量：使用 code-reviewer SubAgent 进行最终审查
自动化：通过 Hooks 实现保存时自动格式化

最终效果：一个功能完整、设计精美、代码规范的待办应用，完全由 Claude Code 自动生成。

常用命令速查表

基础命令

命令	说明	示例
`/login`	登录 Claude Code	`/login`
`/help`	查看帮助	`/help` 或 `?`
`!command`	执行系统命令	`!open index.html`
`Shift + Tab`	切换模式	在默认/自动/规划模式间切换
`Shift + Enter`	多行输入	输入多行需求
`Ctrl + g`	在 VS Code 中编辑	编辑大段文本
`Ctrl + b`	后台运行	将当前进程放到后台
`ESC`	退出当前对话	返回主界面

会话管理

命令	说明	示例
`/rewind`	回滚代码和会话	`/rewind`
`/compact`	压缩对话历史	`/compact`
`/clear`	清空对话历史	`/clear`
`/tasks`	查看后台任务	`/tasks`
`/config`	查看和修改配置	`/config`
`/status`	查看当前会话状态	`/status`

会话恢复

命令	说明	示例
`--continue`	立即跳回到最近一次会话	`claude --continue`
`--resume`	列出所有历史会话选择恢复	`claude --resume`

上下文管理

命令	说明	示例
`/init`	初始化 CLAUDE.md	`/init`
`/memory`	管理记忆文件	`/memory`

高级功能

命令	说明	示例
`/mcp`	管理 MCP 服务器	`/mcp`
`/skills`	查看和管理技能	`/skills`
`/hooks`	管理钩子	`/hooks`
`/agent`	创建和管理 Agent	`/agent`
`/plugin`	管理插件	`/plugin`

启动参数

参数	说明	示例
`--dangerously-skip-permissions`	跳过权限确认	`claude --dangerously-skip-permissions`
`--model`	指定模型	`claude --model sonnet`

最佳实践

开发工作流建议

1. 项目初始化

# 创建项目目录
mkdir my-project && cd my-project

# 启动 Claude Code
claude

# 初始化项目上下文
/init

2. 日常开发

使用自动模式提高效率：按 Shift + Tab 切换到自动模式，减少重复确认
定期压缩上下文：每完成一个大功能后执行 /compact，保持对话清晰
重要节点使用 Git：不要完全依赖 /rewind，重要变更前先提交 Git
合理使用后台任务：开发服务器用 Ctrl + b 放到后台，用 /tasks 管理

3. 复杂任务处理

先规划再执行：按 Shift + Tab 进入规划模式，讨论方案后再实施
确认计划细节：在执行前仔细审查 Claude Code 的计划，必要时补充需求
分步骤验证：大功能分阶段完成，每个阶段验证后再继续
使用 Task 工具：创建任务列表，跟踪进度

4. 团队协作

共享项目上下文：将 CLAUDE.md 提交到版本控制，团队成员共享项目知识
统一 Skills 和 Agents：在项目级别创建 Skills 和 Agents，确保团队使用一致的工作流
使用 Project scope 安装插件：团队共用的插件选择 Project scope 安装
使用 Git Worktree：多个 Claude 并行工作，互不干扰

5. 上下文管理策略

# 项目启动时
/init                    # 初始化项目上下文

# 开发过程中
/memory                  # 定期查看和更新记忆文件
/compact                 # 每完成一个功能后压缩对话

# 出现降智或偏离正确方向时
/clear                   # 立即清理上下文

# 切换模型时
# 使用 --model 指定模型
claude --model sonnet

# 切换任务时
/clear                   # 清空对话，开始新任务

# 项目结束时
/memory                  # 更新项目文档，记录关键决策

安全建议

⚠️ 权限管理

生产环境避免跳过权限：--dangerously-skip-permissions 仅在开发环境使用
敏感操作手动确认：删除文件、修改配置等操作始终手动确认
审查终端命令：Claude Code 执行的命令可能影响系统，执行前仔细审查

🔒 代码安全

重要变更前提交 Git：使用 Git 作为主要的版本控制工具，不依赖 /rewind
审查生成的代码：AI 生成的代码可能存在安全漏洞，部署前进行代码审查
保护敏感信息：不要在对话中包含密码、API 密钥等敏感信息

📝 最佳实践清单

✅ 项目开始时执行 /init 创建 CLAUDE.md
✅ 定期执行 /compact 压缩对话历史
✅ 重要节点提交 Git，不完全依赖 /rewind
✅ 使用规划模式讨论复杂方案
✅ 团队共享 CLAUDE.md 和项目级 Skills
✅ 遇到代码反复改不对时先写测试验证
✅ 当 Claude 偏离方向或降智时立即 /clear
✅ 合理选择模型，日常使用 Sonnet，必要时用 Opus
❌ 不在生产环境使用 --dangerously-skip-permissions
❌ 不在对话中包含敏感信息
❌ 不要盲目使用 Opus 模型（成本高且能力差异不大）
❌ 不盲目执行 Claude Code 建议的命令

🔍 定期审查

# 查看 Claude Code 的操作历史
/tasks                   # 查看后台任务
/memory                  # 查看记忆文件
/hooks                   # 审查自动化钩子
/agent                   # 审查 Agent 配置
/commands                # 查看自定义命令
/config                  # 查看配置设置
/mcp                     # 查看 MCP 服务器状态

成本优化清单

✅ 一次性说清楚需求，避免频繁提问
✅ 使用 @文件名 引用文件，减少上下文中的文件内容
✅ 最大化利用缓存，避免重复请求
✅ 切换话题时使用 /clear 清除上下文
✅ 日常开发使用 Sonnet 模型
✅ 及时关闭不需要的 MCP 配置
❌ 不要滥用 Opus 模型
❌ 不要在不必要时加载大量无关文件到上下文

总结与展望

本教程覆盖 Claude Code 的四大能力：基础交互（三种模式）、复杂任务（终端与后台任务）、多模态与上下文（CLAUDE.md、Figma MCP）、高级扩展（Agent Skill、SubAgent、Plugin）。其他编程 Agent（如 Cursor、OpenCode）在用法上类似，可举一反三。

可期方向：多模态（音视频）、更智能的上下文与插件生态、与更多设计工具的集成。Claude Code 适合作为生产力辅助，处理重复性工作，让你更聚焦创造性部分。

文档结构概览​

内容目录​

第 1 部分：环境搭建与基础交互​

第 2 部分：复杂任务处理与终端控制​

第 3 部分：多模态与上下文管理​

第 4 部分：高级功能扩展与定制​

环境搭建与基础交互​

安装 Claude Code​

登录与授权​

第一个本地任务​

待办软件初版​

工作流与模式运用​

工作流基础操作​

代码库理解与问答​

TDD 工作流​

待办软件实战与模式运用​

规划模式下的计划确认​

终端权限控制​

后台任务管理​

语言切换功能实现​

文件系统与回滚机制​

Figma 设计稿集成​

多模态与上下文管理​

CLAUDE.md 文件管理​

扩展思考与模型选择​

Think Hard 模式​

模型选择指南​

成本优化技巧​

常见问题与解决方案​

代码生成反复改不对​

忘记约束条件​

出现大量幻觉​

代码质量下降（「降智」）​

上下文压缩与清理​

Agent Skills 与 Hooks 机制​

Agent Skills（代理技能）​

Hooks（钩子）​

MCP Server 与 Figma 集成深度​

高级功能扩展与定制​

Agent 与 SubAgent 机制​

Agent 概念​

SubAgent 机制​

Plugin 机制​

Custom Command（自定义命令）​

Rules（规则文件夹）​

多 Claude 协作​

Git Worktree​

规范驱动开发（Spec-Driven Development, SDD）​

理念概述​

四阶段流程​

核心原则​

MCP Server 实用集成示例​

GitLab MCP​

MySQL MCP​

Jina MCP​

Context7 MCP​

Playwright MCP​

Lark MCP​

Jira MCP​

综合实战：完整待办应用​

常用命令速查表​

基础命令​

会话管理​

会话恢复​

上下文管理​

高级功能​

启动参数​

最佳实践​

开发工作流建议​

安全建议​

成本优化清单​

总结与展望​

文档结构概览

内容目录

第 1 部分：环境搭建与基础交互

第 2 部分：复杂任务处理与终端控制

第 3 部分：多模态与上下文管理

第 4 部分：高级功能扩展与定制

环境搭建与基础交互

安装 Claude Code

登录与授权

第一个本地任务

待办软件初版

工作流与模式运用

工作流基础操作

代码库理解与问答

TDD 工作流

待办软件实战与模式运用

规划模式下的计划确认

终端权限控制

后台任务管理

语言切换功能实现

文件系统与回滚机制

Figma 设计稿集成

多模态与上下文管理

CLAUDE.md 文件管理

扩展思考与模型选择

Think Hard 模式

模型选择指南

成本优化技巧

常见问题与解决方案

代码生成反复改不对

忘记约束条件

出现大量幻觉

代码质量下降（「降智」）

上下文压缩与清理

Agent Skills 与 Hooks 机制

Agent Skills（代理技能）

Hooks（钩子）

MCP Server 与 Figma 集成深度

高级功能扩展与定制

Agent 与 SubAgent 机制

Agent 概念

SubAgent 机制

Plugin 机制

Custom Command（自定义命令）

Rules（规则文件夹）

多 Claude 协作

Git Worktree

规范驱动开发（Spec-Driven Development, SDD）

理念概述

四阶段流程

核心原则

MCP Server 实用集成示例

GitLab MCP

MySQL MCP

Jina MCP

Context7 MCP

Playwright MCP

Lark MCP

Jira MCP

综合实战：完整待办应用

常用命令速查表

基础命令

会话管理

会话恢复

上下文管理

高级功能

启动参数

最佳实践

开发工作流建议

安全建议

成本优化清单

总结与展望