Claude Code

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，它可以理解你的代码库、执行命令、读写文件，并协助你完成各种开发任务。本文将详细介绍 Claude Code 的使用方法，特别是如何配合自定义模型使用。

1. 安装和配置

1.1 安装 Claude Code

Claude Code 原生安装使用了 bun 打包的，性能更好：

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

安装完成后，需要配置 API 密钥：

claude
# 首次运行会提示输入 API 密钥

或者通过环境变量设置：

export ANTHROPIC_API_KEY="your-api-key-here"

1.2 验证安装

运行以下命令验证安装是否成功：

claude --version

2. 基本使用

2.1 启动交互式会话

在项目根目录运行 claude 命令启动交互式会话：

claude

启动后，你可以直接输入自然语言描述你的需求，例如：

帮我创建一个简单的 HTTP 服务器

2.2 执行单次查询

使用 -p 参数执行单次查询并退出：

claude -p "解释一下这个项目的结构"

2.3 命令行参数

参数	说明	示例
-p, --prompt	执行单次查询	claude -p "解释代码"
-d, --directory	指定工作目录	claude -d /path/to/project
--verbose	显示详细日志	claude --verbose
--version	显示版本号	claude --version
--help	显示帮助信息	claude --help

2.4 会话内命令

在交互式会话中可以使用的命令：

命令	说明	示例
/clear	清除当前会话历史	/clear
/exit	退出会话	/exit
/help	显示帮助信息	/help
/save <file>	保存会话到文件	/save session.json
/load <file>	加载历史会话	/load session.json
/model	查看/切换模型	/model claude-3-opus
/bug	报告问题	/bug 描述问题

3. 自定义模型配置

3.1 为什么需要自定义模型

Claude Code 默认使用 Anthropic 的官方模型，但在某些场景下，你可能需要：

• 降低成本：使用第三方提供的更便宜的 API 服务
• 数据合规：使用本地部署的模型满足数据隐私要求
• 特殊需求：使用特定版本或微调的模型

3.2 配置自定义模型端点

Claude Code 支持通过环境变量配置自定义模型端点：

# 设置自定义 API 端点
export ANTHROPIC_BASE_URL="https://your-custom-endpoint.com/v1"

# 设置使用的模型名称
export ANTHROPIC_MODEL="your-model-name"

3.3 使用兼容 Anthropic API 的服务

许多服务提供兼容 Anthropic API 的接口，可以直接使用：

3.3.1 使用 OpenRouter

export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="your-openrouter-key"
export ANTHROPIC_MODEL="anthropic/claude-3.5-sonnet"

3.3.2 使用本地部署的模型

如果你使用 vLLM、Ollama 等本地部署方案：

# 以 Ollama 为例
export ANTHROPIC_BASE_URL="http://localhost:11434/v1"
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_MODEL="llama3.1:70b"

3.3.3 使用阿里云百炼

export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
export ANTHROPIC_API_KEY="your-dashscope-key"
export ANTHROPIC_MODEL="qwen-plus"

3.4 配置文件方式

创建 .claude/config.json 文件保存配置：

{
  "api_key": "your-api-key",
  "base_url": "https://your-custom-endpoint.com/v1",
  "model": "your-model-name"
}

4. 高级使用技巧

4.1 项目上下文理解

Claude Code 会自动读取项目中的文件来理解上下文。为了更好地利用这个功能：

4.1.1 创建项目说明文件

在项目根目录创建 PROJECT.md 或 README.md，描述项目结构和技术栈：

# 项目概述

这是一个基于 Spring Boot 的分布式服务...

## 技术栈
- Java 17
- Spring Boot 3.x
- MySQL 8.0

## 目录结构
- `src/main/java`: 源代码
- `src/test/java`: 测试代码
- `src/main/resources`: 配置文件

4.1.2 使用 .kilocodeignore 排除文件

创建 .kilocodeignore 文件排除不需要读取的文件：

node_modules/
*.log
dist/
build/

4.2 多文件操作

4.2.1 批量读取文件

在对话中明确指定要读取的文件：

请读取 src/main/java/com/example/Service.java 和 
src/main/java/com/example/Controller.java，分析它们的关系

4.2.2 创建多个文件

创建一个完整的用户模块，包括：
- User 实体类
- UserRepository 数据访问层
- UserService 业务逻辑层
- UserController 控制器

4.3 代码执行和验证

Claude Code 可以执行 shell 命令来验证代码：

帮我修复这个编译错误，然后运行 mvn test 验证

安全提示：Claude Code 在执行命令前会请求确认，确保你了解命令的作用。

4.4 会话管理

4.4.1 保存重要对话

使用 /save 命令保存当前会话：

/save important-session.json

4.4.2 加载历史会话

/load important-session.json

5. Skills 使用

Claude Code 的 Skills 是一种可扩展的能力系统，允许你定义自定义命令和工作流。

5.1 什么是 Skills

Skills 是预定义的指令模板，可以帮助你：

• 标准化工作流程：确保团队使用一致的方法
• 提高效率：减少重复输入
• 封装最佳实践：将经验固化为可复用的指令

5.2 内置 Skills

Claude Code 提供了一些内置的 Skills：

Skill	说明	使用方法
/dev	开发相关任务	/dev 实现一个功能
/test	测试相关任务	/test 为这个类生成测试
/docs	文档相关任务	/docs 生成 API 文档
/refactor	重构相关任务	/refactor 优化这段代码
/debug	调试相关任务	/debug 分析这个错误

5.3 自定义 Skills

在项目根目录创建 .claude/skills/ 目录，可以定义自定义 Skills。

5.3.1 创建 Skill 文件

创建 .claude/skills/review.json：

{
  "name": "review",
  "description": "代码审查技能",
  "instructions": "请作为资深代码审查员，审查以下代码：\n1. 检查代码规范和风格\n2. 识别潜在的 bug 和安全问题\n3. 评估性能和可维护性\n4. 提出具体的改进建议\n\n代码：",
  "category": "development"
}

5.3.2 使用自定义 Skill

claude /review src/main/java/Service.java

5.3.3 Skill 模板示例

测试生成 Skill (.claude/skills/test.json)：

{
  "name": "test",
  "description": "生成单元测试",
  "instructions": "请为以下代码生成完整的单元测试：\n- 使用 JUnit 5 框架\n- 使用 Mockito 进行依赖模拟\n- 覆盖所有公共方法\n- 包括正常情况和边界情况\n- 断言要具体明确\n\n代码：",
  "category": "testing"
}

Git 提交 Skill (.claude/skills/commit.json)：

{
  "name": "commit",
  "description": "生成 Git 提交信息",
  "instructions": "请根据以下 git diff 生成符合 Conventional Commits 规范的提交信息：\n- 格式：<type>(<scope>): <description>\n- type 包括：feat, fix, docs, style, refactor, test, chore\n- 提供简短的正文说明（可选）\n\ngit diff:",
  "category": "git"
}

SQL 生成 Skill (.claude/skills/sql.json)：

{
  "name": "sql",
  "description": "生成 SQL 查询",
  "instructions": "请根据以下需求生成 SQL 查询：\n- 考虑性能和索引使用\n- 使用参数化查询防止 SQL 注入\n- 添加必要的注释\n- 遵循团队 SQL 规范\n\n需求：",
  "category": "database"
}

5.4 Skill 最佳实践

1. 保持专注：每个 Skill 只做一件事
2. 明确输入输出：清楚说明需要什么输入，会产生什么输出
3. 包含示例：在 instructions 中添加使用示例
4. 分类管理：使用 category 字段组织 Skills

6. 实际应用场景

6.1 代码审查

请审查这个 Pull Request 的改动，找出潜在的问题：
1. 检查是否有空指针风险
2. 检查异常处理是否完善
3. 检查是否有性能问题

6.2 重构辅助

这个类有 500 行代码，太长了。请帮我：
1. 分析职责划分
2. 提出拆分建议
3. 逐步执行重构

6.3 测试生成

为 UserService 类生成单元测试，要求：
- 使用 JUnit 5 和 Mockito
- 覆盖所有公共方法
- 包括边界条件测试

6.4 文档生成

根据代码生成 API 文档：
- 提取所有 REST 端点
- 说明请求参数和响应格式
- 添加使用示例

6.5 Bug 调试

这个测试失败了，请帮我分析原因：
1. 查看错误日志
2. 定位问题代码
3. 提出修复方案
4. 验证修复结果

6.6 使用 Skills 简化流程

使用自定义 Skills 可以简化常见任务：

# 使用 review skill 快速审查代码
claude /review src/main/java/UserService.java

# 使用 test skill 生成测试
claude /test src/main/java/UserService.java

# 使用 commit skill 生成提交信息
git diff | claude /commit

7. 最佳实践

7.1 提示词技巧

1. 具体明确：不要说”修复这个 bug”，而要说”修复 NullPointerException，发生在第 42 行”

2. 分步执行：复杂任务分解成多个小步骤

   第一步：分析代码结构
   第二步：提出改进建议
   第三步：执行重构

3. 提供上下文：告诉 AI 项目的技术栈和约束条件

4. 使用 Skills：将常用操作封装为 Skills，提高效率

7.2 安全注意事项

1. 审查所有改动：在提交前仔细检查 AI 生成的代码
2. 敏感信息保护：不要在对话中暴露 API 密钥、数据库密码等
3. 命令执行确认：仔细审查要执行的命令，特别是 rm、chmod 等危险操作

7.3 成本控制

1. 使用合适的模型：简单任务使用较小的模型
2. 精简上下文：只包含必要的文件
3. 复用会话：在同一会话中继续任务，避免重复发送上下文

8. 常见问题

7.1 模型响应慢

• 检查网络连接
• 尝试使用更小的模型
• 减少上下文文件大小

7.2 API 调用失败

# 检查 API 密钥是否正确
echo $ANTHROPIC_API_KEY

# 检查端点是否可达
curl -I $ANTHROPIC_BASE_URL

# 查看详细日志
claude --verbose

7.3 模型不理解项目

• 确保在项目根目录运行
• 创建清晰的项目说明文档
• 主动提供相关文件路径

8. 常见问题

8.1 模型响应慢

• 检查网络连接
• 尝试使用更小的模型
• 减少上下文文件大小

8.2 API 调用失败

# 检查 API 密钥是否正确
echo $ANTHROPIC_API_KEY

# 检查端点是否可达
curl -I $ANTHROPIC_BASE_URL

# 查看详细日志
claude --verbose

8.3 模型不理解项目

• 确保在项目根目录运行
• 创建清晰的项目说明文档
• 主动提供相关文件路径

9. 总结

Claude Code 是一个强大的编程助手，通过合理配置和使用技巧，可以显著提高开发效率。

核心要点：

• 灵活配置：支持自定义模型端点，可以对接各种兼容服务
• 上下文理解：自动读取项目文件，理解代码结构
• 安全可控：所有命令执行前都会请求确认
• 场景广泛：适用于代码审查、重构、测试、调试等多种场景
• 可扩展性：通过 Skills 系统可以自定义工作流程

推荐配置：

# 生产环境使用官方模型
export ANTHROPIC_API_KEY="sk-..."
export ANTHROPIC_MODEL="claude-3-5-sonnet-20241022"

# 开发测试使用本地模型
export ANTHROPIC_BASE_URL="http://localhost:11434/v1"
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_MODEL="qwen2.5:72b"

常用命令速查：

# 启动交互式会话
claude

# 执行单次查询
claude -p "解释这段代码"

# 使用 Skill
claude /review src/main/java/Service.java

# 指定模型
/model claude-3-opus

# 保存/加载会话
/save session.json
/load session.json

通过掌握这些技巧，你可以让 Claude Code 更好地服务于你的开发工作流。