Claude Code

Claude Code 是由 Anthropic 开发的一个强大 AI 助手，能够阅读你的代码库、编辑文件，并通过终端、IDE、桌面应用和浏览器执行命令。它不仅能帮助你编写代码，还能完成各种开发任务，比如分析项目结构、导航浏览器和运行调试工具。

为了使用 Claude Code，你需要一些基本的编程知识和熟悉命令行操作。如果你还没有安装 Node.js 和 npm，需要先安装它们，因为 Claude Code 是通过 npm 全局安装的。

什么是 Claude Code？

Claude Code 是一个系统级的 AI 代理，不仅仅是一个代码编写工具。它可以理解自然语言指令来完成各种计算机任务。它的主要特点包括：

• 高度可扩展：支持多种扩展方式，如 MCP（Modular Component Platform）、Skills（技能包）、Plugins（插件）和 Hooks（钩子）。
• 多功能性：不仅可以编写代码，还可以打开应用程序、浏览网页、运行开发工具等。

为什么要使用 Claude Code？

Claude Code 提供了一种全新的开发体验，使得开发者可以更加高效地完成工作。通过自然语言指令就能实现复杂的任务自动化，大大节省了时间和精力。

如何安装 Claude Code？

首先确保你已经安装了 Node.js 和 npm。然后你可以通过以下命令全局安装 Claude Code：

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

安装完成后，你可以通过以下命令启动 Claude Code：

claude

常见问题与排查

如果你在安装过程中遇到问题，可以检查是否正确安装了 Node.js 和 npm。如果仍然有问题，请查看官方文档或联系 Anthropic 支持团队获取帮助。

示例：分析 Excalidraw 项目

假设我们要分析 Excalidraw 项目的代码结构。我们可以使用 Claude Code 来快速获得项目的概述：

claude analyze "Excalidraw codebase structure and provide a high-level overview of what it is, its main components, and how they're organized."

预期结果会是一个关于 Excalidraw 项目结构的详细描述。

实用技巧

• 使用 claude help 可以查看所有可用命令及其用法。
• 在配置文件 .claude/config.json 中可以自定义设置，如默认使用的模型和 API 地址。

本章小结

• 理解了 Claude Code 的功能和优势。
• 学习了如何安装和启动 Claude Code。
• 掌握了一些常用的命令和实用技巧。
• 了解了如何利用 Claude Code 分析项目结构。

安装与配置 Claude Code 是使用该工具的第一步。完成这一步之后，你可以顺利地开始探索 Claude Code 提供的各种功能。

前置知识/环境

在开始安装之前，你需要确保你的电脑上已经安装了 Node.js 和 npm。因为 Claude Code 是通过 npm 安装的全局包。

安装方法

方法一：通过 npm 安装

打开终端或命令行工具，输入以下命令来全局安装 Claude Code：

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

安装完成后，可以通过以下命令验证是否安装成功：

claude --version

预期结果应该会显示当前安装的 Claude Code 版本号，比如 1.0.0。

方法二：通过 PowerShell 安装（适用于 Windows 用户）

如果你使用的是 Windows 系统并且希望使用 PowerShell 进行安装，可以按照以下步骤操作：

1. 打开 PowerShell 并输入以下命令来下载并执行安装脚本：

   irm https://claude.ai/install.ps1 | iex

2. 验证安装是否成功：

   claude --version

同样，你应该能看到类似 1.0.0 的版本号作为成功的标志。

解决地域限制

有时候由于地域限制，可能会影响某些功能的正常使用。为了解决这个问题，可以在用户主目录下的 .claude.json 文件中进行相应的配置。具体步骤如下：

1. 找到位于 C:\Users\[用户名] 目录下的 .claude.json 文件。

2. 使用文本编辑器打开该文件。

3. 在最后一个 } 之前添加一行配置信息。例如：

   "api_url": "https://your-custom-api-url"

切换模型

Claude Code 默认使用 Anthropic 公司提供的模型，但是你可以通过 cc-switch 工具来切换到其他的模型。以下是具体的操作步骤：

1. 下载并安装 cc-switch 应用程序。可以从 CC-Switch Releases 页面 下载适合你系统的版本。
2. 启动 cc-switch 应用程序。
3. 在应用程序中添加新的模型供应商，并创建对应的 API Key。
4. 配置你要使用的模型版本和其他相关参数。

模型版本	速度	成本	智力水平	最佳应用场景
Haiku	极快 ⚡️	最低 💰	入门级	客服、翻译、大量简单数据清洗
Sonnet	快 🚀	中等 💰💰	高级 (主流)	编程、日常办公、视觉分析 (性价比之王)
Opus	较慢 🐢	最高 💰💰💰	顶级 🧠	创意写作、复杂策略、深度长文本分析
Opus Thinking	最慢 ⏳	极高 💎	超越极限	数学证明、算法竞赛、硬核逻辑推理

初始化项目

当你在一个新项目中使用 Claude Code 时，首先需要初始化该项目以便让 Claude Code 对项目有一个整体的理解。在项目根目录下打开终端并输入以下命令：

claude /init

这条命令会让 Claude Code 阅读整个项目的代码，并将生成的知识保存到项目根目录下的 CLAUDE.md 文件中。后续的操作都会基于这份文件来进行。

常见报错与排查

• 错误：无法找到命令 'claude'

  如果你在终端中输入 claude --version 或其他命令时报错说找不到该命令，请确认你已经正确安装了 Node.js 和 npm，并且已将 npm 的 global bin 目录添加到了系统的 PATH 环境变量中。

• 错误：网络连接失败

  如果你在尝试访问外部 API 或更新配置时遇到网络连接问题，请检查你的网络设置或者考虑更换网络环境后再试一次。

实用技巧

• 使用 /compact 命令可以压缩之前的对话记录，从而减少 TOKEN 的消耗。
• 使用 /clear 命令可以清除之前的对话记录。
• 使用 /config 命令可以查看和修改全局配置列表。

示例：初始化一个新的 Python 项目

假设我们要对一个名为 my-python-project 的 Python 项目进行初始化分析。首先我们需要进入项目的根目录并运行以下命令：

cd path/to/my-python-project/
claude /init

然后等待一段时间直到 Claude Code 处理完毕后，在项目的根目录下会出现一个 CLAUDE.md 文件，里面包含了对项目的概述以及一些重要的知识点。

本章小结

• 学习了两种不同的安装方法（npm 和 PowerShell）。
• 掌握了解决地域限制的方法以及如何修改 .claude.json 文件中的配置信息。
• 知道了如何通过 cc-switch 工具切换不同的 AI 模型。
• 学会了如何初始化一个新的项目，并理解了 CLAUDE.md 文件的作用。
• 认识了一些常用的基本命令及其用途。

在本章中，我们将深入探索 Claude Code 的基本功能，通过具体的命令和操作让你能够熟练地使用这款强大的 AI 编程助手。读完本章后，你将掌握如何启动 Claude Code、管理对话记录、生成和更新文档、以及如何请求代码审查等功能。

前置知识/环境

确保你已经在你的系统上成功安装了 Claude Code。如果还没有安装，可以通过以下命令进行全局安装：

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

并且你需要有一个项目目录来练习这些基本功能。

基础启动命令

启动方式

你可以通过以下几种方式启动 Claude Code：

1. 带初始问题启动

   如果你想在启动时就提出一个问题，可以直接在命令后面加上你的问题：

   claude "帮我优化这段代码"

2. 一次性执行并退出

   使用 -c 参数可以在执行完指定命令后立即退出 Claude Code 会话：

   claude -c "生成 README.md 文件"

常用启动参数

• -c：用于一次性执行命令并退出。
• --dangerously-skip-permissions：给予全部权限（风险较大），通常不推荐使用。

核心 Slash 命令

基础管理

1. 继续当前目录的上一次聊天

   使用 /continue 可以恢复之前中断的会话。

2. 清除终端屏幕，但保留对话历史

   使用 /clear 可以清屏，方便整理思路。

3. 为项目生成或更新文档 CLAUDE.md

   使用 /doc 命令可以自动生成或更新项目的文档文件 CLAUDE.md。

4. 开启 plan 模式

   使用 /plan 只赋予 Read 权限，适合快速了解代码库而不想轻易更改代码。

5. 开启思考模式

   使用 /think 可以让 Claude 更加详细地分析和解释代码。

6. 选择模型

   使用 /model <model_name> 可以切换不同的 AI 模型。

7. 查看上下文占用情况

   使用 /context 可以查看当前会话使用的上下文大小。

8. 引用文件

   使用 /file <filename> 可以引用特定文件进行处理。

9. 请求代码审查

   使用 /review 可以请求对当前文件或项目的代码审查。

10. 取消当前输入或生成

    使用 /cancel 可以停止正在进行的操作。

11. 管道输入

    你可以将其他命令的结果通过管道传递给 Claude Code 进行处理：

    cat file.py | claude -p "优化这段代码"

12. 编辑 CLAUDE.md

    使用 /edit-docs 可以打开 CLAUDE.md 文件进行手动编辑。

会话优化

1. 开启任务结束响铃通知

   使用 claude config set --global preferredNotifChannel terminal_bell 设置任务结束后发出响铃通知，提醒用户关注结果。

2. 退出 Claude Code 会话

   输入 exit 或者按 Ctrl+D 可以退出当前的 Claude Code 会话。

3. 在控制台查看每日 API 费用

   使用 ccusage daily 查看每日的 API 费用详情，包括 token 使用量及费用统计。

4. 实时监控 API 费用使用情况

   输入 ccusage real-time 可以实时监控 API 的使用情况和费用变化。

5. 筛选与选项

   例如查看某个日期范围内的 API 费用使用情况：

   ccusage daily --since 20250525 --until 20250530

6. 输出格式调整为 JSON 格式

   如果需要导出数据以便进一步处理，可以添加 --json 参数：

   ccusage daily --json

7. 在 CC 中跑 Bash 命令

   直接在 Claude Code 中运行 Bash 命令也很简单：

   !ls -la

8. 内存快捷键 - 添加到 CLAUDE.md 中的规则

   在某些情况下可能需要直接向 CLAUDE.md 添加特定规则或内容，可以使用相应的快捷键实现这一点。具体方法请参考官方文档中的详细说明部分。

实用技巧

CLAUDE.md 文件

在项目根目录创建 CLAUDE.md 文件后，Claude 会自动读取该文件的内容，并根据其中的信息提供更加个性化的支持和服务。因此合理组织和维护这个文件对于提高工作效率非常重要。

示例：实际操作演示

假设我们有一个名为 example-project 的 Python 项目，并希望利用 Claude Code 对其进行全面分析和改进。以下是具体步骤：

1. 导航到项目根目录:

   cd path/to/example-project/

2. 初始化项目并生成初步文档:

   claude /init

3. 查看生成的 CLAUDE.md 文件:

   打开 CLAUDE.md, 审核并补充必要的信息。

4. 请求全面代码审查:

   claude /review all-files=true include-tests=false exclude-vendor=true max-changes=50 summary-only=false detail-level=detailed feedback-format=text output-file=review-report.txt 

5. 根据反馈进行修改，并再次运行审查确认是否达到预期效果。

6. 更新 CLAUDE.md 文档:

   完成相关修改后, 利用 /edit-docs 修改和完善文档内容, 确保其准确性和完整性.

7. 检查 API 费用使用情况:

   随着项目的推进, 定期检查 API 的费用消耗是非常必要的:

   ccusage daily --since $(date +%Y-%m-01) --until $(date +%Y-%m-%d)

8. 当所有工作完成后, 正确关闭会话:

   exit 

易错提示与排查技巧

• 如果你在初始化项目时遇到权限问题，请确保你有足够的权限访问该项目的所有文件。

• 在执行复杂的任务时可能会遇到超时的情况, 这通常是由于网络延迟或资源不足导致的。此时可以尝试分批处理或者稍后再试。

• 如果发现生成的文档不符合预期, 尝试重新初始化或者手动编辑 CLAUDE.md 文件来修正错误信息.

• 若遇到任何未识别的错误信息, 首先查阅官方文档寻找解决方案; 如仍未解决则考虑联系技术支持获取帮助.

本章小结

• 掌握了多种启动方式及常用参数设置方法;
• 熟悉了多个基础管理和优化 slash 命令的应用场景;
• 学习到了如何利用 CLAUDE.md 文件提升项目的可维护性;
• 实践了一个完整的项目初始化、审查过程，并掌握了相关的注意事项和排查技巧;

生成代码片段是Claude Code的核心功能之一，通过这一功能，你可以根据自然语言描述快速生成所需的代码片段，提高编码效率。完成本章的学习后，你将能够熟练地使用Claude Code来生成各种代码片段。

前置知识/环境

假设你已经完成了前几章中的安装与配置，并且熟悉了基本的操作界面和命令。如果没有，请先阅读相关章节进行准备。

概念讲透 + 分步操作

什么是代码片段生成？

代码片段生成是指根据你的文本描述，Claude Code自动生成相应的代码部分。这个过程通常非常快，并且准确性很高。

如何使用代码片段生成功能？

1. 打开 Claude Code 终端 我们先打开之前配置好的Claude Code终端。

2. 输入自然语言描述 接着，在终端中输入你需要的代码片段的自然语言描述。例如，如果你想生成一个Python函数来计算两个数的和，你可以这样写：

   Generate a Python function to calculate the sum of two numbers.

3. 查看生成的代码 输入上述命令后，Claude Code会立即返回生成的代码。预期的结果如下：

   def add_numbers(a, b):
       return a + b

4. 进一步修改和完善 如果生成的代码需要一些调整，可以直接在返回的代码基础上进行修改。

易错处提示常见报错与排查、实用技巧

• 常见的报错信息：如果输入的语言描述不够清晰，Claude Code可能无法准确理解你的意图，从而产生不符合预期的代码。这时可以尝试重新描述你的需求。

• 实用技巧：为了提高生成代码的质量和速度，尽量使用明确具体的语言描述。例如，“Generate a Python function to calculate the sum of two numbers”比“Give me some code for adding two numbers”更有效。

实际场景举例

假设你现在正在开发一个简单的计算器应用，并且需要一个函数来实现乘法运算。我们可以按照以下步骤操作：

1. 打开 Claude Code 终端。

2. 输入以下指令：

   Create a JavaScript function that multiplies two numbers and returns the result.

3. 查看返回结果：

   function multiplyNumbers(a, b) {
       return a * b;
   }

4. 将这段代码复制到你的JavaScript文件中即可。

本章小结

• 学会了如何通过自然语言描述来生成特定的代码片段。
• 理解了提高生成代码质量的关键在于清晰明确的需求描述。
• 掌握了一些常见的报错排查技巧以及实用的操作建议。
• 通过实际的例子加深了对代码片段生成功能的理解和应用。

编写函数文档是软件开发中的一个重要环节，它不仅帮助其他开发者理解代码的功能，还能提升代码的可维护性和协作效率。通过本章的学习，你将能够熟练地利用 Claude Code 来生成高质量的函数文档。

前置知识/环境

确保你已经完成了前面章节中的安装与配置步骤，并且熟悉如何在 Claude Code 中输入指令和查看结果。

概念讲透 + 分步操作

什么是函数文档？

函数文档是对一个函数的行为、参数、返回值以及可能抛出的异常进行详细描述的一种方式。良好的函数文档可以让用户快速了解如何正确调用该函数，并减少因误解而导致的错误。

如何编写函数文档？

Claude Code 可以根据你的自然语言描述自动生成详细的函数文档。以下是具体步骤：

1. 打开 Claude Code 终端。

2. 输入指令：你需要明确告诉 Claude Code 你希望为哪个函数编写文档。例如，假设我们要为一个计算两个数之和的 Python 函数 add_numbers 编写文档，可以这样输入：

   Write documentation for the following Python function:
   
   def add_numbers(a, b):
       """Return the sum of two numbers."""
       return a + b

3. 查看结果：Claude Code 会分析提供的代码并生成相应的文档。预期的结果如下：

   def add_numbers(a, b):
       """
       Return the sum of two numbers.
   
       Parameters:
           a (int or float): The first number to be added.
           b (int or float): The second number to be added.
   
       Returns:
           int or float: The sum of the two input numbers.
       
       Raises:
           TypeError: If either 'a' or 'b' is not an integer or float.
       """
       if not isinstance(a, (int, float)) or not isinstance(b, (int, float)):
           raise TypeError("Both arguments must be integers or floats.")
       
       return a + b

易错处提示及实用技巧

• 明确需求：在请求生成文档时，请尽可能详细地描述函数的功能、参数类型和返回值类型。
• 检查语法：生成的文档可能会有一些格式上的问题，记得手动检查并修正。
• 异常处理：如果函数中有异常处理逻辑，请务必提及这些情况及其处理方法。

实际场景举例

假设你在开发一个数据处理模块，并且有一个用于过滤掉列表中负数的函数 filter_negative_numbers。你可以按照以下步骤操作：

1. 打开 Claude Code 终端。

2. 输入以下指令：

   Write comprehensive documentation for this Python function:
   
   def filter_negative_numbers(numbers):
       """Filter out negative numbers from a list."""
       return [num for num in numbers if num >= 0]

3. 查看返回结果：

   def filter_negative_numbers(numbers):
       """
       Filter out negative numbers from a list.
   
       This function takes a list of numbers and returns a new list containing only the non-negative numbers (i.e., zero and positive numbers).
   
       Parameters:
           numbers (list of int or float): The list of numbers to be filtered.
   
       Returns:
           list of int or float: A new list containing only the non-negative numbers from the original list.
       
       Raises:
           ValueError: If the input is not a list.
           TypeError: If any element in the list is not an integer or float.
           
       Examples:
           >>> filter_negative_numbers([1, -2, 3, -4])
           [1, 3]
   
           >>> filter_negative_numbers([-1, -2, -3])
           []
   
           >>> filter_negative_numbers([])
           []
           
           >>> filter_negative_numbers([0, 5.5, -3.2])
           [0, 5.5]
           
           >>> filter_negative_numbers("not a list")
           Traceback (most recent call last):
               ...
           ValueError: Input must be a list
           
           >>> filter_negative_numbers([1, 'two', 3])
           Traceback (most recent call last):
               ...
           TypeError: All elements in the list must be integers or floats
       """
       
       if not isinstance(numbers, list):
           raise ValueError("Input must be a list")
   
       for num in numbers:
           if not isinstance(num, (int, float)):
               raise TypeError("All elements in the list must be integers or floats")
   
       return [num for num in numbers if num >= 0]

4. 将这段代码复制到你的Python文件中即可。

本章小结

• 学会了如何利用 Claude Code 自动生成详细的函数文档。
• 理解了编写高质量函数文档的重要性以及注意事项。
• 掌握了一些常见的错误排查技巧以及实用的操作建议。
• 通过实际的例子加深了对生成函数文档功能的理解和应用。

遇到问题时，能够迅速定位并解决是非常重要的技能。本章将详细介绍 Claude Code 使用过程中常见的错误及其解决方法，帮助你在遇到问题时不再迷茫，顺利推进工作。

前置知识

确保你已经完成了 Claude Code 的安装与配置，并且熟悉基本的功能操作。如果没有，请先阅读前面的相关章节。

常见错误及解决方法

1. overloaded_error（服务器超载）

原因：当服务器负载过高时，会出现此错误。 解决方法：

• 切换模型：尝试从 Claude Opus 切换回 Sonnet 模型。
• 等待重试：等待一段时间后再尝试使用 Claude Code。

2. request timeout（请求超时）

原因：网络延迟或服务器响应缓慢可能导致请求超时。 解决方法：

• 检查网络连接：确保你的网络连接稳定。
• 增加超时设置：可以在代码中调整超时设置，例如 timeout=60 秒。

import requests

response = requests.get('https://api.claudecode.com/data', timeout=60)

• 重试机制：实现简单的重试机制来处理临时性的网络问题。

import time

def get_data_with_retry(url, retries=3, delay=5):
    for _ in range(retries):
        try:
            response = requests.get(url, timeout=60)
            response.raise_for_status()
            return response.json()
        except requests.RequestException as e:
            print(f"Request failed: {e}. Retrying...")
            time.sleep(delay)
    raise Exception("Failed after several retries")

3. invalid_request_error（无效请求错误）

原因：通常是由于内部逻辑 bug 或请求参数不正确引起的。 解决方法：

• 回退消息：按下 Esc + Esc 回退到上一条消息进行重试。
• 强制退出并重启：按下 Ctrl + C 强制退出当前进程，然后关闭窗口并重新启动 Claude Code。

4. tool_call_error（工具调用错误）

原因：可能是由于内部代码逻辑异常或工具调用失败造成的。 解决方法：

• 重试命令：尝试再次运行之前失败的命令。
• 强制退出并重启窗口：如果多次重试仍然失败，可以使用 Ctrl + C 强制退出当前进程，并打开新的窗口重新运行 Claude Code。

避免上下文和历史对话丢失

为了避免在强制退出或其他异常情况下丢失消息记录和历史对话，建议采取以下措施：

1. 创建 todo.md 文件

   • 在每次使用 Claude Code 执行任务前，将其需求整理并写入 todo.md 文件中。
   • 每次任务分解后及时更新 todo.md 文件内容，在执行任务时严格按照该文件中的指示进行操作。

2. 保存会话记录

   • 使用长期记忆插件如 Claude-Mem 或 Agent Harness 来保存跨会话的上下文信息。

实际案例

假设你在使用 Claude Code 处理数据清洗任务时遇到了 invalid_request_error 错误。以下是具体的排查步骤：

1. 查看详细错误信息

   API Error: 400 {"type":"error","error":{"type":"invalid_request_error", "message": "Invalid parameter 'data_format'"}}}

2. 检查请求参数 确认传递给 API 的所有参数是否正确无误。例如：

   data_format = 'csv'  # 确保这是一个有效的格式选项

3. 按照错误提示修正参数 修改有问题的参数值，并重新发送请求：

   import requests
   
   url = 'https://api.claudecode.com/clean'
   params = {'data_format': 'json'}  # 修改为正确的格式
   response = requests.post(url, json=params)

4. 观察结果 如果修改后仍出现问题，则考虑其他可能的原因，并根据上述建议进行进一步排查。

本章小结

• 学习了如何识别和解决 Claude Code 中常见的四个错误类型及其对应的解决方案。
• 掌握了避免上下文和历史对话丢失的方法，特别是通过维护 todo.md 文件和使用长期记忆插件来保护关键信息。
• 理解了在面对各种故障情况下的排查思路和具体操作步骤。

重构代码可以帮助我们提高代码的质量、性能和可维护性。通过本章的学习，你将能够理解什么是代码重构，并掌握一些基本的重构方法和技术。

前置知识

在开始之前，你需要熟悉 Python 编程基础以及对现有代码有一定的了解。如果你已经完成了前面几章的学习，那么你应该已经安装并配置好了 Claude Code 并能运行基本的功能。

什么是代码重构？

代码重构是指在不改变软件外部行为的前提下，对内部结构进行调整和优化的过程。它的目的是使代码更加清晰、易于理解和维护。

为什么要进行代码重构？

1. 提高可读性：重构可以使复杂的代码变得简单易懂。
2. 增强可维护性：良好的结构使得未来的修改变得更加容易。
3. 提升性能：有时候通过重构可以发现潜在的性能瓶颈并加以改进。
4. 减少bug：整洁的代码更容易被测试和调试。

如何进行代码重构？

下面是一些常用的代码重构技术和步骤：

1. 提取函数（Extract Function）

当一段代码做了太多事情时，我们可以将其拆分成多个小函数，每个函数只做一件事。

# 原始代码
def process_order(order):
    total = 0
    for item in order.items:
        total += item.price * item.quantity
    if order.customer.type == 'VIP':
        total *= 0.9
    return total

# 重构后的代码
def process_order(order):
    total = calculate_total(order)
    apply_vip_discount(total, order)
    return total

def calculate_total(order):
    return sum(item.price * item.quantity for item in order)

def apply_vip_discount(total, order):
    if order.customer.type == 'VIP':
        total *= 0.9

2. 合并条件表达式（Consolidate Conditional Expression）

如果有多个条件分支执行相同的操作，可以合并这些条件表达式。

# 原始代码
if customer.status == 'active' and customer.age > 18:
    send_notification(customer)
elif customer.status == 'pending' and customer.age > 18:

编写单元测试可以帮助我们确保代码的正确性和稳定性。通过本章的学习，你将能够为你的代码编写有效的单元测试，并理解如何使用 Claude Code 来简化这个过程。

为了顺利进行，你需要已经安装了 Claude Code CLI 并且有一个基本的 Python 项目环境。

什么是单元测试？

单元测试是对代码的基本组成单位（通常是函数或方法）进行测试的过程。它的目的是验证每个部分是否按预期工作。良好的单元测试可以减少调试时间，提高代码质量。

如何编写单元测试？

首先，我们需要明确要测试的代码的功能、输入和输出。然后，我们可以使用 Python 的 unittest 库来编写具体的测试用例。

步骤一：导入必要的模块

我们通常会使用 unittest 库来进行单元测试。

import unittest

步骤二：创建一个继承自 unittest.TestCase 的类

在这个类中，我们会定义多个以 test_ 开头的方法，每个方法对应一个独立的测试用例。

class TestOrderProcessing(unittest.TestCase):
    pass

步骤三：编写具体的测试方法

假设我们要对之前重构的 process_order 函数进行测试。

from your_module import process_order, OrderItem, Customer

class TestOrderProcessing(unittest.TestCase):

    def setUp(self):
        self.order = [
            OrderItem(price=100, quantity=2),
            OrderItem(price=50, quantity=1)
        ]
        self.customer = Customer(type='VIP')
    
    def test_process_order_with_vip_discount(self):
        total = process_order({
            'items': self.order,
            'customer': self.customer
        })
        self.assertEqual(total, 245)  # 250 * 0.9 = 225

    def test_process_order_without_vip_discount(self):
        self.customer.type = 'regular'
        total = process_order({
            'items': self.order,
            'customer': self.customer
        })
        self.assertEqual(total, 250)

这里我们定义了两个测试方法：

• test_process_order_with_vip_discount: 测试 VIP 用户是否有折扣。
• test_process_order_without_vip_discount: 测试非 VIP 用户没有折扣。

步骤四：运行单元测试

你可以通过命令行来运行这些测试。

python -m unittest discover -s .

这条命令会在当前目录及其子目录下查找所有符合命名规则的文件并运行其中的测试用例。

常见报错与排查技巧

常见的错误包括：

• ImportError: 如果找不到某个模块，请检查是否正确安装并且路径设置正确。
• AssertionError: 如果断言失败，请仔细检查实际值和期望值之间的差异。

实用技巧：

• 使用 setUp() 方法初始化公共对象或状态，避免重复代码。
• 对于复杂的计算或外部依赖，考虑使用 mock 对象来隔离变量因素。

实际案例演示

假设我们在一个电商网站后台处理订单逻辑。我们需要确保当用户是 VIP 时，订单总价会有折扣；而非 VIP 用户则没有折扣。通过上面提到的方法步骤，我们可以轻松地写出对应的单元测试，并验证逻辑是否正确无误。

本章小结

• 学习了如何使用 unittest 库编写单元测试。
• 明白了如何组织和运行单元测试。
• 掌握了一些常见的错误排查技巧和实用建议。

生成 API 文档可以大大减少手动编写文档的工作量，同时确保文档与代码始终保持一致。读完本章后，你将能够使用 Claude Code 自动生成项目的 API 文档。

为了顺利进行，你需要已经完成前面章节的安装与配置，并且对基本功能有所了解。

自动文档生成原理

Claude Code 的自动文档生成功能主要分为两部分：

1. 代码分析：Claude Code 会扫描你的整个代码库，理解项目的结构和代码组织方式。
2. 提取 API 定义：识别出代码中的函数、类、方法等可导出元素及其参数，并自动生成相应的 API 文档。

步骤一：安装必要的插件

如果你还没有安装用于生成 API 文档的相关插件，可以通过 pip 来安装。例如，常用的工具是 Sphinx 和 sphinxcontrib-httpdomain：

pip install sphinx sphinxcontrib-httpdomain

步骤二：初始化 Sphinx 项目

进入你的项目根目录，然后运行以下命令来初始化一个新的 Sphinx 项目：

sphinx-quickstart

按照提示输入相关信息即可。完成后，你会看到一个名为 docs 的目录被创建出来。

步骤三：配置 conf.py 文件

打开 docs/conf.py 文件，在适当的位置添加以下内容以启用 HTTP 域域扩展：

extensions = [
    'sphinx.ext.autodoc',
    'sphinxcontrib.httpdomain'
]

步骤四：编写 reStructuredText 文件

在 docs/source 目录下创建一个新的 .rst 文件（例如 api.rst），并在其中编写一些关于你的 API 的基本信息。例如：

API Reference
=============

.. autofunction:: your_module.your_function_name

这里的 your_module.your_function_name 是你要文档化的函数的具体路径。

步骤五：构建 HTML 文档

回到项目的根目录，然后运行以下命令来构建 HTML 文档：

make -C docs html

执行完毕后，HTML 格式的 API 文档会被生成在 docs/build/html 目录下。你可以通过浏览器打开 index.html 文件查看效果。

常见报错与排查技巧

常见的错误包括：

• ModuleNotFoundError: 如果找不到某个模块，请检查是否正确安装并且路径设置正确。
• SyntaxError: 如果出现语法错误，请仔细检查 reStructuredText 文件中的语法是否正确。

实用技巧：

• 使用注释来描述每个函数的功能和参数类型。
• 尽量保持代码风格的一致性，便于自动化工具准确抓取信息。

实际案例演示

假设我们有一个简单的 Flask 应用来管理用户数据。我们希望为这个应用生成详细的 API 文档。

首先，在项目中安装 Flask 并创建一个简单的应用：

pip install flask

然后创建一个名为 app.py 的文件，并添加以下内容：

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    """获取指定用户的详细信息"""
    user_info = {
        "id": user_id,
        "email": f"user{user_id}@example.com",
        "name": f"User {user_id}",
        "role": "member"
    }
    return jsonify(user_info)

if __name__ == '__main__':
    app.run(debug=True)

接下来，按照上述步骤配置 Sphinx 并在 api.rst 中添加如下内容：

API Reference for User Management App
=====================================

.. autoflask:: app:create_app()
   :undoc-static:
   :endpoints: users.get_user

最后，运行构建命令并查看生成的 HTML 文档。

本章小结

• 学习了如何使用 Claude Code 自动生成 API 文档。
• 掌握了从代码到文档的基本流程。
• 解决了一些常见的报错问题，并掌握了实用技巧。

持续集成（Continuous Integration, CI）是现代软件开发的重要组成部分，它可以帮助我们在代码合并到主分支之前自动发现潜在的问题。Claude Code 提供了强大的持续集成支持，使得我们可以无缝地将 AI 辅助开发集成到现有的 CI 流水线中。通过本章的学习，你将能够配置 Claude Code 与 CI 工具协同工作，确保代码质量和开发效率。

前置知识

• 你需要已经安装并配置好了 Claude Code。
• 熟悉基本的 Git 和 CI/CD 流程。
• 使用的 CI 工具可以是 GitHub Actions、GitLab CI 或 Jenkins 等。

概念讲透

持续集成的核心思想是在代码库频繁更新的情况下，通过自动化的方式定期构建和测试代码。这样可以及时发现问题并修复，减少发布时的风险。Claude Code 可以在这个过程中提供代码质量检查、静态分析等功能，帮助我们提高代码的质量。

分步操作

假设我们要使用 GitHub Actions 来设置持续集成管道，并在其中加入 Claude Code 的代码检查功能。

1. 创建 GitHub Actions Workflow 文件

   在你的仓库根目录下创建 .github/workflows/ci.yml 文件，并添加以下内容：

   name: Continuous Integration with Claude Code
   
   on:
     push:
       branches:
         - main
     pull_request:
       branches:
         - main
   
   jobs:
     build-and-test:
       runs-on: ubuntu-latest
   
       steps:
         - name: Checkout code
           uses: actions/checkout@v2
   
         - name: Set up Python
           uses: actions/setup-python@v2
           with:
             python-version: '3.8'
   
         - name: Install dependencies
           run: |
             pip install -r requirements.txt
   
         - name: Run Claude Code checks
           run: |
             claudie check --config .claudie.yaml .

2. 配置 Claude Code

   创建一个 .claudie.yaml 文件来配置 Claude Code 的行为：

   rules:
     style_guide: google_python_styleguide/google_python_styleguide/rules.py
     max_line_length: 88
     ignore_patterns:
       - tests/

3. 运行 Workflow

   将以上文件推送到你的 GitHub 仓库后，GitHub Actions 将会根据配置自动运行。你可以通过 GitHub 的界面查看每个 Job 的运行情况。

关键点说明

• on.push 和 on.pull_request 定义了触发条件。
• jobs.build-and-test.steps 列出了具体的任务步骤。
• claudie check 是运行 Claude Code 检查的命令。

易错处提示与排查

• 如果遇到权限问题，请确保你的 GitHub Token 有足够的权限访问仓库。
• 如果 claudie check 命令失败，请检查 .claudie.yaml 配置是否正确，并确认所有依赖已安装。

实用技巧

• 可以结合其他工具（如 SonarQube）来进行更全面的代码质量分析。
• 使用缓存机制加速依赖安装过程，减少等待时间。

示例场景

假设你在开发一个 Web 应用程序，并希望在每次推送或 PR 合并前都进行代码风格检查和单元测试。通过上面的步骤配置好 GitHub Actions 后，每当有人向 main 分支推送新代码或发起 Pull Request 时，GitHub Actions 将会自动运行相应的检查任务。如果发现任何问题（如不符合编码规范），PR 将会被标记为需要修正的状态。

本章小结

• 学习了如何将 Claude Code 集成到 CI/CD 流水线中。
• 掌握了使用 GitHub Actions 配置自动化任务的方法。
• 解决了一些常见的配置错误，并了解了实用技巧。

编写自定义脚本可以帮助你自动化复杂的任务，提高工作效率。通过本章的学习，你将能够创建和使用自定义 Agent 来执行特定的任务，比如代码审查、安全扫描和文档生成。

前置知识

你需要已经完成了 Claude Code 的安装与配置，并熟悉基本的功能和命令。

概念讲透

自定义 Agent 是一种特殊的脚本文件，用于封装特定的任务逻辑。每个 Agent 由两个部分组成：

1. YAML frontmatter: 包含配置元数据，如描述、使用的工具和模型。
2. Markdown body: 定义具体的 task prompt 或 instruction。

Agent 文件通常存储在项目的 .claude/agents/ 目录下，这样可以方便地管理和共享。

分步操作

步骤 1: 创建代码审查员 Agent

我们先来创建一个简单的代码审查员 Agent。这个 Agent 将负责检查代码的质量、安全性和性能。

---
description: Reviews code for quality, security, and performance.
tools:
  - Git
  - Bash
model: glm-4.7
---

请仔细检查以下代码文件，并指出潜在的问题。重点关注以下几个方面：
- 安全漏洞
- 错误处理
- 性能优化建议

格式如下：
**[严重程度: CRITICAL/WARNING/INFO]**
文件路径:行号

将上述内容保存为 .claude/agents/code-reviewer.md 文件。

步骤 2: 创建安全扫描器 Agent

接下来，我们创建一个安全扫描器 Agent，用于检测代码中的安全漏洞。

---
description: Scans code for security vulnerabilities.
tools:
  - Git
  - Bash
model: kimi-k2-turbo-preview
---

请对以下代码进行安全扫描，并列出所有的潜在漏洞。格式如下：
**[严重程度: CRITICAL/WARNING/INFO]**
文件路径:行号

扫描完成后给出一个总结：CRITICAL 数量、WARNING 数量、扫描的文件数。

将上述内容保存为 .claude/agents/security-scanner.md 文件。

步骤 3: 创建文档生成器 Agent

最后，我们创建一个文档生成器 Agent，用于根据代码生成相关文档。

---
description: Generates documentation from code comments.
tools:
  - Git
  - Bash
model: glm-4.7
---

请根据提供的代码注释生成详细的 API 文档。文档应包含以下部分：
- 功能概述
- 方法列表及其详细说明（参数、返回值）
- 示例代码

注意保持文档清晰易懂。

将上述内容保存为 .claude/agents/doc-generator.md 文件。

易错处提示与排查

• 文件路径错误: 确保所有 .md 文件存放在正确的目录下（例如 .claude/agents/）。
• YAML 格式错误: YAML 文件对缩进非常敏感，请确保所有键值对的缩进一致。
• 工具未启用: 如果某些工具不可用，请检查 tools 字段中的工具名称是否正确，并确认这些工具已在 Claude Code 中启用。

实用技巧

• 调试日志: 可以在 YAML frontmatter 中添加 debug_log_path 参数来记录调试信息，便于排查问题。

  debug_log_path: ~/.claude/logs/debug.log

• 版本控制: 将自定义 Agents 提交到版本控制系统中（如 Git），以便团队成员共享和协作。

示例场景

假设你在维护一个大型项目，并希望自动化一些重复性的工作。你可以利用刚刚创建的三个自定义 Agents：

1. 使用 code-reviewer 对新提交的代码进行自动审查。
2. 使用 security-scanner 运行定期的安全审计。
3. 使用 doc-generator 自动生成最新的 API 文档。

通过这种方式，你可以显著减少人工干预的时间，并提高整体开发效率。

本章小结

• 学习了如何创建和管理自定义 Agents。
• 掌握了编写 YAML frontmatter 和 Markdown body 的方法。
• 解决了一些常见的配置错误，并了解了实用技巧。

为了更好地利用 Claude Code 提高工作效率，我们需要掌握一些最佳实践。通过合理配置和使用 Claude Code，我们可以更高效地完成代码审查、安全扫描、文档生成等任务。本章将详细介绍如何优化 CLAUDE.md 文件、管理权限以及自定义命令，帮助你在实际工作中发挥 Claude Code 的最大潜力。

前置知识

• 确保你已经按照前几章的步骤成功安装并配置了 Claude Code。
• 了解基本的命令行操作和 YAML 文件格式。

CLAUDE.md 文件的最佳实践

CLAUDE.md 是一个特殊的文件，Claude 在启动时会自动加载其中的内容。合理的 CLAUDE.md 文件可以帮助我们记录重要的信息，并在整个会话中保持一致性。

如何命名和放置 CLAUDE.md

• 推荐位置: 放在项目的根目录下，命名为 CLAUDE.md，并提交到版本控制系统（如 Git），方便团队成员共享。
• 本地测试: 如果只想在本地使用而不影响其他开发者，可以将其命名为 CLAUDE.local.md 并添加到 .gitignore 中。
• 多项目管理: 对于 monorepos（单一大型代码库管理多个项目），可以在每个子项目目录下分别创建 CLAUDE.md 文件。

# 示例：在项目根目录下创建 CLAUDE.md
touch ~/my-project/CLAUDE.md

内容建议

• 记录项目的规范和约定，如编码风格、提交消息模板等。
• 列出常用的工具及其用途。
• 描述项目的架构和模块划分，帮助新成员快速理解项目结构。

# My Project Specifications

## Coding Standards
- Follow PEP 8 for Python code.
- Use camelCase for JavaScript variables.

## Tools and Commands
- Use `flake8` to check Python code style.
- Run `npm test` to execute all tests.

## Architecture Overview
The project consists of three main modules:
1. Data processing module (`data/`)
2. User interface module (`ui/`)
3. Backend services module (`services/`)

权限管理的最佳实践

默认情况下，Claude Code 会对任何可能修改系统的行为进行询问确认。虽然这种做法确保了安全性，但在日常开发过程中可能会显得过于繁琐。因此，适当调整权限设置是非常必要的。

查看当前权限列表

启动 Claude Code 后，输入 /allowed-tools 命令查看当前允许使用的工具列表。

# 查看允许的工具列表
/allowed-tools

添加或移除工具权限

根据需要添加或移除特定工具的权限。例如，允许文件编辑或执行特定的 Bash 命令。

# 允许文件编辑和 git commit 操作
/allowed-tools add Edit Bash(git commit:*)

注意事项

• 谨慎授权: 只授权你知道是安全的操作。
• 撤销权限: 如果某个操作不再需要被授权，请及时移除相应的权限。

自定义命令的最佳实践

除了内置命令外，你还可以根据自己的需求创建自定义命令。这些命令可以通过简单的 Markdown 文件实现，并在所有会话中使用。

创建自定义命令文件

在 ~/.claude/commands 目录下创建一个新的 Markdown 文件，并编写相应的指令。

# 创建一个新的自定义命令文件 fix-github-issue.md
mkdir -p ~/.claude/commands && touch ~/.claude/commands/fix-github-issue.md

# 编辑 fix-github-issue.md 文件内容如下：
---
name: Fix GitHub Issue
description: Automatically fetch and resolve a GitHub issue by its ID.
command: gh issue view {issue_id} && echo "Implement the necessary changes to fix the issue."
---

使用自定义命令

保存好自定义命令后，在任何 Claude Code 会话中都可以通过 /project:fix-github-issue <issue_id> 调用该命令。

# 使用自定义命令修复 issue #1234
/project:fix-github-issue 1234

示例场景：自动化代码审查流程

假设我们在维护一个大型开源项目，并希望通过自动化方式提升代码质量。我们可以利用 Claude Code 创建一个标准的代码审查流程：

1. 记录规范: 在 CLAUDE.md 中详细描述项目的编码规范和提交要求。
2. 创建自定义命令: 编写一个名为 code-review-checklist.md 的自定义命令文件，在每次 PR 打开时自动提醒审查人员检查的关键点。
3. 配置权限: 允许自动运行一些常用的静态分析工具（如 ESLint、Pylint）来进行初步检查。
4. 集成 CI 流程: 将 Claude Code 的部分功能集成到持续集成系统中（如 Jenkins、GitHub Actions），确保每次代码变更都能经过自动化审核。

通过以上步骤，我们可以大大简化代码审查的过程，并确保所有的贡献都符合项目的高质量标准。

本章小结

• 学习了如何优化 CLAUDE.md 文件以适应不同的工作环境和需求。
• 掌握了如何管理和调整 Claude Code 的权限设置。
• 理解了如何创建和使用自定义命令来扩展 Claude Code 的功能。