Claude Code 使用指南
本文档整合了 Claude Code 的核心功能和使用技巧，帮助您更高效地使用 Claude Code 进行开发工作。
目录
1. 引用文件和目录
1.1 基本概念
使用 @ 快速包含文件或目录，无需等待 Claude 读取它们。这是 Claude Code 的核心功能之一，能够显著提升交互效率。
1.2 使用方法
1.2.1 引用单文件
要引用单文件，请使用 @ 符号后跟文件路径。例如：
> Explain the logic in @project_core_backend/app/admin/route/api.php1.2.2 引用目录
要引用目录，请使用 @ 符号后跟目录路径。例如：
> What's the structure of @project_core_backend/app/services1.2.3 引用多个文件或目录
要引用多个文件或目录，请在 @ 符号后列出多个路径，用空格分隔。例如：
> Show me the code in @project_core_backend/app/admin/route/api.php and @project_core_backend/app/model/BrandModel.php1.2.4 使用图像
@docs\pic\企业微信截图_17635533767553.png 根据这张图，生成一个html，放在 @docs\ 里1.3 路径说明
特别提示：
- 文件路径可以是相对的或绝对的。
1. 相对路径是相对于项目根目录的。例如：
@project_core_backend/app/admin/route/api.php
2. 绝对路径是从项目根目录开始的完整路径。例如：
- Linux/Mac:
@/Users/you/project/src/utils/auth.js
- Windows:
@E:\project\project_core_backend\app\services\customer\BrandServices.php- 引用的文件或目录必须存在于项目中。
- 引用的目录将显示其内容列表，而不是内容本身。
1.4 @ 符号使用和不使用的区别
text
@引用流程：用户输入 → 按需自动读取 → 内容直接注入上下文 → 发送给Claude
手动流程：用户输入 → 发送给Claude → Claude理解 → 调用工具 → 工具返回 → Claude处理1.5 @ 符号对 Token 的影响
Token 消耗情况
CLAUDE.md 文件本身 ✅
- CLAUDE.md 文件会在每次对话时作为系统指令加载
- 文件中的所有内容（包括文件路径引用）都会消耗 token
- 约 207 行的文件，消耗 token 量相对较小
文件路径引用 ✅ 影响很小
- 路径只是文本字符串，占用的 token 很少
- 不会自动加载这些文件的实际内容
实际文件内容 ❌ 不会自动加载
- 只有当使用 Read 工具明确读取文件时，文件内容才会进入上下文
- 例如：只有执行 Read 时，该文件内容才会消耗 token
1.6 使用建议
✅ 推荐使用 @ 引用的场景
- 在对话中引用文件：始终使用 @文件名 确保 Claude 准确读取
- 引用当前存在的项目文件
- 需要快速导航：方便自己和团队成员快速打开文件
- 多文件批量引用：@file1.ts @file2.ts @file3.ts
- 重要的代码模板引用：如 CLAUDE.md 中的模板文件
- 文件很大时，告诉claude code 读取的行数范围，如：@CLAUDE.md 1-10行
1.7 实际案例对比
案例 1：在对话中请求 Claude 阅读配置
❌ 不推荐："Claude，请帮我看看 CLAUDE.md 文件中的后端架构部分"
- Claude 需要先理解，再使用 Read 工具
- 可能理解偏差或延迟
✅ 推荐："@CLAUDE.md 请分析后端架构部分"
- 文件内容立即加载
- Claude 可直接引用具体行号和内容
案例 2：在 CLAUDE.md 文档中记录模板文件
❌ 不推荐：
- 控制器:
app/admin/controller/customer/Brand.php
✅ 推荐：
- 控制器: @project_core_backend/app/admin/controller/customer/Brand.php
2. 检查点 - 快速恢复更改
Claude Code 自动跟踪 Claude 的文件编辑，允许快速撤销更改并回退到之前的状态。
2.1 自动跟踪机制
- 每个用户提示创建一个新检查点，捕获编辑前的代码状态（修改时间戳或内容哈希）
- 保存文件时，Claude 会检查文件是否在此期间被外部修改，防止数据丢失或内容混乱
- 检查点在会话之间持久存在，可在恢复的对话中访问
- 30 天后自动清理（可配置，编辑前会保存一份文件的临时快照）
2.2 如何回退
按两次 Esc（Esc + Esc）或使用 /rewind 命令打开回退菜单，可选择：
- 仅对话：回退用户消息，保留代码更改
- 仅代码：恢复文件更改，保留对话
- 代码和对话：将两者都恢复到先前点
2.3 使用场景
- 探索不同实现方法而不丢失起点
- 快速撤销引入错误的更改
- 进行变体实验，随时恢复到工作状态
2.4 重要限制
- Bash 命令更改未被跟踪：通过 bash 执行的文件操作（rm、mv、cp 等）无法回退
- 外部更改未被跟踪：仅跟踪当前会话中已编辑的文件，手动修改和其他会话的编辑通常不会被捕获
- 不是版本控制替代品：检查点用于快速会话级恢复，永久历史和协作仍需使用 Git 等版本控制工具
3. 历史会话管理
3.1 命令行方式
Claude Code 提供两个选项来恢复之前的对话：
--continue自动继续最近的对话--resume显示对话选择器
3.1.1 工作原理
- 对话存储：所有对话都自动保存在本地，包含其完整的消息历史
- 消息反序列化：恢复时，整个消息历史被恢复以维护上下文
- 工具状态：来自之前对话的工具使用和结果被保留
- 上下文恢复：对话以所有之前的上下文完整恢复
3.1.2 启动示例
bash
# 继续最近的对话
claude --continue
# 使用特定提示继续最近的对话
claude --continue --print "Show me our progress"
# 显示对话选择器
claude --resume
# 在非交互模式下继续最近的对话
claude --continue --print "Run the tests again"3.1.3 启动后示例
bash
# 继续最近的对话
/continue
# 显示对话选择器
/resume
# 导出当前对话
先用 /resume 选择要导出的会话,然后输入 /export3.2 图形化界面方式
- 桌面端开源 GUI 应用 Claudia (https://getclaudia.org/)
- VS Code 插件 Claude Code Chat
3.3 删除会话
修改 history.jsonl 文件，删除对应的会话索引
文件位置：
- Windows:
C:/Users/用户名/.claude/history.jsonl - macOS:
~/.claude/history.jsonl
文件格式： history.jsonl 文件是一个 jsonl 文件，每个 json 对象占一行。删除会话时，需要删除对应的 json 对象。
json
{
"display":"/export ",
"pastedContents":{},
"timestamp":1764292341104,
"project":"E:\\project",
"sessionId":"882b5e09-73e3-44a8-9241-cd7c0da0f983"
}提示：
- 这个历史只是对话的索引
- 实际的对话内容存储在
C:\Users\用户名\.claude\projects\claudecode启动目录\{sessionId}.json文件中
4. Agent Skills 配置和使用
4.1 什么是 Agent Skills？
Agent Skills 将专业知识打包成可发现的功能。每个 Skill 包含一个 SKILL.md 文件，其中包含 Claude 在相关时读取的说明，以及可选的支持文件，如脚本和模板。
Skills 如何被调用： Skills 是模型调用的——Claude 根据您的请求和 Skill 的描述自主决定何时使用它们。这与斜杠命令不同，斜杠命令是用户调用的（您显式输入 /command 来触发它们）。
优势：
- 为您的特定工作流扩展 Claude 的功能
- 通过 git 在您的团队中共享专业知识
- 减少重复提示
- 为复杂任务组合多个 Skills
4.2 项目结构示例
以 PDF Skill 为例：
text
pdf/
├── README.md # 项目总览
├── SKILL.md # 主指令文档
├── FORMS.md # 表单处理指南
├── MERGE.md # PDF合并指南
├── REFERENCE.md # 完整API参考
├── requirements.txt # Python依赖
├── scripts/
│ ├── __init__.py
│ ├── utilities.py # 核心工具函数
│ ├── form_processor.py # 表单处理专用
│ ├── pdf_merger.py # PDF合并专用
│ └── cli.py # 命令行接口
├── examples/ # 使用示例
│ ├── basic_usage.py
│ ├── form_filling.py
│ └── batch_processing.py
└── tests/ # 测试文件
├── test_utilities.py
├── test_forms.py
└── test_merge.py4.3 编写方法
- AI 编写 SKILL.md 文件，描述技能的功能、使用场景和来源
- 参考文档：使用 Claude Code 构建Agent Skills
4.4 使用示例
text
> 你有哪些skill
● 根据当前环境配置，我有以下可用的 skill：
可用技能
pdf
- 功能：从 PDF 文件中提取文本和表格、填充表单、合并文档
- 使用场景：当您需要处理 PDF 文件、提取文档内容、填写表单或合并 PDF 文档时
- 来源：用户自定义
> 使用这个技能读取 @docs\keyboard-shortcuts-windows.pdf4.5 官方SKILLS市场
- 在claude code命令行中安装官方市场，直接获取几十个官方技能，参考以下示例需要手动安装
/plugin marketplace add anthropics/skills - 示例：
bash
/plugin marketplace add anthropics/skills
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Add Marketplace │
│ │
│ Enter marketplace source: │
│ Examples: │
│ • owner/repo (GitHub) │
│ • [email protected]:owner/repo.git (SSH) │
│ • https://example.com/marketplace.json │
│ • ./path/to/marketplace │
│ │
│ anthropics/skills │
│ │
│ ✻ Cloning repository: https://github.com/anthropics/skills.gitbash
> /plugin
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Discover Installed Marketplaces Errors (tab to cycle) │
│ │
│ Installed Plugins │
│ │
│ claude-plugins-official │
│ ❯ ◉ context7 user │
│ ◉ feature-dev user │
│ ◉ php-lsp user, v1.0.0 │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Space: toggle · Enter: details · Delete: uninstall · Esc: back单个安装：
bash
# 安装文档技能
npx skills-installer install @anthropics/skills/docx --client claude-code
# 查询技能
> /skills
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Skills
2 skills
User skills (/Users/***/.claude/skills)
docx · ~2.4k tokens
pdf · ~1.7k tokens
> Use the PDF skill to extract the form fields from @docs/keyboard-shortcuts-macos.pdf
⎿ Read docs/keyboard-shortcuts-macos.pdf (202.4KB)
⏺ /pdf
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Use skill "pdf"?
Claude may use instructions, code, or files from this Skill.
Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When
Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale. (user)
Do you want to proceed?
❯ 1. Yes
2. Yes, and don't ask again for pdf in /Users/***/Sites/kzh
3. No, and tell Claude what to do differently (esc)4.6 其它市场
开源社区维护的，包含有46.5K 个技能的超级市场 Claude Code Plugins https://claude-plugins.dev/skills
- 命令行中添加社区市场
bash
> /plugin marketplace add claudeforge/marketplace
⎿ Successfully added marketplace: claudeforge-marketplace- 单独安装docx技能
bash
> npx skills-installer install @anthropics/skills/docx --client claude-code
#查询技能
> /skillstext
技能详情 https://claude-plugins.dev/skills/@anthropics/skills/docx
Dependencies
Required dependencies (install if not available):
- pandoc: `sudo apt-get install pandoc` (for text extraction)
- docx: `npm install -g docx` (for creating new documents)
- LibreOffice: `sudo apt-get install libreoffice` (for PDF conversion)
- Poppler: `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images)
- defusedxml: `pip install defusedxml` (for secure XML parsing)5. MCP 服务器配置和使用
Claude Code 允许您使用 MCP（Model Context Protocol）来扩展 Claude Code 的功能。 主要的 MCP 市场/目录：
- MCP.so - 收集了 17,258 个 MCP 服务器的第三方市场 MCP
- MCPdb.org - 最大的模型上下文协议目录，拥有 10,000+ 个服务器和客户端 MCPdb
- MCPMarket.com - 连接 Claude 和 Cursor 到 Figma、Databricks、Storybook 等工具的 MCP 服务器 MCP Market
- mcpservers.org - Awesome MCP Servers 的精选集合，可搜索和发现 MCP 服务器和客户端 MCP Servers
- GitHub 官方仓库 - modelcontextprotocol/servers 仓库包含大量官方和社区 MCP 服务器 GitHub
5.1 添加 MCP 服务器
5.1.1 方法1：命令行添加
Claude Code 提供了简单的命令行工具来添加 MCP 服务器：
bash
# 基本语法
claude mcp add <名称> <命令> [参数...]示例：
bash
# 全局范围：在用户目录下安装 puppeteer 插件
claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer
# 安装 chrome-devtools-mcp
claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
# 安装 context7
claude mcp add --transport http context7 https://mcp.context7.com/mcp5.1.2 方法2：配置文件
Claude Code 也支持通过配置文件来添加 MCP 服务器。
**项目范围：**在 settings.json 中 **全局范围：**在 C:\Users\asus\.claude.json 中
添加以下内容：
json
{
"mcpServers": {
"puppeteer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-puppeteer"
],
"env": {}
}
}
}5.2 管理 MCP 服务器
bash
# 列出所有已配置的服务器
claude mcp list
# 获取特定服务器的详细信息
claude mcp get puppeteer
# 删除服务器
claude mcp remove puppeteer
# （在 Claude Code 中）检查服务器状态
/mcp示例输出：
bash
E:\project> claude mcp list
Checking MCP server health...
puppeteer: npx -y @modelcontextprotocol/server-puppeteer - ✓ Connected5.3 使用 Puppeteer MCP 工具
5.3.1 引用资源
在您的提示中键入 @ 以查看来自所有连接的 MCP 服务器的可用资源。
bash
# 爬取网页内容
@puppeteer:fetch https://www.example.com5.3.2 Puppeteer 工具列表
| No. | Name | Description | 功能说明 |
|---|---|---|---|
| 1 | puppeteer_navigate | 页面导航 | 导航到指定URL |
| 2 | puppeteer_screenshot | 屏幕截图 | 捕获当前页面、视口或特定元素的图像 |
| 3 | puppeteer_click | 点击 | 模拟鼠标点击页面上的特定元素（如按钮、链接） |
| 4 | puppeteer_fill | 填写 | 在输入框（Input/Textarea）中输入指定的文本内容 |
| 5 | puppeteer_select | 选择 | 在下拉菜单中根据值或文本选择特定选项 |
| 6 | puppeteer_hover | 悬停 | 在指定元素上悬停 |
| 7 | puppeteer_evaluate | 脚本执行 | 执行自定义 JavaScript 代码 |
5.3.3 详细功能说明
1. puppeteer_navigate (页面导航)
- 描述：这是自动化流程的起点。它不仅是简单的跳转，通常还包含"等待策略"（Wait Strategy）。
- 关键参数：url (目标网址), waitUntil (例如：等待网络空闲 networkidle0 或 DOM 加载完成 domcontentloaded)
- 场景：打开首页、跳转到登录页、刷新当前页面
2. puppeteer_screenshot (屏幕截图)
- 描述：用于调试、生成报告或验证页面状态。它可以截取整个长页面（Full Page），也可以仅截取当前可视区域。
- 关键参数：path (保存路径), fullPage (是否全屏), clip (指定裁剪区域)
- 场景：爬虫出错时保留证据、生成网页缩略图、验证UI样式
3. puppeteer_click (元素点击)
- 描述：通过选择器（Selector）定位元素并模拟用户点击。它会自动滚动页面以确保元素在视野内。
- 关键参数：selector (CSS选择器或XPath), button (左键/右键), clickCount (点击次数)
- 场景：提交表单、点击"下一页"、关闭弹窗、选择商品
4. puppeteer_fill (表单填充)
- 描述：专门用于处理文本输入。与单纯的键盘事件不同，它通常会先聚焦（Focus）元素，甚至清空已有内容后再输入。
- 关键参数：selector (输入框定位), value (填写的文本), delay (模拟打字间隔时间)
- 场景：输入用户名/密码、填写搜索关键词、填写调查问卷
5. puppeteer_select (下拉选择)
- 描述：专门针对 HTML select 标签的交互工具。它比模拟点击下拉框更稳定，直接修改选中状态。
- 关键参数：selector (下拉框定位), values (选项的 value 属性值数组)
- 场景：选择省份/城市、筛选商品分类、选择日期范围
6. puppeteer_hover (鼠标悬停)
- 描述：将鼠标移动到元素中心并保持悬停状态。这对于触发 CSS :hover 伪类或 JavaScript 动态加载的菜单至关重要。
- 关键参数：selector (目标元素)
- 场景：展开二级导航菜单、显示隐藏的工具提示（Tooltip）、触发懒加载图片
7. puppeteer_evaluate (脚本执行)
- 描述：最强大的工具（万能钥匙）。它允许你在浏览器内部运行任意 JavaScript。可以用来获取数据、修改 DOM、绕过复杂的交互逻辑。
- 关键参数：script (要执行的 JS 函数或字符串), args (传递给函数的参数)
- 场景：抓取页面上的复杂数据（Scraping）、修改页面变量、强制移除遮罩层、获取页面性能数据
5.4 实际应用示例
模拟用户新增政策：
bash
# 打开政策管理页面
@puppeteer:navigate http://localhost:5666/Policy/policy/index
# 点击按钮名称为`新增政策`的按钮
@puppeteer:click "新增政策"
# 在input的name属性为policy_title的输入框中填写`外采政策`
@puppeteer:fill [name="policy_title"] "外采政策"
# 继续完成政策类型的选择
# 填写政策详情
# 选择适用范围
# 选择生效日期
# 点击保存完整的自动化测试流程：
bash
请使用 Puppeteer 自动化测试政策管理页面：
1. @puppeteer:navigate http://localhost:5666/Policy/policy/index
2. 等待页面加载完成后，@puppeteer:screenshot "01-列表页"
3. @puppeteer:click button:has-text("新增政策")
4. 等待弹窗打开后，@puppeteer:screenshot "02-表单弹窗"
5. @puppeteer:fill input[placeholder="请输入政策标题"] "外采政策测试"
6. @puppeteer:click .ant-select:has-text("请选择政策类型")
7. @puppeteer:click .ant-select-item:first-child
8. @puppeteer:fill .w-e-text-container "这是政策详情测试内容"
9. @puppeteer:click label:has-text("全员")
10. @puppeteer:fill input[placeholder="请选择生效日期"] "2025-12-01"
11. @puppeteer:screenshot "03-填写完成"
12. @puppeteer:click button:has-text("保存")
13. 等待2秒后 @puppeteer:screenshot "04-保存结果"关键提示：
- 需要在每个步骤之间适当等待，确保页面元素已加载
- 对于复杂组件（如富文本编辑器、日期选择器），可能需要调整选择器
- 建议在关键步骤截图，便于调试
- 如果遇到动态生成的 class 名称，优先使用 placeholder、has-text() 等语义化选择器
附录
A. 文件结构
本指南整合了以下源文档：
@引用文件和目录.md- @ 符号引用文件和目录的使用方法checkpoint恢复更改.md- 检查点功能说明历史会话.md- 会话管理和恢复skill的配置和使用.md- Agent Skills 配置mcp的配置和使用.md- MCP 服务器配置
B. 相关资源
- 官方文档：https://code.claude.com/docs/zh-CN/
- Claudia GUI：https://getclaudia.org/
- GitHub Issues：https://github.com/anthropics/claude-code/issues
更新时间： 2025-01-27 文档版本： 1.0 整理者： Claude Code