COURSE 04

AI 应用通识课程

Claude Code：理解 AI 编程助手的工作原理

不只是"怎么用"，而是"工具背后的原理"

课程目标

本课程旨在帮助学员

理解 Claude Code 的工作原理（不只是"怎么用"）
识别 Claude Code 的失败模式（什么时候会"沉默失败"）
判断什么场景适合用 Claude Code，什么场景不适合
建立对 AI 编程助手的正确心智模型

课程提纲

8 个部分

为什么需要 AI 编程助手？
Claude Code 的工作原理
Claude Code 的失败模式
实战场景演练
与其他工具的对比
安装和配置
最佳实践
理解深度测试

PART 01

为什么需要 AI 编程助手？

PART 01

场景：10 万行代码库的 API 迁移

假设你有一个 10 万行的 Python 项目，使用了某个第三方库的 API。现在这个库发布了 v2 版本，API 接口全部改了。你需要把所有调用从 v1 迁移到 v2。

问题来了：AI 编程助手是怎么做到的？

PART 01

三种解决方案对比

手动解决

用 grep 找到所有调用
逐个文件打开，手动修改
运行测试，看有没有漏改的

预计时间：3 天

容易出错

传统工具 (sed/awk)

写复杂的正则表达式
批量替换
难以处理复杂语法结构

预计时间：1 天

仍然容易漏

AI 编程助手

告诉它需求和文档
自动扫描、识别、修改
你审查修改、运行测试

预计时间：2 小时

效率提升 12 倍

PART 02

Claude Code 的工作原理

PART 02

核心架构：LLM + 工程层封装

三层架构回顾

应用层：Claude Code ← 我们在这里 ↓ 工程层：Prompt、Tool、Memory、MCP ↓ 模型层：Claude Opus 4.7 / Sonnet 4.6

关键理解：Claude Code 不是一个独立的 AI 模型，而是 LLM + 工程层封装的应用层产品。

PART 02

Claude Code 的组成

底层：模型

Claude Opus 4.7 或 Sonnet 4.6（LLM）

中间层：工程能力

Tool Use（工具调用）
Memory（对话历史）
上下文窗口管理

应用层：用户界面

命令行界面 / VS Code 插件 / Web 界面

PART 02

类比：工程同构映射

❌ 情感比喻（不准确）

"Claude Code 就像一个坐在你旁边的程序员同事"

问题：程序员同事有主观能动性、能理解隐含需求、能纠正你的错误。Claude Code 不行。

✅ 工程类比（准确）

Claude Code = 代码补全器 + 文件操作器 + 命令执行器

这是工程同构映射：每个组件都有明确的工程对应物，可以用来推断局限。

PART 02

Claude 模型家族：三个系列

模型	定位	特点	适用场景	Claude Code 使用
Opus	旗舰模型	最强推理能力、最大上下文窗口	复杂编程任务、架构设计	✅ 默认使用 Opus 4.7
Sonnet	平衡模型	性能与成本平衡、速度较快	日常编程、代码审查	✅ 可选 Sonnet 4.6
Haiku	轻量模型	响应速度最快、成本最低	简单补全、快速问答	❌ Claude Code 不使用

PART 02

为什么 Claude Code 主要用 Opus？

原因 1：强推理能力

理解复杂的代码逻辑
规划多步骤的重构任务
处理跨文件的依赖关系

原因 2：1M token 上下文

Opus 4.7 支持 1M token
可以看到整个大型项目
Haiku 上下文窗口较小

SWE-Bench Pro 基准测试：Opus 4.7 达到 64.3% 准确率（目前最强）

PART 02

模型类比：架构师 vs 工程师 vs 助手

Opus = 资深架构师

慢但深思熟虑，能处理复杂问题

Sonnet = 高级工程师

快速高效，能处理大部分日常任务

Haiku = 初级助手

极快响应，只能处理简单任务

实际建议：默认用 Opus，除非你明确知道任务很简单。不要因为成本而盲目降级——用错模型导致的返工成本更高。

PART 02

上下文窗口机制

Claude Opus 4.7 支持 1M token 上下文窗口

1 token ≈ 0.75 个英文单词 ≈ 0.5 个中文字符
1M token ≈ 75 万个英文单词 ≈ 50 万个中文字符

💡 版本提示：
• Claude Code 2.1.121+ 版本：完整支持 1M token
• Claude Code 2.1.116 及更早版本：限制为 200K token
• 建议使用最新版本以获得完整上下文窗口支持

这意味着什么？
Claude Code 可以一次性"看到"你整个大型项目的代码（如果项目不超过 50 万字），理解文件之间的依赖关系、函数调用链、数据流向。

PART 02

上下文窗口演示

项目结构示例

项目结构： - main.py (2000 字) - utils.py (1500 字) - models.py (3000 字) - config.py (500 字) 总计：7000 字 Claude Code 可以一次性读取所有文件，理解整个项目结构。

局限：如果项目超过 50 万字，Claude Code 只能看到部分代码。它会优先读取你明确提到的文件，或者项目的入口文件。

PART 02

Tool Use 机制

Claude Code 不是直接操作文件，而是通过"工具调用"。

工作流程

1. 你给任务："读取 main.py，把所有 print 改成 logging" ↓ 2. Claude Code 生成工具调用计划： - read_file("main.py") - 分析内容，找到所有 print 语句 - 生成新代码（替换 print 为 logging） - write_file("main.py", new_content) ↓ 3. 系统执行工具调用： - 读取文件内容，返回给 Claude Code - Claude Code 生成新代码 - 写入文件 ↓ 4. Claude Code 返回结果："已完成，修改了 15 处 print 语句"

PART 02

可用的工具

工具列表

read_file(path) # 读取文件内容 write_file(path, content) # 写入文件 list_files(directory) # 列出目录下的文件 run_command(command) # 执行命令行命令 search_files(pattern) # 搜索文件内容

关键点：Claude Code 不是"直接改文件"，而是"生成改文件的指令"。每个工具调用都是一次 API 请求。

PART 02

Memory 机制

Claude Code 会"记住"对话历史。但"记住"不等于"理解"——它只是把之前的对话文本加到上下文窗口里。

对话示例

# 第 1 轮对话你："读取 main.py" Claude Code："已读取，这是一个 FastAPI 应用" # 第 2 轮对话你："把所有路由改成异步函数" Claude Code：（它会记住第 1 轮的内容，知道你在说 main.py）

局限：如果对话太长，超过 1M token，早期的对话会被"遗忘"（从上下文窗口中移除）。Claude Code 不会主动总结对话历史。

PART 02

Agent 能力

Claude Code 可以"自主规划任务步骤"。

示例任务："找出项目中所有未使用的函数"

列出所有 Python 文件
读取每个文件，提取函数定义
搜索每个函数的调用位置
如果某个函数没有被调用，标记为"未使用"
输出结果

但这不是真正的推理，而是"生成一个看起来合理的步骤序列"。

PART 03

Claude Code 的失败模式

核心警告：Neural net training fails silently.
LLM 生成代码也会 silently fail.

PART 03

失败模式 1：沉默失败

代码看起来能工作，但在边界条件下崩溃。

案例：统计文件行数的函数

你的需求：

"写一个函数，统计一个文件的行数"

PART 03

Claude Code 生成的代码

count_lines.py

def count_lines(filename): with open(filename, 'r') as f: return len(f.readlines()) # 测试 print(count_lines('test.txt')) # 输出：10

看起来没问题，对吧？

PART 03

但如果文件很大...

如果文件很大（比如 1GB 的日志文件）：

f.readlines() 会把整个文件读入内存
导致内存溢出
程序崩溃

这就是"沉默失败"：它不会报错，但会在生产环境中崩溃。

PART 03

正确的写法

count_lines_correct.py

def count_lines(filename): count = 0 with open(filename, 'r') as f: for line in f: count += 1 return count

教学点：Claude Code 生成的代码"看起来能工作"，但在边界条件下会失败。你的责任：理解代码的逻辑，测试边界条件。

PART 03

失败模式 2：理解偏差

Claude Code 理解错了你的需求。

案例：优化代码

你的需求：

"帮我优化这段代码的性能"

Claude Code 的理解：

可能理解为"减少代码行数"
把所有变量名改成单字母（user_name → u）
删除所有注释
把多行代码合并成一行

PART 03

正确的需求描述

❌ 不好的描述

"帮我优化这段代码的性能"

问题：太模糊，Claude Code 可能理解错。

✅ 好的描述

"帮我优化这段代码的性能，重点是减少循环次数和内存占用，保持代码可读性"

明确、具体、无歧义。

教学点：Claude Code 是 System 1 思维者，只能做模式匹配，不能做真正的推理。你需要给出明确、具体、无歧义的需求描述。

PART 03

失败模式 3：工具调用失败

文件路径错误、权限不足等。

案例：读取不存在的文件

你的需求：

"读取 config.yaml 文件"

如果文件不存在：

Claude Code 调用 read_file("config.yaml")
系统返回错误：FileNotFoundError
Claude Code 可能理解错误信息，尝试读取其他路径
或者直接告诉你"文件不存在"

教学点：Claude Code 能处理简单的错误，但对于复杂的错误（网络超时、数据库连接失败），它可能理解不了。

PART 04

实战场景演练

PART 04

场景 1：重构一个大型函数

问题：

你有一个 200 行的函数，逻辑混乱，需要拆分成多个小函数。

手动解决：

需要 2 小时
容易出错（拆分后的函数可能引入新的 bug）

Claude Code 解决：给出任务 → 生成拆分方案 → 检查 → 运行测试

PART 04

拆分方案示例

before_after.py

# 原函数：200 行，做了 5 件事 def process_data(data): # 验证数据、清洗数据、转换格式、计算统计、保存结果 ... # 拆分后：5 个小函数 def validate_data(data): ... def clean_data(data): ... def transform_data(data): ... def calculate_stats(data): ... def save_results(data): ... def process_data(data): data = validate_data(data) data = clean_data(data) data = transform_data(data) stats = calculate_stats(data) save_results(stats)

PART 04

检查清单

检查拆分是否合理：

每个函数是否只做一件事？
拆分后的逻辑是否保持了原有功能？
有没有引入新的 bug？

运行测试

$ pytest test_process_data.py ===== test session starts ===== collected 5 items test_process_data.py ..... [100%] ===== 5 passed in 0.23s =====

局限：Claude Code 可能过度拆分或拆分不够。需要手动审查。

PART 04

场景 2：从零搭建一个 Web 项目

问题：

你想做一个 Todo List 应用，用 FastAPI + SQLite。

任务描述

用 FastAPI + SQLite 搭建一个 Todo List 应用，包含以下功能： 1. 创建任务（POST /tasks） 2. 获取所有任务（GET /tasks） 3. 更新任务状态（PUT /tasks/{id}) 4. 删除任务（DELETE /tasks/{id}) 数据库表结构： - id (主键) - title (任务标题) - completed (是否完成) - created_at (创建时间)

PART 04

生成的项目结构

项目结构

todo-app/ ├── main.py # FastAPI 应用入口 ├── models.py # 数据库模型 ├── database.py # 数据库连接 ├── requirements.txt # 依赖列表 └── test_main.py # 测试文件

手动解决需要 4 小时，Claude Code 可以在 15 分钟内生成完整项目。

PART 04

检查和测试

检查生成的代码：

数据库模型是否正确？
API 接口是否符合 RESTful 规范？
有没有 SQL 注入漏洞？
有没有参数验证？

测试 API

$ curl -X POST http://localhost:8000/tasks \ -H "Content-Type: application/json" \ -d '{"title": "学习 Claude Code"}' {"id": 1, "title": "学习 Claude Code", "completed": false}

局限：Claude Code 可能生成不安全的代码（没有参数验证、没有 SQL 注入防护）。

PART 04

场景 3：调试一个有 bug 的代码

问题：

你有一个 Python 脚本，运行时报错，但你看不出问题在哪里。

Claude Code 调试流程：

把错误信息和代码一起发给 Claude Code
Claude Code 分析错误原因
生成修复方案
你审查修复方案
运行测试，验证修复

局限：Claude Code 只能修复简单的错误（语法错误、运行时错误）。对于逻辑错误，它可能找不到问题。

PART 05

与其他工具的对比

PART 05

工具对比

工具	上下文窗口	Tool Use	Agent 能力	价格	适用场景
Claude Code	1M token	✅ 强	✅ 强	$20/月	大型项目重构、多文件协同修改
GitHub Copilot	~8K token	❌ 无	❌ 无	$10/月	日常编码、快速补全
Cursor	~32K token	✅ 中	✅ 中	$20/月	新手友好、开箱即用

PART 05

技术原因分析

为什么 Claude Code 适合大型项目？

1M token 上下文窗口
Tool Use 能力强
Agent 能力强

为什么 Copilot 适合日常编码？

响应速度快（~100ms）
集成度高
但上下文窗口小

为什么 Cursor 适合新手？

界面友好
开箱即用
但上下文窗口中等

PART 05

组合使用建议

日常编码用 Copilot 快速补全
复杂任务用 Claude Code 规划和实现
新手入门用 Cursor 熟悉 AI 编程

关键理解：不同工具有不同的优势和局限，根据任务特点选择合适的工具。

PART 06

安装和配置

PART 06

快速安装步骤

1. 安装 Node.js

Terminal

$ node --version

v20.11.0

# 如果未安装，去 https://nodejs.org/ 下载 LTS 版本

2. 安装 Claude Code

Terminal

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

3. 验证安装

Terminal

$ claude-code --version

2.1.128

4. 登录账号

Terminal

$ claude-code login

PART 07

最佳实践

PART 07

最佳实践 1：清晰的需求描述

❌ 不好的描述

"帮我写个登录功能"

"优化这段代码"

"修复这个 bug"

问题：太模糊，Claude Code 可能理解错你的需求

✅ 好的描述

"写一个 Python 函数，输入是用户名和密码，输出是 JWT token。使用 PyJWT 库，token 有效期 24 小时，包含用户 ID 和角色信息。"

"优化这段代码的性能，重点是减少循环次数和内存占用，保持代码可读性"

"修复这个 bug：当输入为空列表时，函数抛出 IndexError"

原因：明确、具体、无歧义

PART 07

最佳实践 2：分步骤执行

为什么重要？减少沉默失败的风险，每完成一步确认后再继续

示例：重构大型函数

步骤 1："读取 main.py，告诉我主要的功能模块"

→ 确认 Claude Code 理解了项目结构

步骤 2："把 process_data 函数拆分成多个小函数"

→ 检查拆分方案是否合理

步骤 3："运行测试，看是否通过"

→ 验证重构没有引入新的 bug

PART 07

最佳实践 3：代码审查清单

为什么重要？Claude Code 是 System 1 思维者，不能做真正的推理

检查清单

☐ 代码逻辑是否正确？

☐ 有没有边界条件处理？（空列表、大文件、特殊字符）

☐ 有没有错误处理？（try-except、错误信息）

☐ 有没有安全漏洞？（SQL 注入、XSS、参数验证）

☐ 代码可读性如何？（变量命名、函数拆分、注释）

PART 08

理解深度测试

PART 08

四个理解深度 Level

Level 1

能用 Claude Code 完成简单任务

测试：让 Claude Code 写一个 Python 脚本，统计文件行数

通过标准：能正确描述需求、能运行生成的代码、能看懂代码的基本逻辑

Level 2

能判断生成的代码是否正确

测试：让 Claude Code 写一个函数，你能指出它的 bug

通过标准：能识别边界条件问题、能识别性能问题、能识别安全问题

Level 3

能用 Claude API 自己实现简化版

测试：用 50 行 Python 调用 Claude API，实现"读文件 → 生成代码 → 写文件"的流程

通过标准：理解上下文窗口机制、理解 Tool Use 机制、能处理简单的错误

Level 4

能判断什么时候该用、什么时候不该用

测试：给你 5 个编程任务，你能说出哪些适合用 Claude Code，哪些不适合，以及原因

通过标准：理解 Claude Code 的优势和局限、能根据任务特点选择合适的工具、能预测失败模式

课后练习

练习 1（Level 1）：完成简单任务

让 Claude Code 写一个 Python 脚本，读取当前目录下的所有 .txt 文件，统计每个文件的行数和字数，输出一个汇总报告。

练习 2（Level 2）：找出 bug

让 Claude Code 写一个函数，计算一个列表的平均值。然后找出它的 bug（提示：空列表会导致除零错误）。

练习 3（Level 3）：实现简化版

用 Claude API 实现一个简化版的 Claude Code：

读取一个文件
让 Claude 生成优化后的代码
写回文件

练习 4（Level 4）：判断适用场景

以下 5 个任务，哪些适合用 Claude Code？为什么？

写一个 "Hello World" 程序
重构一个 10 万行的代码库
调试一个复杂的并发 bug
生成一个 REST API 的完整代码
优化一个算法的时间复杂度

总结

Claude Code 不是魔法，而是 LLM + 工程层封装

理解原理，才能用好工具

Neural net training fails silently.
LLM 生成代码也会 silently fail.

你的责任：理解代码逻辑，测试边界条件，审查安全问题

下节课预告：安装配置 OpenClaw，接入 QQ/飞书/微信，搭建你的第一个 AI 助手