Claude Code 使用手册

本手册面向 Claude Code CLI 用户，涵盖常用命令、Skill 使用技巧及最佳实践。

---

目录

1. 快速入门
2. 基本常用命令
3. Skill 使用技巧
4. 高级功能
5. 配置与个性化
6. 常见问题

---

一、快速入门

1.1 安装 Claude Code

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

1.2 启动方式

# 方式1：在项目目录中启动
cd your-project
claude

# 方式2：直接指定项目路径
claude /path/to/project

1.3 基本交互

操作	快捷键/命令	说明
发送消息	Enter	提交当前输入
多行输入	直接粘贴或连续输入	Claude Code 支持多行文本粘贴
退出	/exit 或 Ctrl+C	退出会话
查看帮助	/help	显示所有可用命令

注意：Claude Code CLI 基于终端，不支持 Shift+Enter 换行。如需输入多行内容，可直接粘贴完整文本，或先在外部编辑器写好再粘贴。

---

二、基本常用命令

2.1 内置命令

命令	说明	示例
/status	查看当前模型和配置状态	/status
/help	显示帮助信息	/help
/clear	清除当前对话历史	/clear
/compact	压缩对话历史以节省上下文	/compact
/exit	退出 Claude Code	/exit

2.2 文件操作命令

命令/操作	说明	示例
@文件名	引用指定文件	@src/main.py
@文件夹/	引用整个文件夹	@src/
@#行号	引用文件特定行	@src/main.py#10-20
查看文件	让 Claude 读取文件内容	查看 src/main.py 的内容
修改文件	让 Claude 编辑文件	修改 src/main.py，添加注释

2.3 代码操作命令

操作	说明	示例
解释代码	解释当前代码逻辑	解释这段代码的作用
重构代码	改进代码结构和质量	重构这个函数，使其更易读
添加注释	为代码添加文档注释	为这段代码添加详细注释
生成测试	创建单元测试	为 UserService 类生成单元测试
查找错误	分析和修复 Bug	这段代码有什么问题？

2.4 终端命令执行

Claude Code 可以直接在终端执行命令：

运行 npm install
执行 git status
查看当前目录下的所有文件

2.5 Git 相关操作

操作	示例
查看 Git 状态	查看 git 状态
提交代码	提交当前更改，消息是：修复登录bug
查看提交历史	查看最近的提交记录
创建分支	创建新分支 feature/login

---

三、Skill 使用技巧

3.1 什么是 Skill

Skill 是存储在 .cursor/skills/ 或 ~/.cursor/skills/ 下的 Markdown 文件，用于教 AI 如何完成特定任务。

3.2 Skill 目录结构

skill-name/
├── SKILL.md         # 必填，主说明文档
├── reference.md     # 可选，详细参考文档
├── examples.md      # 可选，使用示例
└── scripts/         # 可选，配套脚本
    └── helper.py

3.3 创建自定义 Skill

步骤 1：创建目录

mkdir -p ~/.cursor/skills/my-skill

步骤 2：编写 SKILL.md

---
name: my-skill
description: 简要描述这个 Skill 的作用和触发时机
---

# My Skill

## 使用步骤

1. 第一步说明
2. 第二步说明
3. 第三步说明

## 示例

提供具体的使用示例...

步骤 3：关键编写要点

要点	说明	示例
name	小写字母、数字、连字符，最多64字符	code-review, generate-tests
description	第三人称，说明"做什么"和"何时用"	生成单元测试，当用户要求测试代码时使用
精简	只写 AI 不知道的信息	避免解释基础概念
长度	SKILL.md 建议不超过 500 行	细节放 reference.md
路径	使用正斜杠	scripts/helper.py

3.4 常用内置 Skill 参考

create-rule（创建规则）

用途：创建项目规则文件（.mdc）统一 AI 行为

触发：当用户想添加编码规范、项目约定时使用

示例：

帮我在项目里加一条 TypeScript 的编码规则
创建一个 React 组件规范

生成的规则文件结构：

---
description: TypeScript 编码规范
globs: **/*.ts
alwaysApply: false
---

# TypeScript 规范

- 使用严格类型
- 避免 any 类型
- 函数需要返回类型注解

create-skill（创建 Skill）

用途：帮助用户编写新的 Skill

触发：当用户想创建自定义 Skill 时使用

示例：

新建一个用于代码审查的 skill
帮我创建一个生成 API 文档的 skill

update-cursor-settings（更新设置）

用途：修改 Cursor 编辑器设置

触发：当用户想改字体、主题、快捷键等设置时

示例：

把编辑器字体调大
开启保存时自动格式化
把主题改成深色

3.5 Skill 最佳实践

1. 渐进式说明

   • 核心内容放在 SKILL.md
   • 详细说明放在 reference.md
   • 示例放在 examples.md

2. 描述要具体

   • ✅ 好：分析 Excel 数据并生成报表，当用户处理 .xlsx 文件时使用
   • ❌ 差：帮助处理文档

3. 使用模板

   ## 工作流程
   
   复制此清单并跟踪进度：
   
   - [ ] 步骤 1：分析需求
   - [ ] 步骤 2：设计方案
   - [ ] 步骤 3：实现功能
   - [ ] 步骤 4：验证结果
   

4. 避免反模式

   • ❌ Windows 风格路径：scripts\helper.py

   • ✅ 正斜杠路径：scripts/helper.py

   • ❌ 太多选项：你可以用 A，或 B，或 C...

   • ✅ 提供默认：使用 A，特殊情况用 B

---

四、高级功能

4.1 多文件编辑

同时修改 src/user.ts 和 src/auth.ts，添加登录验证

4.2 代码搜索与分析

搜索项目中所有使用 User 类的地方
分析项目结构并生成架构图
找出所有未使用的函数

4.3 批量操作

为 src/components/ 下的所有组件添加 PropTypes
把项目中所有 var 改成 const 或 let

4.4 智能补全

基于已有的 UserService，帮我写 ArticleService
参考现有的样式，为新页面写 CSS

---

五、配置与个性化

5.1 配置文件位置

平台	路径
Windows	C:\Users\用户名\.claude\settings.json
macOS	~/.claude/settings.json
Linux	~/.claude/settings.json

5.2 常用配置项

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "ANTHROPIC_DEFAULT_MODEL": "claude-sonnet-4-20250514"
  },
  "preferences": {
    "auto_execute_commands": false,
    "confirm_destructive_operations": true
  }
}

5.3 配置 GLM 模型（Z.AI）

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5"
  }
}

---

六、常见问题

Q1: Claude Code 启动失败

解决：

# 检查 Node.js 版本（需要 18+）
node --version

# 重新安装
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

Q2: API Key 无效

解决：

• 检查 settings.json 中的 ANTHROPIC_AUTH_TOKEN
• 确认 API Key 有余额
• 验证网络连接

Q3: 如何切换模型

解决：

# 查看当前模型
/status

# 在配置文件中修改默认模型
# 或使用环境变量
export ANTHROPIC_DEFAULT_MODEL=claude-opus-4-20250514

Q4: 对话历史太长

解决：

/compact    # 压缩历史
/clear      # 清除历史

Q5: Skill 没有生效

解决：

1. 检查 Skill 文件位置是否正确
2. 确认 SKILL.md 格式正确（包含 YAML frontmatter）
3. 验证 description 是否清晰具体
4. 重启 Claude Code

---

参考资源

• Claude Code 官方文档
• Cursor 官方文档
• Z.AI 开发文档

---

手册生成于 Claude Code