Claude Code 深度教程：从 CLI 命令到自定义 Skills 工作流

Claude Code 是 Anthropic 推出的命令行 AI 编程助手，2025年已经成为很多后端开发者的主力工具。它不是简单的代码补全，而是能在终端里自主理解项目、编辑文件、运行命令、调试排错的 AI Agent。我用 Claude Code 做了几个微服务重构项目，总结了一套从入门到精通的使用方法。今天把深度教程分享出来。

一、Claude Code 是什么

Claude Code 是运行在终端里的 AI 编程助手，核心特点：

CLI 原生：在终端里运行，和 Vim/Emacs/tmux 完美配合
自主 Agent：能自主规划任务、编辑文件、运行命令、看报错、修复，循环直到完成
项目理解：能读取整个项目结构、理解代码上下文、跨文件引用
工具能力：内置文件编辑、命令执行、搜索、git 操作，还能通过 MCP 扩展
Claude 原生：用 Claude 3.5/3.7 Sonnet/Opus，推理能力强，复杂任务完成度高

和 Cursor 的区别：Cursor 是 AI 原生 IDE（GUI），Claude Code 是 CLI 工具。喜欢命令行、用 Vim/Emacs、做后端开发的，Claude Code 更顺手；喜欢 GUI、做前端全栈的，Cursor 体验更好。

二、安装与配置

安装

1
2
3
4
5
6
7
8
# macOS
brew install claude-code

# 或用 npm
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

认证

1
2
3
4
5
# 方式一：用 Anthropic API Key（按量付费）
export ANTHROPIC_API_KEY=sk-ant-xxx

# 方式二：订阅 Claude Pro/Max（含额度）
claude login

建议重度用户订阅 Max 计划（$20/月），有额度上限，比按量付费可控。

基础配置

创建 ~/.claude/settings.json：

1
2
3
4
5
6
7
8
{
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash(git *)", "Bash(go *)", "Bash(make *)"],
    "deny": ["Bash(rm -rf /)", "Bash(:(){:|:&};:)"]
  },
  "model": "claude-3-5-sonnet-20241022",
  "max_uses": 50
}

permissions.allow：允许执行的操作，常用命令加白名单，不用每次确认
permissions.deny：禁止执行的危险操作
model：默认模型，Sonnet 性价比高，复杂任务用 Opus
max_uses：单次对话最大工具调用次数，防止死循环

三、基础使用

启动

1
2
3
4
5
6
7
8
9
# 在项目目录下启动
cd my-project
claude

# 启动时直接带任务
claude "给这个服务加一个健康检查接口"

# 用特定模型启动
claude --model opus "重构这个复杂函数"

常用命令

在 Claude Code 交互界面里：

命令	说明
`/help`	查看帮助
`/clear`	清空对话历史
`/compact`	压缩对话历史（上下文太长时用）
`/model`	切换模型
`/cost`	查看当前对话的 token 用量和费用
`/exit`	退出
`!命令`	直接执行 shell 命令（如 `!git status`）
`@文件名`	引用文件，让 Claude 关注这个文件
`@符号名`	引用代码符号（函数、类、变量）

第一个任务

1
2
# 在 Go 项目里
claude "给 resume-service 加一个健康检查接口 /health，返回服务状态、版本、数据库连接状态"

Claude Code 会：

读取项目结构，找到 resume-service 的代码
理解现有代码风格和框架（Gin/Echo）
编辑 handler 文件，添加 /health 接口
编辑路由文件，注册路由
运行 go build 验证编译通过
运行 go test 跑测试
如果有报错，自动修复，再跑一遍

整个过程不需要你手动操作，Claude 自主完成。你只需要看结果，不满意就说"这里改一下"。

四、高级技巧

4.1 项目理解

Claude Code 能读取整个项目，但上下文有限，要引导它关注重点：

4.2 多文件重构

复杂重构涉及多个文件，要把任务拆清楚：

关键点：

把需求说清楚，包含具体步骤
涉及外部依赖（Redis）要说明
要求加单测，保证质量
“先看代码再说方案，确认后再改”——防止 Claude 直接改出问题

4.3 调试排错

Claude Code 最强大的场景之一是调试：

Claude 会自己运行命令、看日志、分析代码、定位问题、修复，然后再跑一遍验证。

4.4 代码审查

4.5 测试生成

五、自定义 Skills

Claude Code 支持自定义 Skills，把常用的工作流固化下来。

创建 Skill

在项目根目录创建 .claude/skills/ 目录，每个 Skill 是一个子目录，包含 SKILL.md：

Skill 示例：API 开发流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# .claude/skills/api-development/SKILL.md
---
name: api-development
description: 开发新 API 接口的标准流程，包含接口定义、参数校验、业务逻辑、错误处理、单测
---

# API 开发标准流程

当用户要求开发新 API 接口时，按以下流程执行：

## 1. 理解需求
- 确认接口的功能、输入、输出
- 确认权限要求（是否需要登录、角色权限）
- 确认是否有类似的现有接口可以参考

## 2. 查看现有代码
- 查看同模块的 handler 代码风格
- 查看路由注册方式
- 查看 service 层和 repository 层的模式
- 查看错误处理和参数校验的方式

## 3. 实现接口
按以下顺序实现：
1. **参数定义**：在 types 包定义请求和响应结构体，加 validate tag
2. **Handler**：参数校验、调用 service、格式化响应
3. **Service**：业务逻辑、事务管理、缓存操作
4. **Repository**：数据库操作
5. **路由注册**：在 router 里注册接口

## 4. 错误处理
- 参数错误返回 400，code=1
- 未登录返回 401，code=2
- 无权限返回 403，code=3
- 资源不存在返回 404，code=4
- 服务器错误返回 500，code=500

## 5. 单测
- Handler 层：用 httptest 测试，mock service
- Service 层：mock repository，覆盖正常和异常场景
- 覆盖率要求 80% 以上

## 6. 验证
- 运行 `go build ./...` 确认编译通过
- 运行 `go test ./...` 确认测试通过
- 运行 `go vet ./...` 确认没有静态检查问题

## 注意事项
- 遵循现有代码风格，不要引入新的依赖
- 敏感操作（删除、修改）要加权限校验
- 数据库操作用事务保证一致性
- 不要硬编码，配置放 config

使用 Skill

启动 Claude Code 后，它会自动发现 .claude/skills/ 里的 Skills。当你说"开发一个新接口"时，Claude 会自动加载 api-development Skill，按标准流程执行。

也可以显式指定：

六、MCP 集成

Claude Code 支持 MCP，可以连接外部 MCP Server 扩展能力。

配置 MCP

在 ~/.claude.json 或项目级 .claude/settings.json 里配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "recruitment": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "X-API-Key": "your-key"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

使用 MCP 工具

配置后，Claude Code 就能使用 MCP Server 提供的工具。比如连接了 GitHub MCP 后：

Claude 会调用 GitHub MCP 工具获取 PR 列表，筛选未处理的，然后逐个修改代码、提交、推送。

七、工作流优化

7.1 CLAUDE.md 文件

在项目根目录创建 CLAUDE.md，Claude Code 启动时会自动读取，作为项目级指令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# CLAUDE.md

## 项目概述
这是最佳东方招聘平台的后端微服务，用 Go + Gin + GORM 开发，部署在 K8s 上。

## 技术栈
- 语言：Go 1.22
- Web 框架：Gin
- ORM：GORM
- 数据库：MySQL 8.0
- 缓存：Redis 7
- 消息队列：RabbitMQ
- 服务发现：etcd
- 部署：K8s + ArgoCD

## 代码规范
- 分层架构：handler → service → repository
- 错误处理：用自定义 error，统一返回格式 {code, message, data}
- 参数校验：用 go-playground/validator
- 日志：用 zap，结构化日志
- 测试：用 testify，mock 用 mockery

## 常用命令
- 构建：make build
- 测试：make test
- 运行：make run
- 代码生成：make gen（mock、swagger）

## 注意事项
- 不要直接修改 main 分支，新建分支开发
- 数据库迁移用 golang-migrate，不要手动改表
- 敏感配置不要硬编码，从环境变量读
- 提交前跑 make lint 和 make test

有了 CLAUDE.md，Claude Code 不用每次都问"这个项目用什么框架"，直接就能上手。

7.2 任务拆分

大任务不要一次丢给 Claude，拆成小任务，每步验证：

每步完成后验证，再进行下一步，比一次让它做整个重构靠谱得多。

7.3 人工审核

Claude 生成的代码一定要审核，特别是：

安全相关（SQL、权限、加密）
并发相关（goroutine、锁、channel）
数据库事务
错误处理
性能敏感的代码

不要完全信任 AI，它会"一本正经地胡说八道"。审核重点是逻辑正确性和安全性，语法和风格 Claude 一般没问题。

八、实战案例

案例：微服务接口开发

任务：给 resume-service 加一个批量导出接口。

整个过程 5 分钟，比自己写快 5-10 倍，而且代码质量稳定。

九、踩坑经验

上下文太长会"失忆"：对话太长时，Claude 会忘记早期的上下文。用 /compact 压缩，或者开新对话，把关键信息贴进去
不要让它直接跑危险命令：虽然有 deny 列表，但还是要小心。涉及删除、覆盖、发布的命令，让它先确认再执行
大文件编辑容易出错：Claude 编辑大文件（>500行）时有时会漏内容。让它用小范围编辑，或者把大文件拆成小文件
依赖版本问题：Claude 可能会建议用不存在的 API 或过时的库。涉及第三方库时，让它先看 go.mod/package.json 里的版本，再写代码
测试不要完全信：Claude 写的测试有时会"放水"（断言太松、mock 不对）。一定要看测试代码，确认测试真的在验证逻辑
git 操作要小心：让 Claude 操作 git 时，它可能会强制推送、删除分支。涉及 git 操作时，先让它说要执行什么命令，确认后再执行
API Key 安全：不要把 API Key 写在代码里，Claude 可能会不小心提交到 git。用环境变量，CLAUDE.md 里说明
费用控制：重度使用 Claude Code，token 消耗很快。订阅 Max 计划比按量付费划算，用 /cost 随时看用量

十、总结

Claude Code 深度使用核心：

CLI 原生，后端开发者利器：在终端里运行，和 Vim/tmux/git 完美配合，比 GUI 工具更适合后端开发
自主 Agent，不是简单补全：能理解项目、编辑文件、运行命令、看报错、修复，循环直到完成任务
CLAUDE.md 是项目说明书：把项目概述、技术栈、规范、常用命令写进去，Claude 不用每次问，直接上手
自定义 Skills 固化工作流：把常用流程（API 开发、bug 修复、代码审查）做成 Skill，保证一致性和质量
MCP 扩展能力边界：连接 GitHub、数据库、内部系统等 MCP Server，让 Claude 能操作外部世界
任务拆分，小步迭代：大任务拆成小步骤，每步验证，比一次丢给它靠谱
人工审核是必须的：安全、并发、事务、性能相关的代码一定要审核，不要完全信任 AI
上下文管理很重要：对话太长用 /compact，大任务开新对话，防止"失忆"

Claude Code 代表了 AI 编程的新范式——不是"AI 帮你写一行代码"，而是"AI 作为你的开发伙伴，自主完成完整任务"。用好它，开发效率能提升 2-3 倍，而且能把你从重复劳动中解放出来，专注于架构设计和业务思考。但它是工具不是替代者，你的技术判断力、业务理解、代码审美仍然是核心。

一、Claude Code 是什么#

二、安装与配置#

安装#

认证#

基础配置#

三、基础使用#

启动#

常用命令#

第一个任务#

四、高级技巧#

4.1 项目理解#

4.2 多文件重构#

4.3 调试排错#

4.4 代码审查#

4.5 测试生成#

五、自定义 Skills#

创建 Skill#

Skill 示例：API 开发流程#

使用 Skill#

六、MCP 集成#

配置 MCP#

使用 MCP 工具#

七、工作流优化#

7.1 CLAUDE.md 文件#

7.2 任务拆分#

7.3 人工审核#

八、实战案例#

案例：微服务接口开发#

九、踩坑经验#

十、总结#