Claude Code in Action 学习笔记 01

这是 Anthropic 官方免费课程 Claude Code in Action 的学习笔记，记录将 Claude Code 集成到日常开发工作流的核心知识点。

什么是Coding Assistant

Coding Assistant不仅仅是一个编写代码的工具，它是一个使用语言模型来处理复杂编程任务的复杂系统。

Coding Assistant的工作流程

当你给Coding Assistant一个任务（比如根据错误信息修复 bug）时，它会遵循类似人类开发者的思考过程：

1. 收集上下文 - 理解错误指向什么、代码库的哪个部分受影响、哪些文件相关
2. 制定计划 - 决定如何解决问题，比如修改代码并运行测试来验证修复
3. 执行操作 - 实际实施解决方案，更新文件并运行命令

Tool Use 机制

语言模型的局限性

语言模型本身只能处理文本并返回文本——它们实际上无法读取文件或运行命令。如果你直接问一个独立的语言模型读取文件，它会告诉你它没有这个能力。

那么 Coding Assistant 是如何解决这个问题的？答案是一个巧妙的系统——Tool Use。

Tool Use 的工作原理

当你向Coding Assistant发送请求时，它会自动在你的消息中添加指令，教语言模型如何请求操作。

完整流程示例：

1. 你问："main.go 文件里写了什么代码？"
2. Coding Assistant在请求中添加Tool Use指令
3. 语言模型响应："ReadFile: main.go"
4. Coding Assistant读取实际文件，将内容发送回模型
5. 语言模型根据文件内容提供最终答案

这个系统让语言模型能够有效地"读取文件"、“编写代码"和"运行命令”，尽管它们实际上只是生成格式化的文本响应。

Claude 的 Tool Use 优势

并非所有语言模型在使用工具方面都同样出色。Claude 系列模型（Opus、Sonnet 和 Haiku）在理解工具功能和有效使用工具完成复杂任务方面特别强大。

强大 Tool Use 能力带来的好处

内置工具系统

Claude Code 配备了一套全面的内置工具，用于处理常见的开发任务：

• 文件读取 - 读取项目中的任意文件
• 代码编写 - 创建和修改代码文件
• 命令执行 - 运行 shell 命令
• 目录管理 - 管理项目目录结构

Claude Code 真正强大之处在于它能够智能地组合这些工具来解决复杂的多步骤问题，而不仅仅是单独使用某个工具。

Context 管理

在使用 Claude Code 进行编码项目时，上下文管理至关重要。你的项目可能有几十甚至几百个文件，但 Claude 只需要正确的信息就能有效地帮助你。

/init 命令

当你第一次在新项目中启动 Claude 时，运行 /init 命令。这会让 Claude 分析你的整个代码库并理解：

• 项目的目的和架构
• 重要的命令和关键文件
• 编码模式和结构

分析完成后，Claude 会创建一个摘要并写入 CLAUDE.md 文件。

CLAUDE.md 文件

CLAUDE.md 文件有两个主要用途：

1. 引导 Claude 浏览你的代码库，指出重要的命令、架构和编码风格
2. 允许你给 Claude 特定或自定义的指令

这个文件会包含在你向 Claude 发出的每个请求中，就像为你的项目设置了一个持久的系统提示词。

CLAUDE.md 文件位置

Claude 识别三个不同位置的 CLAUDE.md 文件：

添加自定义指令

直接告诉 Claude 编辑你的 CLAUDE.md 文件即可。例如：

请在 CLAUDE.md 中添加：Use comments sparingly. Only comment complex code.

或者更具体地指定文件：

Edit my CLAUDE.md to add: Always use TypeScript strict mode

Add to CLAUDE.local.md: Prefer functional programming style

Claude 会自动将指令合并到对应的 CLAUDE.md 文件中。

使用 @ 引用文件

当你需要 Claude 查看特定文件时，使用 @ 符号后跟文件路径。这会自动将该文件的内容包含在你的请求中。

How does the auth system work? @auth

Claude 会显示一个与 auth 相关的文件列表供你选择，然后将选定的文件包含在对话中。

在 CLAUDE.md 中引用文件

你也可以使用相同的 @ 语法在 CLAUDE.md 文件中直接引用文件。这对于与项目许多方面相关的文件特别有用。

The database schema is defined in the @prisma/schema.prisma file.
Reference it anytime you need to understand the structure of data stored in the database.

当你以这种方式引用文件时，其内容会自动包含在每个请求中，因此 Claude 可以立即回答关于数据结构的问题，而无需每次都搜索和读取 schema 文件。

截图沟通

与 Claude 沟通最有效的方式之一是通过截图。当你想修改界面的特定部分时，截图可以帮助 Claude 准确理解你所指的内容。

使用 Ctrl+V（macOS 上不是 Cmd+V）将截图粘贴到 Claude 中。这个快捷键专门用于将截图粘贴到聊天界面。粘贴图片后，你可以要求 Claude 对应用程序的该区域进行特定更改。

Planning Mode

对于需要在代码库中进行大量研究的复杂任务，可以启用 Planning Mode。此功能让 Claude 在实施更改之前对项目进行彻底探索。

启用方式

按 Shift + Tab 两次启用 Planning Mode（如果你已经处于自动接受编辑状态accept edits on，则只需按一次）。

Planning Mode 下 Claude 会做什么

• 读取项目中更多的文件
• 创建详细的实施计划
• 向你展示它打算做什么
• 等待你的批准后再继续

这让你有机会审查计划，如果 Claude 遗漏了重要内容或没有考虑到某个特定场景，可以及时纠正。

Thinking Mode

Thinking Mode 让 Claude 在提供解决方案之前花更多时间进行内部推理，适合处理复杂问题。

启用 Thinking Mode 的三种方式

1. 全局开启（持久化）

使用 /config 命令全局开启 thinking mode：

/config

此设置会保存到 ~/.claude/settings.json 中的 alwaysThinkingEnabled 字段。

2. 环境变量（自定义 token 预算）

设置 MAX_THINKING_TOKENS 环境变量来指定自定义的 token 预算：

export MAX_THINKING_TOKENS=10000

3. 单次请求使用 ultrathink

在消息中包含 ultrathink 关键词，仅对当前请求启用 thinking mode：

ultrathink: design a caching layer for our API

查看思考过程

按 Ctrl+O 切换详细模式，可以看到 Claude 的内部推理过程（显示为灰色斜体文本）。

Token 预算说明

模型默认设置

使用 /model 命令查看当前使用的模型。

Planning vs Thinking 的使用场景

这两个功能处理不同类型的复杂性：

Planning Mode 适用于

• 需要广泛理解代码库的任务
• 多步骤实施
• 影响多个文件或组件的更改

Thinking Mode 适用于

• 复杂的逻辑问题
• 调试困难的问题
• 算法挑战

对话控制技巧

在处理复杂任务时，你需要引导对话保持专注和高效。以下是控制对话流程的几种技巧。

使用 Escape 中断 Claude

有时 Claude 会朝错误的方向发展，或试图一次处理太多事情。按 Escape 键可以中途停止 Claude 的响应，让你重新引导对话。

适用场景：

• Claude 开始制定一个涵盖所有内容的综合计划，但你只想让它专注于一个特定任务
• Claude 的方向与你的预期不符

结合 Escape 与记忆功能

当 Claude 在不同对话中反复犯同样的错误时，可以：

1. 按 Escape 停止当前响应
2. 告诉 Claude 编辑 CLAUDE.md 添加正确的做法
3. 继续对话

这可以防止 Claude 在项目的未来对话中犯同样的错误。

回退对话（Rewind）

在长对话中，可能会积累一些不相关或分散注意力的上下文。例如，Claude 遇到错误并花时间调试，这些来回讨论对下一个任务可能没有用处。

操作方式： 按 Escape 两次

这会显示你发送过的所有消息，让你可以跳回到较早的点继续。

好处：

• 保留有价值的上下文（如 Claude 对代码库的理解）
• 移除分散注意力或不相关的对话历史
• 让 Claude 专注于当前任务

上下文管理命令

/compact

/compact 命令会总结整个对话历史，同时保留 Claude 学到的关键信息。

适用场景：

• Claude 已经获得了关于项目的宝贵知识
• 你想继续处理相关任务
• 对话变得很长但包含重要上下文

当 Claude 对当前任务了解很多，而你想在进入下一个相关任务时保持这些知识时，使用 /compact。

/clear

/clear 命令会完全移除对话历史，给你一个全新的开始。

适用场景：

• 你要切换到完全不同、不相关的任务
• 当前对话上下文可能会让 Claude 对新任务感到困惑
• 你想在没有任何先前上下文的情况下重新开始

何时使用这些技巧

Custom Commands

Claude Code 内置了一些可以通过斜杠访问的命令，但你也可以创建自定义命令来自动化经常运行的重复性任务。

创建自定义命令

要创建自定义命令，需要在项目中设置特定的文件夹结构：

1. 找到项目目录中的 .claude 文件夹
2. 在其中创建一个名为 commands 的新目录
3. 创建一个以你想要的命令名称命名的 markdown 文件（如 audit.md）

文件名就是你的命令名称——所以 audit.md 会创建 /audit 命令。

.claude/
└── commands/
    └── audit.md      # 创建 /audit 命令

示例：Audit 命令

以下是一个审计项目依赖漏洞的自定义命令示例：

# audit.md

Run npm audit to find vulnerable installed packages.
Then run npm audit fix to apply updates.
Finally, run tests to verify the updates didn't break anything.

这个 audit 命令会执行三件事：

1. 运行 npm audit 查找有漏洞的已安装包
2. 运行 npm audit fix 应用更新
3. 运行测试验证更新没有破坏任何功能

带参数的命令

自定义命令可以使用 $ARGUMENTS 占位符接受参数，这使它们更加灵活和可复用。

例如，一个 write_tests.md 命令可能包含：

Write comprehensive tests for: $ARGUMENTS

Testing conventions:
* Use Vitests with React Testing Library
* Place test files in a __tests__ directory in the same folder as the source file
* Name test files as [filename].test.ts(x)
* Use @/ prefix for imports

Coverage:
* Test happy paths
* Test edge cases
* Test error states

然后你可以用文件路径运行这个命令：

/write_tests the use-auth.ts file in the hooks directory

参数不必是文件路径——它们可以是任何你想传递给 Claude 的字符串，为任务提供上下文和方向。

Custom Commands 的主要优势

Custom Commands 对于项目特定的工作流特别有用，比如运行测试套件、部署代码，或按照团队约定生成样板代码。

MCP Servers

你可以通过添加 MCP（Model Context Protocol）服务器来扩展 Claude Code 的能力。这些服务器可以在远程或本地机器上运行，为 Claude 提供它原本没有的新工具和能力。

安装 MCP Server

以 Playwright MCP Server 为例，它可以让 Claude 控制 Web 浏览器。在终端中（不是在 Claude Code 内部）运行以下命令：

claude mcp add playwright npx @playwright/mcp@latest

这个命令做了两件事：

1. 将 MCP 服务器命名为 “playwright”
2. 提供在本地机器上启动服务器的命令

管理权限

首次使用 MCP 服务器工具时，Claude 每次都会请求权限。如果你厌倦了这些权限提示，可以通过编辑设置来预先批准服务器。

打开 .claude/settings.local.json 文件，将服务器添加到 allow 数组中：

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  }
}

实际示例：改进组件生成

以下是 Playwright MCP Server 如何改进开发工作流的真实示例。你可以让 Claude：

1. 打开浏览器并导航到你的应用程序
2. 生成一个测试组件
3. 分析视觉样式和代码质量
4. 根据观察结果更新生成提示词
5. 用新组件测试改进后的提示词

例如，你可以要求 Claude：

Navigate to localhost:3000, generate a basic component, review the styling,
and update the generation prompt at @src/lib/prompts/generation.tsx
to produce better components going forward.

Claude 会使用浏览器工具与你的应用交互，检查生成的输出，然后修改你的提示词文件以鼓励更原创和有创意的设计。

关键优势

Claude 可以看到实际的视觉输出，而不仅仅是代码，这使它能够对样式改进做出更明智的决策。

例如，Claude 可能会更新提示词以鼓励：

• 温暖的日落渐变（橙色到粉色到紫色）
• 海洋深度主题（青色到翡翠色到青色）
• 不对称设计和重叠元素
• 创意间距和非传统布局

探索其他 MCP Servers

Playwright 只是 MCP 服务器可能性的一个例子。生态系统包括用于以下用途的服务器：

MCP Servers 可以将 Claude 从代码助手转变为能够与整个工具链交互的综合开发伙伴。

GitHub 集成

Claude Code 提供官方 GitHub 集成，让 Claude 可以在 GitHub Actions 中运行。这个集成提供两个主要工作流：Issue 和 PR 的 mention 支持，以及自动 PR 审查。

设置集成

在 Claude 中运行 /install-github-app 命令，它会引导你完成设置过程：

1. 在 GitHub 上安装 Claude Code 应用
2. 添加你的 API 密钥
3. 自动生成包含工作流文件的 Pull Request

生成的 PR 会向你的仓库添加两个 GitHub Actions。合并后，你会在 .github/workflows 目录中看到工作流文件。

默认 GitHub Actions

集成提供两个主要工作流：

Mention Action

你可以在任何 Issue 或 PR 中使用 @claude 提及 Claude。被提及时，Claude 会：

• 分析请求并创建任务计划
• 以完全访问代码库的权限执行任务
• 直接在 Issue 或 PR 中回复结果

Pull Request Action

每当你创建 PR 时，Claude 会自动：

• 审查提议的更改
• 分析修改的影响
• 在 PR 上发布详细报告

自定义工作流

合并初始 PR 后，你可以自定义工作流文件以适应项目需求。

添加项目设置

在 Claude 运行之前，可以添加步骤来准备环境：

- name: Project Setup
  run: |
    npm run setup
    npm run dev:daemon    

自定义指令

为 Claude 提供项目设置的上下文：

custom_instructions: |
  The project is already set up with all dependencies installed.
  The server is already running at localhost:3000. Logs from it
  are being written to logs.txt. If needed, you can query the
  db with the 'sqlite3' cli. If needed, use the mcp__playwright
  set of tools to launch a browser and interact with the app.  

MCP Server 配置

你可以配置 MCP 服务器为 Claude 提供额外能力：

mcp_config: |
  {
    "mcpServers": {
      "playwright": {
        "command": "npx",
        "args": [
          "@playwright/mcp@latest",
          "--allowed-origins",
          "localhost:3000;cdn.tailwindcss.com;esm.sh"
        ]
      }
    }
  }  

工具权限

在 GitHub Actions 中运行 Claude 时，必须显式列出所有允许的工具。这在使用 MCP 服务器时尤为重要。

allowed_tools: "Bash(npm:*),Bash(sqlite3:*),mcp__playwright__browser_snapshot,mcp__playwright__browser_click,..."

最佳实践

GitHub 集成将 Claude 从开发助手转变为自动化团队成员，可以直接在 GitHub 工作流中处理任务、审查代码并提供见解。

总结

1. Coding Assistant 使用语言模型来完成不同的任务
2. 语言模型需要工具来处理大多数现实世界的编程任务
3. 不同语言模型使用工具的能力水平不同
4. Claude 强大的 Tool Use 能力为 Claude Code 带来了更好的安全性、可定制性和持久性
5. 上下文管理是高效使用 Claude Code 的关键——使用 /init、CLAUDE.md 和 @ 引用来提供精准的上下文
6. 截图是与 Claude 精确沟通的有效方式——使用 Ctrl+V 粘贴截图
7. Planning Mode 适合需要广泛代码库理解的复杂任务——按 Shift + Tab 两次启用
8. Thinking Mode 提供深度推理能力——通过 /config、ultrathink 关键词或 MAX_THINKING_TOKENS 环境变量启用
9. 掌握对话控制技巧保持高效——Escape 中断、双击 Escape 回退、/compact 压缩、/clear 清除
10. Custom Commands 自动化重复工作流——在 .claude/commands/ 中创建 markdown 文件，使用 $ARGUMENTS 接受参数
11. MCP Servers 扩展 Claude 能力边界——通过 claude mcp add 添加服务器，在 settings.local.json 中配置权限
12. GitHub 集成实现自动化协作——使用 /install-github-app 设置，支持 @claude mention 和自动 PR 审查

Tool Use 能力是将简单的文本生成模型转变为强大 Coding Assistant 的关键——它能够读取你的文件、理解你的代码库，并对项目进行有意义的更改。