Claude Code

这一课你将能做到

1. 用 CLAUDE.md 文件建立 Claude Code 的项目级记忆
2. 用 Plan 模式让 Claude Code 先规划后执行，避免它一上来就乱改
3. 在终端里完成一次「探索代码库 → 设计方案 → 实现 → 提交」的完整闭环

为什么要学

Claude Code 是 Anthropic 推出的终端 Agent 工具。和 Cursor 这类编辑器不同，它活在命令行里：你描述任务，它自己读文件、跑测试、执行 shell 命令、改代码，全程不需要你切窗口。对习惯终端的开发者，这是目前最接近「真正的 AI 结对工程师」的体验。

人话：Cursor 是「AI 住进了你的编辑器」，Claude Code 是「AI 住进了你的终端」。它特别擅长需要多步骤、跨文件、要跑命令验证的任务——比如「把这个模块从 MySQL 迁到 PostgreSQL」这种打开编辑器都不知道从哪下手的活。

真实场景中它的杀手锏是理解大型陌生代码库：接手一个没人敢动的老项目时，让它先给你画调用链、找关键文件，比自己 grep 一天快得多。

先建立图像

Claude Code 工作循环：
┌────────────────────────────────────────┐
│ 你：描述任务（自然语言）                 │
│   ↓                                    │
│ Claude Code：                          │
│   1. 读 CLAUDE.md（项目记忆）           │
│   2. 探索代码库（读文件、搜索、跑命令）   │
│   3. 制定计划（Plan 模式时可审批）       │
│   4. 执行：改代码、跑测试、看结果        │
│   5. 失败了自我修正，直到通过            │
│   ↓                                    │
│ 你：验收 diff，确认提交                  │
└────────────────────────────────────────┘

跟着做

步骤 1：安装与启动

npm install -g @anthropic-ai/claude-code
cd your-project
claude

首次启动需要登录 Anthropic 账号（或配置 API key）。进入交互界面后，你就面对一个能操作你项目的 AI 会话。

步骤 2：创建 CLAUDE.md

在项目根目录创建 CLAUDE.md——这是 Claude Code 每次启动自动读取的记忆文件：

# 项目说明
Spring Boot 3 + MyBatis-Plus 的文章收藏夹后端。

## 常用命令
- 启动：./mvnw spring-boot:run
- 测试：./mvnw test
- 单测单个类：./mvnw test -Dtest=ArticleServiceTest

## 代码约定
- Controller 只做参数校验和转发，业务在 Service
- 返回统一 Result<T>：{ code, message, data }
- 数据库表字段小写下划线，Java 字段驼峰，MyBatis-Plus 自动映射

## 注意
- 不要修改 application-prod.yml
- 数据库变更只写迁移 SQL，不直接动库

写好后运行 /init 命令，Claude Code 也可以自动分析项目帮你生成初版 CLAUDE.md，你再手工修订。

步骤 3：先用它探索一个陌生项目

找一个你不熟的开源项目（或公司里没人敢动的模块），启动 claude，输入：

这个项目的整体架构是什么？
HTTP 请求从进入到返回经过哪几层？
用户认证的完整调用链画出来。

观察它如何自己搜索文件、读代码、总结。这个能力在接手遗留系统时价值极大。

步骤 4：用 Plan 模式做受控修改

启动时加权限参数，或在会话中切换模式。给一个真实任务：

进入 plan 模式。
任务：给文章列表接口加按标签筛选功能。
要求：先读相关代码，给出修改计划（涉及哪些文件、每个文件改什么），
等我批准后再动手。

Plan 模式下它只读不写，输出计划：

计划：
1. ArticleMapper.xml：list 查询加 tag_id 条件
2. ArticleService：list 方法加 tagId 参数
3. ArticleController：GET /articles 加可选参数 tagId
4. 新增测试：ArticleServiceTest.testListByTag

你确认「执行」，它才开始改。这个「先审批后执行」的闸口，是 Claude Code 在真实项目里最常用的安全阀。

步骤 5：让它自我验证

任务执行后追加：

跑一下相关测试，确认没有回归。
如果测试失败，分析原因并修复，直到通过。

Claude Code 会自己执行 ./mvnw test，读失败输出，定位修复——这个「跑命令 → 看结果 → 修正」的自动循环是终端 Agent 区别于编辑器聊天的本质。

步骤 6：收尾提交

总结这次改动，生成一条符合 conventional commits 规范的提交信息。

确认信息后让它执行 git commit，或你自己审查 diff 后手动提交（推荐后者，提交前看一眼 diff 的习惯不要丢）。

讲清楚要点

1. CLAUDE.md 是单向记忆：它每次会话自动加载，是项目约定、常用命令、禁区的单一事实来源。团队共用一份，进 Git。
2. Plan 模式把「想」和「做」分开：复杂任务先让它出计划，你批准方向后再执行。方向错了改计划只要一分钟，方向错了改代码要一小时。
3. 权限分级：读文件、跑测试默认放行；写文件、执行命令按需审批。生产相关操作（数据库、部署）永远保持手动确认。
4. 自验证循环是核心价值：「改代码 → 跑测试 → 读报错 → 修复」的闭环让它能独立完成长任务，你的角色从「操作员」变成「验收员」。
5. 会话即上下文：一个任务一个会话。任务漂移了（从「修 bug」聊到「重构架构」）就开新会话，旧上下文会稀释注意力。

你可能会懵的地方

• 它和 Cursor 的 Agent 有什么区别？ 场景不同。Cursor 强在「你边写它边辅助」，Claude Code 强在「你交代任务它独立完成」。长链路任务（迁移、批量重构、跑测试修复循环）终端 Agent 更顺手；边写边改的精细控制编辑器更好。很多人两者混用。

• 它会不会乱执行危险命令？ 有权限系统：默认对写操作、bash 命令逐条请求许可；也可以用配置文件精细控制允许/禁止的命令列表（比如永远禁止 rm -rf 和 git push --force）。别把权限配置成「全部自动允许」。

• CLAUDE.md 和 .cursor/rules 能通用吗？ 内容层面基本可以互相迁移，格式略有差别。维护两份的成本不低，团队如果多工具混用，可以写一份主文档，其他工具的规则文件只做引用或软链。

• 它读我整个项目会不会很慢很贵？ 它会按需检索而不是全量加载，但大项目首次探索确实消耗 token。技巧：让它先输出「文件地图」（目录结构+关键文件清单），后续会话直接基于地图指定文件，跳过重复探索。

• 上下文窗口满了怎么办？ 用 /compact 命令压缩会话（保留关键结论），或让它把当前进度写入 CLAUDE.md / 进度文件，然后开新会话从文件恢复。长任务主动分段比等窗口爆掉再救要好。

错法对照

错法	问题	正解
不写 CLAUDE.md 直接开干	每次会话从零解释约定	维护 CLAUDE.md，团队共享进 Git
大任务直接「去做吧」	方向跑偏几小时才发现	Plan 模式先审批方向
权限全部自动放行	危险命令无闸口	写操作和 bash 保持审批，配禁止清单
一个会话做到天荒地老	上下文膨胀，输出质量下降	任务完成即结束，进度落盘开新会话
提交前不看 diff	幻觉代码进历史	git diff 过一遍再 commit

卡点急救

1. 它反复改不对同一个地方：缺关键信息。把相关接口文档、表结构、错误日志直接贴给它，或写入 CLAUDE.md 的「已知坑」部分。
2. 探索阶段就消耗大量 token：先让它只输出文件地图和关键文件清单，确认范围后再深入。
3. 测试跑不过它开始乱改：打断，让它「先只分析失败原因给报告，不要改代码」，定位后再让它动手。

面试常问

• 终端 Agent 和 IDE 插件形态的 AI 工具，工程上怎么选？ 高分回答：按任务形态选——交互式精细编辑用 IDE 工具，长链路自动化任务（迁移、批量重构、测试修复循环）用终端 Agent；两者可以共存，关键是统一的项目约定文件和相同的审查流程。

• 如何在 CI 或自动化流程中使用 Claude Code 这类 Agent？ 可以用于自动修复 lint 错误、依赖升级后的适配、生成变更日志等低风险任务；必须有完整测试套件做兜底，产物走 PR 人工审查，不允许直接推主分支。

• Agent 自主执行命令的安全边界怎么设？ 三层：工具自身的权限审批机制、配置文件的命令黑白名单、运行环境隔离（容器/普通用户权限）。生产凭证不进 Agent 可达的环境变量。

自测三问

1. CLAUDE.md 文件解决什么问题？它和普通 README 的区别是什么？
2. Plan 模式为什么能显著降低返工成本？
3. Claude Code 的「自验证循环」指什么？它为什么重要？

小结一句话

Claude Code 把 AI 从「聊天助手」变成「终端里能独立完成任务的工程师」——CLAUDE.md 给它记忆，Plan 模式给你刹车。

延伸

• Claude Code 官方文档
• CLAUDE.md 记忆机制
• 下一课：GitHub Copilot 与 Gemini——IDE 内置助手与多模态方案。