Claude Code 进阶

在第十一课中，我们学会了：

• CLAUDE.md的三种存放位置（项目级、个人全局、个人项目级）
• 基本模板结构（项目说明、构建命令、代码规范、注意事项）
• 用 /init 命令自动生成初始版本

这些是入门级用法。接下来，我们要学习让CLAUDE.md真正发挥威力的高级技巧。

CLAUDE.md支持用 @ 符号引用项目中的其他文件，让AI在需要时自动读取这些文件的内容：

## 项目配置
详细依赖见 @package.json
项目说明见 @README.md
API接口规范见 @docs/api-spec.yaml

这样做的好处是避免在CLAUDE.md中重复维护已经存在于其他文件中的信息。当 package.json 更新了依赖，CLAUDE.md不需要同步修改——AI会直接去读最新版本。

当项目规范较多时，把所有规则塞进一个CLAUDE.md会变得又长又难维护。更好的做法是使用 .claude/rules/ 目录，将规则拆分为多个文件：

.claude/
  rules/
    testing.md        # 测试相关规范
    api-design.md     # API设计规范
    security.md       # 安全规范
    code-style.md     # 代码风格
    git-workflow.md   # Git工作流规范

每个文件专注于一个领域的规范。Claude Code启动时会自动读取 .claude/rules/ 目录下的所有文件。这种方式的优势是：

• 不同领域的规范由不同的负责人维护
• 新增规范只需添加文件，不需要修改现有文件
• 每个文件保持简短，易于阅读和审查

有些规范只对特定类型的文件生效。例如，测试文件有测试文件的写法要求，前端组件有前端组件的要求。你可以在规则文件的YAML frontmatter中使用 paths 字段来限定生效范围：

---
paths:
  - "src/components/**/*.tsx"
  - "src/components/**/*.ts"
---

# 前端组件规范

- 所有组件使用函数组件 + Hooks
- 组件文件名使用PascalCase
- 每个组件必须导出对应的Props类型定义
- 使用Ant Design组件库，禁止引入其他UI库

这条规则只在Claude Code操作 src/components/ 下的 .tsx 和 .ts 文件时生效。操作其他文件时，这些规则不会被加载，既节省上下文空间，又避免不相关的规范造成干扰。

除了你手动编写的CLAUDE.md，Claude Code还会自动积累使用过程中的知识。当你在对话中纠正AI的行为（比如"我们项目不用分号"），Claude Code可能会自动记住这个偏好。

自动记忆存储在：

~/.claude/projects/<project-hash>/memory/

你可以用 /memory 命令查看和编辑这些自动积累的记忆：

> /memory

这个命令会列出Claude Code为当前项目记住的所有信息，你可以删除不准确的记忆，或手动添加新的条目。

一份好的CLAUDE.md不在于长，而在于有效。以下四条原则可以帮你写出高质量的指令：

具体可验证是最重要的原则。"写好代码"不是一条有效的指令，因为AI无法判断什么叫"好"。而"所有函数必须有JSDoc注释"是一条有效指令——做了就是做了，没做就是没做，没有灰色地带。

以下是一个电商后台管理系统项目的完整CLAUDE.md。注意它的结构组织和指令的具体程度：

# 项目：电商后台管理系统

## 技术栈
- 前端：React 18 + TypeScript + Ant Design
- 后端：Node.js + Express + PostgreSQL
- 测试：Jest + React Testing Library

## 构建与运行
- npm install 安装依赖
- npm run dev 启动开发服务器（端口3000）
- npm run build 构建生产版本
- npm test 运行全部测试
- npm run test:watch 监听模式运行测试

## 代码规范
- 组件使用函数组件 + Hooks，禁止使用类组件
- API请求统一使用 src/utils/request.ts 中的封装
- 所有新增API接口必须添加TypeScript类型定义
- 数据库查询使用参数化查询，禁止字符串拼接SQL
- 变量命名：camelCase，组件命名：PascalCase

## 文件结构约定
- 页面组件放在 src/pages/
- 公共组件放在 src/components/
- API接口定义放在 src/api/
- 工具函数放在 src/utils/

## 禁区（不要修改）
- .env 和 .env.* 文件
- database/migrations/ 目录下的已有迁移文件
- public/config.js 运行时配置

## 提交规范
- 提交前必须通过 npm test
- 提交信息格式：type(scope): description
- type: feat/fix/refactor/test/docs

这份CLAUDE.md的优点在于：

• 篇幅适中：不到50行，覆盖了项目最关键的信息
• 指令具体：每条规范都可以明确判断是否遵守
• 有"禁区"：明确告诉AI哪些文件不能碰，这是防止AI误操作的关键手段
• 有构建命令：AI不需要猜测如何运行项目

如果基础CLAUDE.md是新员工的"入职手册"，那么深度配置后的CLAUDE.md就是一份完整的"部门运营手册"——它不仅告诉新人公司是做什么的，还告诉他每个场景下该遵守什么规矩、哪些红线不能碰、遇到问题找谁。有了这样一份手册，AI就能像一个有经验的团队成员一样工作。

并非所有任务都需要Plan Mode。以下场景特别推荐使用：

相反，如果只是"给这个函数加个参数"这种简单任务，直接用默认模式更高效。

假设你要给一个Express后端项目添加用户认证功能，涉及多个文件的新增和修改。以下是使用Plan Mode的完整流程：

第一步：启动Plan Mode

在描述任务时，你可以明确要求Claude Code先制定计划：

> 请先制定计划，不要直接执行。我需要给这个Express项目添加JWT用户认证，
  包括注册、登录、Token验证中间件。

Claude Code进入计划模式后，会开始分析代码库但不会修改任何文件。

第二步：Claude分析代码库，列出详细步骤

Claude Code会给出类似这样的计划：

计划：添加JWT用户认证

1. 安装依赖
   - 添加 jsonwebtoken, bcryptjs, express-validator

2. 创建用户模型
   - 新建 src/models/User.js
   - 定义用户Schema（username, email, password_hash）

3. 创建认证中间件
   - 新建 src/middleware/auth.js
   - 实现Token验证逻辑

4. 创建认证路由
   - 新建 src/routes/auth.js
   - 实现 POST /register 和 POST /login

5. 注册路由
   - 修改 src/app.js，挂载认证路由

6. 添加测试
   - 新建 src/__tests__/auth.test.js
   - 覆盖注册、登录、Token验证三个场景

预计修改文件：2个现有文件 + 4个新文件

第三步：审查和修改计划

你审查这个计划，发现几个问题：

> 计划整体不错，但有几个调整：
  1. 密码加密用 argon2 替代 bcryptjs，更安全
  2. 用户模型增加 created_at 字段
  3. 先不加测试，我想先看到功能跑通

第四步：Claude更新计划

Claude Code会根据你的反馈更新计划。你确认无误后批准执行。

第五步：按计划执行

批准后，Claude Code按照商定的计划逐步执行。你可以看到它正在执行计划的哪一步。

第六步：执行过程中仍可干预

即使在执行阶段，你仍然可以随时按 Ctrl+C 中断操作，或者输入新的指令来调整方向。Plan Mode的"计划"不是死板的合同，而是一个可以灵活调整的导航路线。

总结Plan Mode的三个核心价值：

• 避免走错方向后才发现：在动手之前就能看到AI打算怎么做，方向不对立刻纠正
• 让你对将要发生的事有预期：知道会改哪些文件、改什么内容，心里有底
• 适合复杂任务的风险控制：影响范围越大的任务，事前规划越重要

Plan Mode就像装修前先看设计图。没有设计图的装修，工人凭感觉干活，等你回家一看——"这面墙怎么被拆了？！"有了设计图，你在施工开始之前就能发现问题，修改设计图的成本远低于拆了重装。

Claude Code的默认模式就是"边装修边设计"，适合刷个墙、换个灯这种小活。Plan Mode就是"先出图再施工"，适合整体翻新这种大工程。

用几个具体场景来理解MCP的实际价值：

举一个实际的工作流例子：你在Sentry上看到一个线上报错，对Claude Code说"帮我分析Sentry上最近的这个TypeError"。如果安装了Sentry MCP Server，Claude Code就能直接从Sentry获取错误详情和堆栈信息，然后结合项目代码定位问题、提出修复方案。整个过程不需要你手动复制粘贴错误信息。

MCP Server根据运行方式分为三种类型：

对于大多数用户来说，HTTP远程服务器是最常用的类型——它连接的是已经在云端运行好的服务，你只需要添加一下连接信息即可。Stdio本地服务器则适合需要连接本地资源（如本地数据库）的场景。

Claude Code提供了 claude mcp 命令来管理MCP Server：

# 添加HTTP远程服务器（最常用）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 添加本地Stdio服务器（例如连接本地数据库）
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb"

# 查看已安装的MCP Server列表
claude mcp list

# 删除一个MCP Server
claude mcp remove notion

安装完成后，在Claude Code交互界面中可以用 /mcp 命令检查MCP Server的状态：

> /mcp

这会显示所有已连接的MCP Server及其当前状态（正常运行、连接失败等）。

和CLAUDE.md类似，MCP配置也有不同的作用域：

团队共享是一个重要的应用场景。比如你的团队都需要连接同一个GitHub仓库和同一个数据库，就可以把MCP配置写入 .mcp.json 并提交到Git仓库，所有成员拉取代码后自动获得相同的MCP连接。

以连接GitHub为例，展示完整的安装和使用流程：

# 第一步：安装GitHub MCP Server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 第二步：进入Claude Code，检查连接状态
claude
> /mcp
# 应该看到github服务器状态为"connected"

# 第三步：开始使用
> 帮我看看PR #42的改动，有没有潜在问题
> 给Issue #15添加一条评论，说明修复方案
> 列出最近一周被标记为bug的Issue

安装完成后，Claude Code就像"长了一双新的手"——它不仅能操作本地文件，还能直接和GitHub交互。

MCP就像手机的App Store。Claude Code是手机本身，具备打电话、发短信这些基础功能。MCP Server就是各种App——装了微信就能聊天，装了支付宝就能付款，装了地图就能导航。每个MCP Server赋予Claude Code一种新的能力，而你可以根据需要自由组合。

Claude Code支持四种Hook事件：

其中 PostToolUse 是最常用的——它让你能在Claude Code每次修改文件后自动做一些标准化处理。

Hooks在 settings.json 中配置。配置结构如下：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

这段配置的含义是：每当Claude Code执行了Write（写入文件）或Edit（编辑文件）操作后，自动对被修改的文件运行Prettier格式化工具。$CLAUDE_FILE_PATH 是一个环境变量，表示被操作的文件路径。

matcher 字段用正则表达式匹配工具名称，支持 | 表示"或"。command 是要执行的Shell命令。

每次编辑文件后，自动运行代码格式化工具：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

效果：Claude Code每次修改文件后，文件会自动按照Prettier的规则格式化。你不再需要在CLAUDE.md里费心描述缩进、分号、引号等格式规范——Prettier会自动统一处理。

每次修改 .ts 或 .js 文件后，自动运行相关测试：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo $CLAUDE_FILE_PATH | grep -qE '\\.(ts|js)$'; then npx jest --findRelatedTests $CLAUDE_FILE_PATH --passWithNoTests; fi"
      }
    ]
  }
}

效果：AI每改一个代码文件，相关的测试就会自动运行。如果测试失败，Claude Code会立即知道并尝试修复。

在工具调用之前检查，如果目标是 .env 文件，则拒绝操作：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "if echo $CLAUDE_FILE_PATH | grep -qE '\\.env'; then echo 'BLOCKED: .env文件禁止修改' && exit 1; fi"
      }
    ]
  }
}

效果：即使你或AI不小心要修改 .env 文件，Hook也会拦截这个操作。退出码非0（exit 1）会阻止Claude Code继续执行该操作。

使用Hooks需要注意以下几点：

• Hook执行失败会阻止Claude Code继续操作：如果Hook脚本返回非0退出码，Claude Code会认为操作被拒绝。确保你的Hook脚本在正常情况下不会意外失败。
• Hook命令的执行时间不宜过长：每次工具调用都会触发Hook。如果Hook脚本执行时间较长（比如跑完整的测试套件），会显著拖慢Claude Code的工作效率。
• 先在小范围测试：配置新的Hook后，先用一个简单任务测试一下效果，确认没有问题再投入正式使用。

Claude Code不仅能修改代码，还能完成完整的Git工作流：

在Claude Code中，你可以用自然语言完成各种Git操作：

"提交当前修改，写一个描述性的commit message"

"创建一个新分支feature/user-auth，然后在这个分支上实现用户认证功能"

"审查PR #123，逐文件指出潜在问题"

"帮我解决当前的合并冲突，保留双方的功能"

"看看最近5次提交都改了什么，给我一个总结"

其中，自动生成commit message是一个特别实用的功能。Claude Code会分析所有改动的文件和内容，生成格式规范、语义准确的提交信息，比手写的 "fix bug" 或 "update code" 要有用得多。

Claude Code内置了对 gh（GitHub CLI）的支持。这意味着你可以通过Claude Code直接与GitHub交互：

"用gh创建一个PR，标题为'Add user authentication'，描述中列出主要改动"

"查看最近的Issue列表，筛选出标记为bug的"

"把PR #56的状态改为ready for review"

"查看CI/CD流水线的运行状态"

gh CLI结合Claude Code的自然语言理解能力，让GitHub操作变得非常流畅——你不需要记住 gh 的各种参数和子命令，用自然语言描述就行。

用Claude Code做代码审查是一个高价值的使用场景。典型流程如下：

第一步：你告诉Claude Code要审查的PR
  "审查PR #42"
      ↓
第二步：Claude Code获取PR的所有改动
  分析新增文件、修改文件、删除文件
      ↓
第三步：逐文件审查
  检查代码逻辑、命名规范、安全隐患、性能问题
      ↓
第四步：生成审查意见
  按严重程度分类：必须修改 / 建议修改 / 讨论点
      ↓
第五步：建议修改方案
  对于发现的问题，给出具体的修改建议

Claude Code做代码审查的优势在于它能理解整个代码仓库的上下文。人类审查者在看一个PR时，可能不了解被修改的代码与其他模块的关系；Claude Code则可以检查改动是否与项目中其他部分存在不一致或冲突。

关于Git操作，有一条重要的安全原则需要牢记：

Claude Code不会自动push到远程仓库。 所有的Git操作（commit、创建分支等）都只影响你的本地仓库。如果你需要push到远程仓库或创建PR，必须明确要求Claude Code这样做。这个设计是故意的——它给你留了一个审核窗口，在代码推送到远程之前做最后的检查。

Skills是可复用的工作流，存放在 .claude/commands/ 目录中。 你可以把经常执行的任务封装成一个Skill，之后通过斜杠命令快速调用。

例如，创建一个代码审查的自定义命令：

.claude/commands/review-pr.md

文件内容：

审查当前分支相对于main分支的所有改动：

1. 列出所有被修改的文件
2. 逐文件分析改动，重点关注：
   - 代码逻辑是否正确
   - 是否有安全隐患
   - 是否遵循项目代码规范
   - 是否有性能问题
3. 按严重程度分类列出所有发现
4. 对每个问题给出具体修改建议

保存后，你就可以在Claude Code中通过 /review-pr 命令一键启动这个工作流。团队成员把 .claude/commands/ 目录提交到Git仓库，所有人就共享了同样的Skills，确保一致的工作标准。

其他常见的自定义命令场景：

• /deploy-staging：部署到测试环境的标准流程
• /add-api：添加新API接口的标准步骤（创建路由、控制器、测试）
• /fix-lint：修复所有lint错误的标准流程

多文件重构是Claude Code最擅长的场景之一，但也需要讲究策略：

第一步：让Claude Code理解整体架构

> 分析这个项目的整体架构，画出模块之间的依赖关系

先建立全局理解，再着手修改。

第二步：用Plan Mode制定重构计划

> 请先制定计划。我要把所有API调用从直接使用fetch改为使用统一的request封装

让AI列出所有需要修改的文件和具体改动。

第三步：分步执行，每步验证

不要让AI一次性修改所有文件。按照计划分步执行，每一步执行完都运行测试确认没有引入问题。

第四步：保持测试通过

每次修改后都确保现有测试通过。如果测试失败了，先修复再继续下一步。测试就是你的安全网。

Claude Code使用API按量计费，以下策略可以有效控制成本：

其中"精准描述"是最容易被忽视的策略。对比以下两种描述：

# 模糊描述（可能需要多次来回确认）
> 帮我优化一下这个页面

# 精准描述（一次就能理解意图）
> 帮我优化商品列表页面的加载速度：
  1. 给图片添加懒加载
  2. 把商品列表改为虚拟滚动
  3. API请求添加缓存，缓存时间5分钟

精准描述虽然你多打了几行字，但AI能一次理解你的意图，不需要反复追问"优化哪方面？""优化到什么程度？"总体来看，反而省了token。

1. 使用管道输入

你可以把其他命令的输出通过管道传给Claude Code：

# 把错误日志传给Claude分析
cat error.log | claude -p "分析这个错误日志，找出根本原因"

# 把一段代码传给Claude审查
cat src/utils/auth.ts | claude -p "审查这段代码的安全性"

-p 参数表示"单次对话模式"——Claude Code处理完输入后直接输出结果并退出，不进入交互模式。这在自动化脚本中特别有用。

2. 在CI/CD中集成Claude Code

Claude Code可以集成到持续集成流程中，实现自动化的代码审查或文档生成：

# 在CI中自动审查PR改动
git diff main...HEAD | claude -p "审查这些改动，列出潜在问题"

3. 多会话管理

用 /resume 命令可以在不同任务之间切换，恢复之前的会话上下文：

> /resume
# 显示最近的会话列表，选择要恢复的会话

这在你同时处理多个任务时非常有用——不需要从头向AI解释上下文。

4. @引用文件

在对话中使用 @ 符号引用特定文件，让AI聚焦于这些文件：

> 看看 @src/utils/request.ts 和 @src/api/user.ts 这两个文件，
  帮我把错误处理逻辑统一一下

5. 子Agent并行工作

对于相互独立的子任务，Claude Code可以启动多个子Agent并行处理，显著加快完成速度。这在大型项目中尤其有用——比如同时给多个模块添加类型注解，每个模块由一个子Agent独立处理。

6. 远程控制

Claude Code支持从手机或浏览器继续工作。你在办公室用终端启动了一个长时间运行的任务，可以在手机上查看进展和结果。这对于需要长时间运行的任务（如大规模重构）特别方便。

从这张表可以看出，两者的差异不是"谁好谁差"，而是设计理念和适用场景的不同。Cursor追求的是"在可视化界面中高效编辑"，Claude Code追求的是"自主规划和执行复杂任务"。

根据不同的使用场景，以下是具体的选择建议：

最重要的认知是：Claude Code和Cursor不是二选一的关系，而是互补的关系。

在同一个项目中，你完全可以这样配合使用：

• 用 Cursor 做日常的单文件编辑、UI调整、快速修Bug——需要频繁看代码、来回调整的工作
• 用 Claude Code 做跨文件重构、功能模块开发、代码审查、自动化流程——需要AI自主规划和执行的工作

这就像开车和坐地铁不是二选一——短途灵活出行开车方便，长途固定路线坐地铁高效。选择工具的核心标准不是"哪个更先进"，而是"哪个更适合当前的任务"。

选择你手头的一个实际项目（如果没有，可以用一个开源项目），编写一份完整的CLAUDE.md，要求包含以下内容：

1. 项目说明和技术栈
2. 构建与运行命令（安装依赖、启动开发、运行测试、构建生产版本）
3. 代码规范（至少5条具体可验证的规则）
4. 文件结构约定
5. 禁区（至少列出2个不应修改的文件或目录）
6. 提交规范

完成后，启动Claude Code验证它是否正确读取了你的CLAUDE.md，尝试让它做一个小修改，观察它是否遵守了你设定的规范。

选择一个涉及多文件修改的任务（例如"给所有API接口添加错误处理"或"把项目中的var全部改为const/let"），按以下步骤操作：

1. 明确要求Claude Code先制定计划
2. 审查计划，提出至少一个修改建议
3. 批准修改后的计划
4. 观察Claude Code按计划执行的过程
5. 对比Plan Mode和直接让AI执行的体验差异

选择一个MCP Server进行安装和测试：

1. 用 claude mcp add 命令安装一个MCP Server（推荐从GitHub MCP开始）
2. 用 /mcp 命令确认连接状态
3. 尝试用自然语言让Claude Code通过MCP执行一个操作
4. 记录安装过程中遇到的问题和解决方法

在什么情况下你会选择Cursor而不是Claude Code？反过来呢？

提示：从以下维度思考——

• 任务的复杂度和涉及的文件数量
• 你对修改结果的可预测性需求
• 项目的协作方式（个人项目还是团队项目）
• 你的命令行熟练程度
• 预算和成本可预测性