Skip to content

Claude Code 快速上手教程 ​

零基础友好 | 学练结合 | 快速提升 70% 开发效率

学习目标: 掌握 Claude Code 的核心使用技能,显著提升开发效率

适用对象: 从未使用过 Claude Code 的开发者

学习方式: 建议按顺序学习,每个章节包含理论 + 实践


📚 课程大纲 ​

部分内容形式
第一部分核心理念理论
第二部分必备技能理论 + 练习
第三部分实战演练场景 + 练习
第四部分快速避坑案例
第五部分下一步指引

第一部分:核心理念 ​

1.1 为什么需要结构化提示词 ​

传统方式的问题 ​

❌ 问题场景:

bash
开发者: "帮我写一个订单功能"
AI: (生成 500 行代码)
开发者: "这个不对,我需要支持会员折扣"
AI: (重新生成 500 行代码)
开发者: "还要支持免费次数..."
AI: (再次重新生成...)

问题:

  • 💸 浪费大量 token
  • 🔄 反复返工
  • 😰 代码质量不可控
  • ⏰ 效率低下

结构化方式的优势 ​

✅ 正确场景:

bash
【分析阶段】
开发者: "讨论订单功能需求,不要写代码"
AI: "理解需求,识别 4 种计费场景..."
开发者: "理解正确"

【设计阶段】
开发者: "给出 2-3 个实现方案,不要写代码"
AI: "方案 A: 统一入口... 方案 B: 分散处理..."
开发者: "采用方案 A"

【实施阶段】
开发者: "按方案 A 开始编码"
AI: "生成符合预期的代码"
开发者: "完美!"

优势:

  • ✅ 一次到位,减少返工
  • ✅ 节省 token 成本
  • ✅ 代码质量可控
  • ✅ 效率大幅提升

1.2 三段式工作流 ​

这是 Claude Code 协作的核心方法论:

bash
┌─────────────────────────────────────────┐
│  阶段 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: @ 文件引用符 ​

作用: 精确引用文件或代码段

格式:

bash
@文件路径                    # 引用整个文件
@文件路径#L50                # 引用第 50 行
@文件路径#L50-80             # 引用第 50-80 行
@文件1 @文件2                # 引用多个文件

示例:

bash
# 引用整个文件
@api/v1/order.go

# 引用特定行
@service/user.go#L100

# 引用范围
@service/order.go#L50-80

# 引用多个文件
@api/v1/order.go @service/order.go

为什么重要?

bash
❌ 错误: "订单文件的第 100 行左右那个函数"
   - AI 可能找错位置
   - 描述模糊不准确

✅ 正确: "@service/order.go#L100-120"
   - 精确定位
   - 不会出错

语法 2: 关键修饰符 ​

修饰符 1: "不要写代码"

bash
用途: 限制 AI 只分析讨论,不生成代码
使用场景: 分析阶段、设计阶段

示例:
@service/order.go#L50-100
解释一下订单创建的完整流程,不要写代码

修饰符 2: "先说明"

bash
用途: 要求 AI 先给出方案,等确认后再执行
使用场景: 复杂修改前、风险较高的操作

示例:
@api/v1/user.go#L50-80
删除 deprecated 字段,先说明影响范围,不要写代码

修饰符 3: "直接修改"

bash
用途: 跳过讨论,立即执行
使用场景: 简单操作、已经明确的修改

示例:
@model/user.go#L20
将 UserID 改为 UID,直接修改

语法 3: / 命令符 ​

bash
/clear          清空上下文
/think          深度思考模式

使用场景:

bash
/clear 使用时机:
  ✅ 切换到完全不同的任务
  ✅ 上下文超过 50 轮对话
  ✅ AI 开始混淆之前的内容
  ❌ 任务进行中(会丢失上下文)
  ❌ 仅仅换了个文件

/think 使用时机:
  ✅ 复杂的架构设计
  ✅ 难以抉择的技术选型
  ✅ 需要深度分析的问题

语法 4: 结构化描述 ​

使用标识符组织信息:

bash
【需求背景】
现有功能管理页面混乱,需要重新设计

【功能目标】
实现统一的功能管理,包括:
- 价格配置
- 免费次数设置
- 平台支持

【技术要求】
- 响应时间 < 500ms
- 支持批量导入
- 配置变更要有审计日志

为什么使用结构化?

  • ✅ 信息清晰,不遗漏
  • ✅ AI 更容易理解
  • ✅ 便于后续追溯

语法 5: 占位符约定 ​

在模板中使用占位符:

bash
{文件}     → api/v1/user.go
{行号}     → #L100-120
{功能}     → 订单创建逻辑
{模块}     → user_benefit
{方案X}    → 方案A
{字段}     → member_level

示例:

bash
模板:
@{文件}#{行号} 解释{功能},不要写代码

实际使用:
@api/v1/order.go#L50-100 解释订单创建逻辑,不要写代码

2.2 三段式工作流实操 ​

阶段 1: 分析 ​

目标: 理解现状,不要盲目修改

核心模板:

bash
@{文件}#{行号} 解释一下{功能/逻辑},不要写代码

完整示例:

bash
@api/v1/order.go#L50-100
解释一下订单创建的完整流程,不要写代码

请说明:
1. 输入参数和返回值
2. 核心步骤分解
3. 边界条件处理
4. 错误处理方式

AI 会输出:

  • 函数的核心逻辑
  • 关键步骤说明
  • 边界条件
  • 潜在问题

你要做的:

  • 确认理解是否正确
  • 识别遗漏的部分
  • 决定是否需要看更多代码

阶段 2: 设计 ​

目标: 制定方案,充分讨论

核心模板:

bash
讨论需求,不要写代码
{详细需求描述}

有没有更好的方案,不要写代码

完整示例:

bash
讨论需求,不要写代码

【当前功能】
订单创建接口,所有用户统一价格

【需要增加的逻辑】
根据用户类型计费:
- 场景 1: 免费功能,直接创建订单
- 场景 2: 付费功能,优先扣免费次数
- 场景 3: 无免费次数,会员按会员价
- 场景 4: 非会员按原价

【技术要求】
- 免费次数扣减和订单创建要在同一事务
- 会员价 = 原价时,不显示会员标识

请给出 2-3 个实现方案,不要写代码

AI 会输出:

  • 方案 A、B、C
  • 每个方案的优缺点
  • 推荐方案和理由

你要做的:

bash
采用方案 B,请详细说明实施步骤,不要写代码

包括:
1. 数据查询顺序
2. 判断逻辑
3. 事务范围
4. 返回字段设计

阶段 3: 实施 ​

目标: 编写代码,分步执行

核心模板:

bash
采用方案{X},开始编码

要求:
- 遵循 CLAUDE.md 中的规范
- {其他约束条件}

完整示例:

bash
采用方案 B,开始编码

【编码规范】
- 遵循 CLAUDE.md 中的分层规范
- 参考 user_benefit 模块的实现方式
- 错误处理统一使用 pkg/errors

【实施顺序】
1. 先完成 Model 层(数据查询)
2. 再完成 Service 层(业务逻辑)
3. 最后完成 API 层(接口暴露)

每完成一层暂停,等我确认后继续

AI 会输出:

  • 按顺序生成代码
  • 每层完成后暂停

你要做的:

bash
# 确认第一层
ok,继续 Service 层

# 确认第二层
ok,继续 API 层

# 全部完成
完美,生成单元测试

💡 动手练习 1 ​

任务: 使用三段式工作流理解一个函数

假设你有一个文件 service/user.go,其中 L50-100 是用户注册函数。

请写出:

  1. 分析阶段的提示词
  2. 设计阶段的提示词(假设要增加手机号验证)
  3. 实施阶段的提示词

提示:

  • 记得使用 @ 引用
  • 记得加"不要写代码"
  • 使用结构化描述

参考答案(不要偷看,先自己写):

点击查看参考答案
bash
【分析阶段】
@service/user.go#L50-100
解释一下用户注册函数的完整流程,不要写代码

请说明:
1. 当前的验证逻辑
2. 数据存储方式
3. 错误处理

【设计阶段】
讨论需求,不要写代码

【当前功能】
用户注册,验证邮箱后创建账户

【需要增加】
增加手机号验证:
- 发送验证码
- 验证码 5 分钟有效
- 验证通过后才能注册

请给出实现方案,不要写代码

【实施阶段】
采用你推荐的方案,开始编码

要求:
- 遵循现有的错误处理方式
- 验证码存储在 Redis
- 每完成一个函数暂停

第三部分:实战演练 ​

3.1 场景 1: 简单逻辑增加 ​

场景描述 ​

任务: 在用户信息接口中,如果用户是会员,额外返回会员等级和过期时间

当前代码:

go
// 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 轮: 理解 + 设计 ​

bash
@api/v1/user.go#L50-80

【当前功能】
获取用户基本信息接口

【需要增加】
如果用户是会员,额外返回:
- member_level: 会员等级
- member_expire_at: 会员过期时间

【要求】
- 非会员用户不返回这些字段
- 使用 omitempty 保持向后兼容

请先:
1. 复述当前函数逻辑
2. 说明修改建议

不要写代码

第 2 轮: 实施 ​

bash
方案合理,开始修改

要求:
- 新增字段使用 json:",omitempty" 标签
- 添加注释说明

关键要点 ​

✅ 正确做法:

  • 先理解现状
  • 使用 omitempty 保持兼容性
  • 分步执行

❌ 常见错误:

  • 直接要求加字段,没理解现有逻辑
  • 忘记向后兼容
  • 没有测试非会员场景

💡 动手练习 2 ​

任务: 在商品列表接口中,如果商品有折扣,额外返回折扣信息

提示:

  1. 参考场景 1 的流程
  2. 思考:折扣信息包含哪些字段?
  3. 思考:如何判断商品是否有折扣?
  4. 写出完整的 2 轮提示词

3.2 场景 2: Bug 修复 ​

场景描述 ​

Bug 现象: 用户反馈,订单创建后扣了两次免费次数

问题代码:

go
// 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 轮: 问题复现 ​

bash
遇到以下问题,请帮助定位

【问题描述】
用户创建订单后,免费次数被扣减了 2 次

【复现步骤】
1. 用户有 5 次免费次数
2. 创建 1 个订单
3. 免费次数变成 3(应该是 4)

【预期行为】
创建 1 个订单,免费次数扣减 1 次

【相关代码】
@service/order.go#L100-130

请分析可能的原因,不要写代码

第 2 轮: 根因分析 ​

bash
基于代码分析根本原因,不要写代码

【分析内容】
1. 为什么会扣两次?
2. 是否有并发问题?
3. 是否缺少事务?

第 3 轮: 修复方案 ​

bash
请给出修复方案,不要写代码

【方案要求】
1. 解决并发问题
2. 保证事务一致性
3. 最小化改动

如有多个方案,请对比说明

第 4 轮: 实施修复 ​

bash
采用方案 A(使用事务),开始修复

要求:
- 订单创建和次数扣减在同一事务
- 添加错误回滚逻辑

关键要点 ​

✅ 正确做法:

  • 详细描述问题现象
  • 分析根本原因
  • 方案要考虑并发
  • 使用事务保证一致性

❌ 常见错误:

  • 描述不清晰
  • 没考虑并发场景
  • 直接要求改代码,没分析原因

💡 动手练习 3 ​

Bug: 用户修改密码后,仍然能用旧密码登录

提示:

  1. 写出问题复现的提示词
  2. 写出根因分析的提示词
  3. 思考可能的原因(缓存?token?)

3.3 场景 3: 方案选择 ​

场景描述 ​

需求: 系统需要支持多种计费方式(按次、按天、按月、阶梯定价)

当前: 只支持按次计费

复杂度: 🔴 复杂(4-6 轮)


第 1 轮: 需求讨论 ​

bash
讨论需求,不要写代码

【背景】
当前订单系统只支持按次计费

【新需求】
需要支持 4 种计费方式:
1. 按次计费(现有)
2. 按天计费(24 小时有效)
3. 按月计费(30 天有效)
4. 阶梯定价(用量越多,单价越低)

【技术要求】
- 不能影响现有按次计费的订单
- 需要支持未来新增计费方式
- 计费逻辑要可配置

请分析:
1. 现有架构是否支持
2. 需要新增哪些表/字段
3. 主要技术难点

第 2 轮: 方案对比 ​

bash
基于以上分析,请提供 2-3 个设计方案,不要写代码

对比维度:
- 实施复杂度
- 扩展性
- 维护成本
- 对现有系统的影响

第 3 轮: 详细设计 ​

bash
采用方案 B(策略模式),请详细说明实施步骤,不要写代码

包括:
1. 数据库设计(表结构/字段)
2. 代码分层设计
3. 如何保证向后兼容
4. 实施顺序

第 4 轮: 需求确认 ​

bash
请复述以下内容,确认理解一致,不要写代码:

1. 数据库设计
2. 计费策略如何选择
3. 如何保证现有订单不受影响
4. 新增计费方式的流程

第 5-6 轮: 分步实施 ​

bash
确认无误,开始编码

【实施顺序】
1. 先完成数据库变更
2. 再完成计费策略接口
3. 实现 4 种计费策略
4. 修改订单创建逻辑

每完成一步暂停

关键要点 ​

✅ 正确做法:

  • 充分的需求讨论
  • 多个方案对比
  • 详细的设计阶段
  • 需求复述确认
  • 分步实施

❌ 常见错误:

  • 没有方案对比就选定方案
  • 忽略向后兼容性
  • 没有考虑扩展性
  • 一次性实现所有功能

第四部分:快速避坑 ​

4.1 五个最常见错误 ​

错误 1: 没理解就修改 ​

❌ 错误示例:

bash
@service/order.go#L50-150
帮我在这里加个会员判断逻辑

问题:

  • AI 不知道插入哪里
  • 不知道变量是否已初始化
  • 可能破坏原有流程

✅ 正确做法:

bash
@service/order.go#L50-150
请先解释当前函数的完整逻辑,不要写代码

(AI 解释后)

理解正确,现在在"校验权限"之后插入会员判断逻辑

错误 2: 描述不清晰 ​

❌ 错误示例:

bash
订单文件的第 100 行左右那个函数,改一下

问题:

  • 位置模糊
  • 操作不明确

✅ 正确做法:

bash
@service/order.go#L100-120

将 OrderType 字段改为 FunctionKey,要求:
- 更新所有引用
- 保持向后兼容

错误 3: 忽略并发安全 ​

❌ 错误示例:

bash
帮我实现扣减免费次数的逻辑

问题:

  • 没说明并发场景
  • AI 可能生成非并发安全的代码

✅ 正确做法:

bash
实现扣减免费次数的逻辑

【并发要求】
- 需要并发安全(同一用户可能同时创建多个订单)
- 使用数据库事务或乐观锁
- 扣减失败要有明确提示

请先说明并发处理方案,不要写代码

错误 4: 破坏兼容性 ​

❌ 错误示例:

bash
删除 user 表的 nickname 字段

问题:

  • 可能有地方还在用
  • 可能导致线上故障

✅ 正确做法:

bash
@model/user.go

删除 nickname 字段前,请先:
1. 搜索所有引用该字段的位置
2. 评估影响范围
3. 给出兼容性迁移方案

不要写代码

错误 5: 上下文混乱 ​

❌ 错误现象:

bash
# 第 50 轮对话
开发者: "继续上一个任务"
AI: "混淆了 20 轮前的任务和 40 轮前的任务"

问题:

  • 对话太长
  • 任务切换没清空上下文

✅ 正确做法:

bash
# 切换任务时
/clear

继续订单模块开发

【上次进度】
- 已完成: Model 层、Service 层
- 当前: 需要完成 API 层
- 关键决策: 采用方案 B(统一入口)

请先复述关键决策,然后继续

4.2 快速检查清单 ​

在发送提示词前,快速检查:

bash
□ 是否使用 @ 精确引用了文件?
□ 分析/设计阶段是否加了"不要写代码"?
□ 需求描述是否清晰完整?
□ 是否考虑了并发安全?
□ 是否考虑了向后兼容?
□ 是否使用结构化描述(【】标识)?
□ 复杂修改是否先说明方案?

第五部分:下一步 ​

5.1 学习路径 ​

bash
┌─────────────────────────────────────────┐
│ 你现在的位置                             │
│ ✅ 掌握了核心理念和语法                   │
│ ✅ 学会了三段式工作流                     │
│ ✅ 完成了 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 理解错了怎么办? ​

答: 使用纠错模板

bash
不对,{错误点说明}

正确理解应该是:
{详细说明}

请先复述正确理解,然后重新{操作}

Q4: 如何知道我是否掌握了? ​

答: 自我检查

bash
□ 能独立使用三段式完成一个中等任务?
□ 能准确使用 @ 引用和修饰符?
□ 知道何时说"不要写代码"?
□ 能识别并避免 5 个常见错误?
□ 完成了至少 1 个真实工作任务?

如果全部打勾,恭喜你已经掌握核心技能!

🎉 恭喜完成学习! ​

你已经掌握了 Claude Code 的核心技能:

✅ 理解三段式工作流的价值 ✅ 掌握核心语法(@、修饰符、命令) ✅ 能够独立完成简单任务 ✅ 知道如何避免常见错误 ✅ 知道下一步如何提升

现在就去实践吧!

记住:

  • 🎯 先分析,再设计,后实施
  • 📍 使用 @ 精确引用
  • 🛑 关键时刻说"不要写代码"

版本: v1.1 最后更新: 2025-10-23 下一步: 实战指南.md 或 进阶技巧.md