Claude Code 快速上手教程
零基础友好 | 学练结合 | 快速提升 70% 开发效率
学习目标: 掌握 Claude Code 的核心使用技能,显著提升开发效率
适用对象: 从未使用过 Claude Code 的开发者
学习方式: 建议按顺序学习,每个章节包含理论 + 实践
📚 课程大纲
| 部分 | 内容 | 形式 |
|---|---|---|
| 第一部分 | 核心理念 | 理论 |
| 第二部分 | 必备技能 | 理论 + 练习 |
| 第三部分 | 实战演练 | 场景 + 练习 |
| 第四部分 | 快速避坑 | 案例 |
| 第五部分 | 下一步 | 指引 |
第一部分:核心理念
1.1 为什么需要结构化提示词
传统方式的问题
❌ 问题场景:
开发者: "帮我写一个订单功能"
AI: (生成 500 行代码)
开发者: "这个不对,我需要支持会员折扣"
AI: (重新生成 500 行代码)
开发者: "还要支持免费次数..."
AI: (再次重新生成...)问题:
- 💸 浪费大量 token
- 🔄 反复返工
- 😰 代码质量不可控
- ⏰ 效率低下
结构化方式的优势
✅ 正确场景:
【分析阶段】
开发者: "讨论订单功能需求,不要写代码"
AI: "理解需求,识别 4 种计费场景..."
开发者: "理解正确"
【设计阶段】
开发者: "给出 2-3 个实现方案,不要写代码"
AI: "方案 A: 统一入口... 方案 B: 分散处理..."
开发者: "采用方案 A"
【实施阶段】
开发者: "按方案 A 开始编码"
AI: "生成符合预期的代码"
开发者: "完美!"优势:
- ✅ 一次到位,减少返工
- ✅ 节省 token 成本
- ✅ 代码质量可控
- ✅ 效率大幅提升
1.2 三段式工作流
这是 Claude Code 协作的核心方法论:
┌─────────────────────────────────────────┐
│ 阶段 1: 分析 (Analysis) │
│ 目标: 理解现状、评估可行性 │
│ 关键词: 解释、分析、不要写代码 │
│ 时长: 1-2 轮对话 │
├─────────────────────────────────────────┤
│ 阶段 2: 设计 (Design) │
│ 目标: 制定方案、确认需求 │
│ 关键词: 讨论、对比、复述、不要写代码 │
│ 时长: 2-3 轮对话 │
├─────────────────────────────────────────┤
│ 阶段 3: 实施 (Implementation) │
│ 目标: 编写代码、分步执行 │
│ 关键词: 采用方案 X、开始编码 │
│ 时长: 1-N 轮对话(根据复杂度) │
└─────────────────────────────────────────┘核心原则
原则 1: 先分析,再设计,后实施
- ❌ 不要直接要求写代码
- ✅ 先理解现状,讨论方案,最后编码
原则 2: 关键时刻说"不要写代码"
- 分析阶段:必须加
- 设计阶段:必须加
- 实施阶段:不需要
原则 3: 使用 @ 精确引用
- ❌ "在订单文件的 100 行左右"
- ✅
@service/order.go#L100-120
1.3 为什么这样更高效?
效果对比
| 维度 | 传统方式 | 三段式工作流 |
|---|---|---|
| 返工次数 | 3-5 次 | 0-1 次 |
| Token 消耗 | 大量 | 节省 40-60% |
| 对话轮数 | 15-20 轮 | 5-10 轮 |
| 代码质量 | 不可控 | 可控 |
| 学习曲线 | 陡峭 | 平缓 |
真实案例
任务: 为订单接口增加会员折扣逻辑
传统方式: 12 轮对话,3 次重写 三段式: 5 轮对话,一次到位
节省时间: 70%
第二部分:必备技能
2.1 核心语法
语法 1: @ 文件引用符
作用: 精确引用文件或代码段
格式:
@文件路径 # 引用整个文件
@文件路径#L50 # 引用第 50 行
@文件路径#L50-80 # 引用第 50-80 行
@文件1 @文件2 # 引用多个文件示例:
# 引用整个文件
@api/v1/order.go
# 引用特定行
@service/user.go#L100
# 引用范围
@service/order.go#L50-80
# 引用多个文件
@api/v1/order.go @service/order.go为什么重要?
❌ 错误: "订单文件的第 100 行左右那个函数"
- AI 可能找错位置
- 描述模糊不准确
✅ 正确: "@service/order.go#L100-120"
- 精确定位
- 不会出错语法 2: 关键修饰符
修饰符 1: "不要写代码"
用途: 限制 AI 只分析讨论,不生成代码
使用场景: 分析阶段、设计阶段
示例:
@service/order.go#L50-100
解释一下订单创建的完整流程,不要写代码修饰符 2: "先说明"
用途: 要求 AI 先给出方案,等确认后再执行
使用场景: 复杂修改前、风险较高的操作
示例:
@api/v1/user.go#L50-80
删除 deprecated 字段,先说明影响范围,不要写代码修饰符 3: "直接修改"
用途: 跳过讨论,立即执行
使用场景: 简单操作、已经明确的修改
示例:
@model/user.go#L20
将 UserID 改为 UID,直接修改语法 3: / 命令符
/clear 清空上下文
/think 深度思考模式使用场景:
/clear 使用时机:
✅ 切换到完全不同的任务
✅ 上下文超过 50 轮对话
✅ AI 开始混淆之前的内容
❌ 任务进行中(会丢失上下文)
❌ 仅仅换了个文件
/think 使用时机:
✅ 复杂的架构设计
✅ 难以抉择的技术选型
✅ 需要深度分析的问题语法 4: 结构化描述
使用标识符组织信息:
【需求背景】
现有功能管理页面混乱,需要重新设计
【功能目标】
实现统一的功能管理,包括:
- 价格配置
- 免费次数设置
- 平台支持
【技术要求】
- 响应时间 < 500ms
- 支持批量导入
- 配置变更要有审计日志为什么使用结构化?
- ✅ 信息清晰,不遗漏
- ✅ AI 更容易理解
- ✅ 便于后续追溯
语法 5: 占位符约定
在模板中使用占位符:
{文件} → api/v1/user.go
{行号} → #L100-120
{功能} → 订单创建逻辑
{模块} → user_benefit
{方案X} → 方案A
{字段} → member_level示例:
模板:
@{文件}#{行号} 解释{功能},不要写代码
实际使用:
@api/v1/order.go#L50-100 解释订单创建逻辑,不要写代码2.2 三段式工作流实操
阶段 1: 分析
目标: 理解现状,不要盲目修改
核心模板:
@{文件}#{行号} 解释一下{功能/逻辑},不要写代码完整示例:
@api/v1/order.go#L50-100
解释一下订单创建的完整流程,不要写代码
请说明:
1. 输入参数和返回值
2. 核心步骤分解
3. 边界条件处理
4. 错误处理方式AI 会输出:
- 函数的核心逻辑
- 关键步骤说明
- 边界条件
- 潜在问题
你要做的:
- 确认理解是否正确
- 识别遗漏的部分
- 决定是否需要看更多代码
阶段 2: 设计
目标: 制定方案,充分讨论
核心模板:
讨论需求,不要写代码
{详细需求描述}
有没有更好的方案,不要写代码完整示例:
讨论需求,不要写代码
【当前功能】
订单创建接口,所有用户统一价格
【需要增加的逻辑】
根据用户类型计费:
- 场景 1: 免费功能,直接创建订单
- 场景 2: 付费功能,优先扣免费次数
- 场景 3: 无免费次数,会员按会员价
- 场景 4: 非会员按原价
【技术要求】
- 免费次数扣减和订单创建要在同一事务
- 会员价 = 原价时,不显示会员标识
请给出 2-3 个实现方案,不要写代码AI 会输出:
- 方案 A、B、C
- 每个方案的优缺点
- 推荐方案和理由
你要做的:
采用方案 B,请详细说明实施步骤,不要写代码
包括:
1. 数据查询顺序
2. 判断逻辑
3. 事务范围
4. 返回字段设计阶段 3: 实施
目标: 编写代码,分步执行
核心模板:
采用方案{X},开始编码
要求:
- 遵循 CLAUDE.md 中的规范
- {其他约束条件}完整示例:
采用方案 B,开始编码
【编码规范】
- 遵循 CLAUDE.md 中的分层规范
- 参考 user_benefit 模块的实现方式
- 错误处理统一使用 pkg/errors
【实施顺序】
1. 先完成 Model 层(数据查询)
2. 再完成 Service 层(业务逻辑)
3. 最后完成 API 层(接口暴露)
每完成一层暂停,等我确认后继续AI 会输出:
- 按顺序生成代码
- 每层完成后暂停
你要做的:
# 确认第一层
ok,继续 Service 层
# 确认第二层
ok,继续 API 层
# 全部完成
完美,生成单元测试💡 动手练习 1
任务: 使用三段式工作流理解一个函数
假设你有一个文件 service/user.go,其中 L50-100 是用户注册函数。
请写出:
- 分析阶段的提示词
- 设计阶段的提示词(假设要增加手机号验证)
- 实施阶段的提示词
提示:
- 记得使用 @ 引用
- 记得加"不要写代码"
- 使用结构化描述
参考答案(不要偷看,先自己写):
点击查看参考答案
【分析阶段】
@service/user.go#L50-100
解释一下用户注册函数的完整流程,不要写代码
请说明:
1. 当前的验证逻辑
2. 数据存储方式
3. 错误处理
【设计阶段】
讨论需求,不要写代码
【当前功能】
用户注册,验证邮箱后创建账户
【需要增加】
增加手机号验证:
- 发送验证码
- 验证码 5 分钟有效
- 验证通过后才能注册
请给出实现方案,不要写代码
【实施阶段】
采用你推荐的方案,开始编码
要求:
- 遵循现有的错误处理方式
- 验证码存储在 Redis
- 每完成一个函数暂停第三部分:实战演练
3.1 场景 1: 简单逻辑增加
场景描述
任务: 在用户信息接口中,如果用户是会员,额外返回会员等级和过期时间
当前代码:
// api/v1/user.go L50-80
func GetUserInfo(c *gin.Context) {
userID := c.GetInt("user_id")
user, err := model.GetUserByID(userID)
if err != nil {
response.Error(c, err)
return
}
response.Success(c, gin.H{
"user_id": user.ID,
"username": user.Username,
"email": user.Email,
})
}需求: 增加会员信息字段
复杂度: 🟢 简单(2-3 轮)
第 1 轮: 理解 + 设计
@api/v1/user.go#L50-80
【当前功能】
获取用户基本信息接口
【需要增加】
如果用户是会员,额外返回:
- member_level: 会员等级
- member_expire_at: 会员过期时间
【要求】
- 非会员用户不返回这些字段
- 使用 omitempty 保持向后兼容
请先:
1. 复述当前函数逻辑
2. 说明修改建议
不要写代码第 2 轮: 实施
方案合理,开始修改
要求:
- 新增字段使用 json:",omitempty" 标签
- 添加注释说明关键要点
✅ 正确做法:
- 先理解现状
- 使用 omitempty 保持兼容性
- 分步执行
❌ 常见错误:
- 直接要求加字段,没理解现有逻辑
- 忘记向后兼容
- 没有测试非会员场景
💡 动手练习 2
任务: 在商品列表接口中,如果商品有折扣,额外返回折扣信息
提示:
- 参考场景 1 的流程
- 思考:折扣信息包含哪些字段?
- 思考:如何判断商品是否有折扣?
- 写出完整的 2 轮提示词
3.2 场景 2: Bug 修复
场景描述
Bug 现象: 用户反馈,订单创建后扣了两次免费次数
问题代码:
// service/order.go L100-130
func CreateOrder(userID, functionID int) error {
// 查询免费次数
usage := model.GetUsage(userID, functionID)
if usage.FreeCount > 0 {
// 扣减免费次数
model.DecrementFreeCount(userID, functionID)
}
// 创建订单
order := &model.Order{
UserID: userID,
FunctionID: functionID,
}
return model.CreateOrder(order)
}复杂度: 🟡 中等(3-4 轮)
第 1 轮: 问题复现
遇到以下问题,请帮助定位
【问题描述】
用户创建订单后,免费次数被扣减了 2 次
【复现步骤】
1. 用户有 5 次免费次数
2. 创建 1 个订单
3. 免费次数变成 3(应该是 4)
【预期行为】
创建 1 个订单,免费次数扣减 1 次
【相关代码】
@service/order.go#L100-130
请分析可能的原因,不要写代码第 2 轮: 根因分析
基于代码分析根本原因,不要写代码
【分析内容】
1. 为什么会扣两次?
2. 是否有并发问题?
3. 是否缺少事务?第 3 轮: 修复方案
请给出修复方案,不要写代码
【方案要求】
1. 解决并发问题
2. 保证事务一致性
3. 最小化改动
如有多个方案,请对比说明第 4 轮: 实施修复
采用方案 A(使用事务),开始修复
要求:
- 订单创建和次数扣减在同一事务
- 添加错误回滚逻辑关键要点
✅ 正确做法:
- 详细描述问题现象
- 分析根本原因
- 方案要考虑并发
- 使用事务保证一致性
❌ 常见错误:
- 描述不清晰
- 没考虑并发场景
- 直接要求改代码,没分析原因
💡 动手练习 3
Bug: 用户修改密码后,仍然能用旧密码登录
提示:
- 写出问题复现的提示词
- 写出根因分析的提示词
- 思考可能的原因(缓存?token?)
3.3 场景 3: 方案选择
场景描述
需求: 系统需要支持多种计费方式(按次、按天、按月、阶梯定价)
当前: 只支持按次计费
复杂度: 🔴 复杂(4-6 轮)
第 1 轮: 需求讨论
讨论需求,不要写代码
【背景】
当前订单系统只支持按次计费
【新需求】
需要支持 4 种计费方式:
1. 按次计费(现有)
2. 按天计费(24 小时有效)
3. 按月计费(30 天有效)
4. 阶梯定价(用量越多,单价越低)
【技术要求】
- 不能影响现有按次计费的订单
- 需要支持未来新增计费方式
- 计费逻辑要可配置
请分析:
1. 现有架构是否支持
2. 需要新增哪些表/字段
3. 主要技术难点第 2 轮: 方案对比
基于以上分析,请提供 2-3 个设计方案,不要写代码
对比维度:
- 实施复杂度
- 扩展性
- 维护成本
- 对现有系统的影响第 3 轮: 详细设计
采用方案 B(策略模式),请详细说明实施步骤,不要写代码
包括:
1. 数据库设计(表结构/字段)
2. 代码分层设计
3. 如何保证向后兼容
4. 实施顺序第 4 轮: 需求确认
请复述以下内容,确认理解一致,不要写代码:
1. 数据库设计
2. 计费策略如何选择
3. 如何保证现有订单不受影响
4. 新增计费方式的流程第 5-6 轮: 分步实施
确认无误,开始编码
【实施顺序】
1. 先完成数据库变更
2. 再完成计费策略接口
3. 实现 4 种计费策略
4. 修改订单创建逻辑
每完成一步暂停关键要点
✅ 正确做法:
- 充分的需求讨论
- 多个方案对比
- 详细的设计阶段
- 需求复述确认
- 分步实施
❌ 常见错误:
- 没有方案对比就选定方案
- 忽略向后兼容性
- 没有考虑扩展性
- 一次性实现所有功能
第四部分:快速避坑
4.1 五个最常见错误
错误 1: 没理解就修改
❌ 错误示例:
@service/order.go#L50-150
帮我在这里加个会员判断逻辑问题:
- AI 不知道插入哪里
- 不知道变量是否已初始化
- 可能破坏原有流程
✅ 正确做法:
@service/order.go#L50-150
请先解释当前函数的完整逻辑,不要写代码
(AI 解释后)
理解正确,现在在"校验权限"之后插入会员判断逻辑错误 2: 描述不清晰
❌ 错误示例:
订单文件的第 100 行左右那个函数,改一下问题:
- 位置模糊
- 操作不明确
✅ 正确做法:
@service/order.go#L100-120
将 OrderType 字段改为 FunctionKey,要求:
- 更新所有引用
- 保持向后兼容错误 3: 忽略并发安全
❌ 错误示例:
帮我实现扣减免费次数的逻辑问题:
- 没说明并发场景
- AI 可能生成非并发安全的代码
✅ 正确做法:
实现扣减免费次数的逻辑
【并发要求】
- 需要并发安全(同一用户可能同时创建多个订单)
- 使用数据库事务或乐观锁
- 扣减失败要有明确提示
请先说明并发处理方案,不要写代码错误 4: 破坏兼容性
❌ 错误示例:
删除 user 表的 nickname 字段问题:
- 可能有地方还在用
- 可能导致线上故障
✅ 正确做法:
@model/user.go
删除 nickname 字段前,请先:
1. 搜索所有引用该字段的位置
2. 评估影响范围
3. 给出兼容性迁移方案
不要写代码错误 5: 上下文混乱
❌ 错误现象:
# 第 50 轮对话
开发者: "继续上一个任务"
AI: "混淆了 20 轮前的任务和 40 轮前的任务"问题:
- 对话太长
- 任务切换没清空上下文
✅ 正确做法:
# 切换任务时
/clear
继续订单模块开发
【上次进度】
- 已完成: Model 层、Service 层
- 当前: 需要完成 API 层
- 关键决策: 采用方案 B(统一入口)
请先复述关键决策,然后继续4.2 快速检查清单
在发送提示词前,快速检查:
□ 是否使用 @ 精确引用了文件?
□ 分析/设计阶段是否加了"不要写代码"?
□ 需求描述是否清晰完整?
□ 是否考虑了并发安全?
□ 是否考虑了向后兼容?
□ 是否使用结构化描述(【】标识)?
□ 复杂修改是否先说明方案?第五部分:下一步
5.1 学习路径
┌─────────────────────────────────────────┐
│ 你现在的位置 │
│ ✅ 掌握了核心理念和语法 │
│ ✅ 学会了三段式工作流 │
│ ✅ 完成了 3 个实战场景 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 初级阶段(接下来 1-2 周) │
│ → 使用实战指南完成实际工作任务 │
│ → 熟练掌握 5-10 个常用场景 │
│ → 建立团队的 CLAUDE.md 规范文档 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 中级阶段(1-2 个月后) │
│ → 学习进阶技巧(流程组合、上下文管理) │
│ → 处理复杂的重构和新功能开发 │
│ → 优化团队协作流程 │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 高级阶段(3 个月后) │
│ → 掌握所有高级技巧 │
│ → 能够培训其他团队成员 │
│ → 建立团队最佳实践 │
└─────────────────────────────────────────┘5.2 推荐的下一步行动
行动 1: 完成一个真实任务
选择你当前工作中的一个小任务(如:增加一个字段、修复一个 Bug),使用三段式工作流完成它。
行动 2: 根据工作阶段选择合适文档
选择指南:
日常开发任务 → 使用 实战指南.md
- 快速查找具体场景的完整流程
- 适合执行明确的开发任务
- 推荐场景:文档项目(场景 1-5)、后端开发(工作流 1-3)、前端开发(工作流 2, 4)
遇到复杂问题 → 使用 进阶技巧.md
- 学习如何拆分复杂任务
- 掌握上下文管理策略
- 适合 1-2 周后有一定经验时使用
行动 3: 建立项目的 CLAUDE.md
为你的项目创建 CLAUDE.md 文件,记录:
- 项目结构
- 代码规范
- 常用命令
- 特殊注意事项
参考: CLAUDE.md 模板
5.3 资源速查
| 资源 | 用途 | 何时使用 |
|---|---|---|
| ClaudeCode.md | 提示词模板库 | 查询特定模板语法 |
| 实战指南.md | 完整场景流程 | 执行复杂的多步骤任务 |
| README.md | 文档导航 | 不确定用哪个文档时 |
| CLAUDE.md | 项目规范 | 了解项目特定规范 |
| 进阶技巧.md | 高级技巧 | 1-2 个月后学习 |
5.4 常见问题
Q1: 我应该什么时候使用三段式?
答:
- ✅ 复杂度 > 简单修改时
- ✅ 不确定如何实现时
- ✅ 涉及多个文件协作时
- ❌ 非常简单的操作(如改个变量名)可以直接要求
Q2: 每次都要三个阶段吗?
答: 不一定
- 简单任务: 分析 + 实施(2 轮)
- 中等任务: 分析 + 设计 + 实施(3-5 轮)
- 复杂任务: 完整三段式(6-10 轮)
Q3: AI 理解错了怎么办?
答: 使用纠错模板
不对,{错误点说明}
正确理解应该是:
{详细说明}
请先复述正确理解,然后重新{操作}Q4: 如何知道我是否掌握了?
答: 自我检查
□ 能独立使用三段式完成一个中等任务?
□ 能准确使用 @ 引用和修饰符?
□ 知道何时说"不要写代码"?
□ 能识别并避免 5 个常见错误?
□ 完成了至少 1 个真实工作任务?
如果全部打勾,恭喜你已经掌握核心技能!🎉 恭喜完成学习!
你已经掌握了 Claude Code 的核心技能:
✅ 理解三段式工作流的价值 ✅ 掌握核心语法(@、修饰符、命令) ✅ 能够独立完成简单任务 ✅ 知道如何避免常见错误 ✅ 知道下一步如何提升
现在就去实践吧!
记住:
- 🎯 先分析,再设计,后实施
- 📍 使用 @ 精确引用
- 🛑 关键时刻说"不要写代码"
