Claude Code 教程：安装、重构与调试实战

什么是 Claude Code？

Claude Code 是一款直接在您的终端中运行的工具，能够理解您的代码库，并通过自然语言命令协助完成开发任务。 它几乎无需配置即可集成到您的开发环境中，让您专注于编写和改进代码。

以下是 Claude Code 的一些关键能力：

• 编辑与重构： 通过 AI 建议修改、优化并增强您的代码库。
• 修复缺陷： 识别并解决错误、缺失依赖和性能瓶颈。
• 代码理解： 针对代码架构、逻辑与依赖提出问题并获得解答。
• 自动化测试与代码规范： 执行并修复失败的测试，运行 lint 命令，提升代码质量。
• Git 集成： 轻松搜索 git 历史、解决合并冲突、创建提交并生成拉取请求。

无论是参与开源项目还是维护企业级代码库，Claude Code 都能提供贴合您编码风格与项目需求的智能自动化支持。近期更新新增了 自动模式（更少的权限打断）、计划模式（先设计后实现的工作流），以及 Routines（基于触发器调度的云端代理，无需本机运行）。

以下是该服务的理想用户：

• 软件开发者：提升代码质量与可维护性。
• 开源贡献者：理解并优化不熟悉的代码库。
• DevOps 工程师：自动化代码评审与规范检查任务。

Claude Code 在 Max 和 Team Premium 方案上现默认使用 Claude Opus 4.7。 Pro 用户默认使用 Sonnet 4.6，但可在复杂任务中切换至 Opus 模型。您可以在会话中使用 /model 命令切换模型，或通过 /effort 滑杆调整推理深度。您也可以使用 Claude Agents SDK 构建独立的 AI 代理。

Anthropic 还推出了 Cowork，为日常文件与文档任务提供类代理式协助，超越纯编码场景。该功能在 Claude 桌面应用中向所有付费方案用户（Pro、Max、Team、Enterprise）开放。

下面开始我们的上手项目。

步骤 1：安装 Claude Code

开始使用 Claude Code 之前，您需要一个终端、一个要操作的代码项目，以及 Claude 订阅（Pro/Max/Teams/Enterprise）或已启用计费的 Claude Console 账户。

根据您的操作系统与终端，在终端中运行下列命令之一即可安装 Claude Code。

macOS / Linux / WSL： 

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell： 

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

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

注意：通过 npm install -g @anthropic-ai/claude-code 安装的方式仍可用，但已被弃用，建议优先采用上述原生安装流程。如您此前通过 npm 安装，可使用 claude install 进行迁移。

安装完成后，导航到您的项目目录并运行：

cd your-project-directory
claude

在认证阶段，系统会询问您是基于付费订阅使用 Claude Code，还是基于 API 用量计费。

接着，您将收到一个登录链接，页面会显示验证码，请将其输入运行 Claude Code 的终端中。完成后，系统会自动创建 一个专用的“Claude Code”工作区，用于用量追踪与成本管理。

现在，Claude Code 已可以使用。

步骤 2：配置开发环境

在本次演示中，我将使用 Supabase 的 Python 库 supabase-py，它是一个用于与 Supabase 交互的开源 Python 客户端。Supabase 是基于 PostgreSQL 构建的后端即服务（BaaS）。Supabase 提供一系列工具，包括身份认证、实时订阅、存储以及自动生成的 API。

首先克隆仓库并配置开发环境。

1. 打开终端，导航到您希望克隆 Supabase-py 仓库的目录（例如 cd Desktop），并运行以下命令：

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. 然后创建虚拟环境并安装所需依赖，请在终端中逐条运行以下命令：

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

您的 Python 环境现已配置完成，具备运行 Supabase 库所需的全部依赖，仓库也已准备好供您探索。

步骤 3：确定可贡献的方向

一种很好的贡献方式是浏览 GitHub 的 Issues 标签页。在 Supabase 仓库中，我在 client.py 中发现了关于代码可读性、结构以及缺乏有意义注释的问题。

我们将用 Claude Code 完成以下工作：

• 重构代码以增强可读性、可维护性与结构性。
• 添加有意义的文档字符串与行内注释，阐明各组件的用途。
• 通过分析问题与潜在错误来识别并修复缺陷。

步骤 4：尝试使用 Claude Code

既然我们已经位于 supabase-py 文件夹中，请进入包含 client.py 的 supabase 目录并运行 Claude Code：

cd supabase
claude

Claude Code 现在可以访问 Supabase-py 文件夹内的所有文件与目录。下面开始试验。

重构代码

作为改进 Supabase Python SDK 的一部分，我们来重构 client.py 文件，以提高可读性、可维护性与组织性。只需在命令行输入以下提示：

提示：重构 Supabase 文件夹中的 client.py 文件代码。

Claude 在继续之前会请求确认。按下回车键批准更改。完成后，Claude Code 会更新文件、在终端展示差异，并提供变更摘要。

使用 Claude Code，我们对 client.py 做了如下改进：

• 整理导入：Claude Code 将相关导入分组为逻辑部分（认证错误、API 类型、函数错误），为清晰起见重命名部分导入，并移除冗余别名以保持一致性。
• 提升可读性：添加了导入分区注释，并在 __all__ 列表中去重，使组织更清晰。
• 简化客户端选项：通过合并相似导入到一条语句，减少多余行。

下面是原始代码与重构后代码的对比。

为代码编写文档

除了重构，Claude Code 还能在整个项目范围内生成、更新并统一代码文档。它可以识别缺少文档的部分，生成结构化的文档字符串或注释，并检查是否符合项目文档标准。

我们使用 Claude Code 改进了 client.py 的文档，效果包括：

• 在模块层面添加清晰的文档字符串，说明文件用途。
• 添加详细的导入分区注释（错误类型、客户端实现、存储服务）。
• 添加行内注释，描述错误类型、客户端函数和关键组件。

下面是重构后代码与文档化代码的对比。

提示：通过添加注释为 client.py 编写文档，以提升可理解性。

文档添加完成后，您可以通过向 Claude 发出如下提示，验证其是否符合项目标准：

提示：检查文档是否符合我们的项目标准。

修复缺陷

调试可能耗时，但 Claude Code 能通过分析错误信息、定位根因并给出修复建议来缩短循环周期。无论是导入缺失、运行时错误还是逻辑问题，它都能缩小排查范围并提出有针对性的更正。

使用 Claude Code 进行调试的步骤如下：

1. 定位问题：将错误信息提供给 Claude。
2. 获取修复建议： 向 Claude 询问可行的解决方案。
3. 应用并验证修复：按建议实施，并检查问题是否解决。

Claude Code 为解决 client.py 中与导入相关的问题做了如下安排：

• 忽略类型注释： 添加 # type: ignore 注释，以抑制 IDE 和类型检查对未解析导入的告警。
• 一致的错误分类：确保来自认证、数据库、存储与函数模块的错误导入清晰分组。
• 保持代码可读性： 通过注释标明为何忽略某些导入，而非直接删除它们。

下面是原始代码与修复后代码的对比。

提示： 我看到一些错误，例如“Import gotrue.errors 无法解析”。请帮助我修复 client.py 中的所有错误。

Claude Code 命令

以下是一些您可以在 Claude 中尝试的命令。

若想深入了解，建议查看我们的 Claude Code 斜杠命令指南。

Claude Code 高级功能

当您熟悉了重构与调试的基础操作后，可以通过自定义行为来扩展 Claude Code 的能力。Hooks 与插件 可帮助您自动化重复任务并整合外部系统。

Claude Code hooks

Claude Code hooks 是在 Claude Code 会话中，特定事件发生时执行 shell 命令的自动触发器。它们能自动化诸如代码格式化、运行测试与安全检查等重复性任务，这些是 Claude 可能会跳过的步骤。

Hooks 采用事件-动作机制，您需要定义三部分：

• 事件： 何时触发 hook？

• 匹配器： 影响哪些操作？

• 命令： 触发后运行什么？

例如，某个 hook 可在 Claude 写入 Python 文件后触发，并自动运行 black 进行格式化。Hooks 会接收关于发生事件的 JSON 上下文，从而基于文件类型或路径做出更智能的决策。它们可以向 Claude 的对话记录输出信息，或直接向 Claude 发送错误以阻止操作。

常见用例如下：

• 代码格式化： 在写入代码后自动运行 linter 与格式化工具

• 测试： 修改后执行测试套件，及早发现缺陷

• 安全： 阻止修改生产配置或 API 密钥等敏感文件

• 文档： 当源文件变更时自动生成 API 文档

• Git 自动化： 创建智能提交并校验分支保护策略

• 通知： 当重要文件变更时通过 Slack 提醒团队

• 合规： 在允许修改前强制校验许可证头或编码规范

可在 Claude Code 中使用 /hooks 命令设置 hooks，或直接编辑 ~/.claude/settings.json。

Claude Code 插件

插件是将 Claude Code 连接到外部工具、服务与 API 的扩展。Hooks 自动化本地 shell 命令，而插件可与更广泛的开发生态集成，如 CI/CD 流水线、项目管理工具与团队沟通平台。

插件可将多个组件打包——子代理（面向特定任务的专业 Claude 助手）、MCP 服务器（标准化工具集成）与 hooks——组合为一个统一的包进行编排。

插件可以分析代码更改并自动在 Jira 中创建问题，或连接至您的内部测试基础设施。插件响应与 hooks 相同的事件，但会将数据发送到外部服务，并处理响应以影响 Claude 的工作流。

Claude Code 插件擅长以下任务：

• CI/CD 集成： 当文件变更时触发构建、测试与部署

• 项目管理： 在 Jira、GitHub 或 Linear 中自动创建或更新问题

• 团队沟通： 当发生变更时在 Slack 或 Teams 中发布更新

• 代码评审： 自动创建拉取请求并在 GitHub/GitLab 上管理评审

• 外部分析： 调用 SonarQube、CodeClimate 或 Snyk 进行企业级代码扫描

• 自定义工具： 集成公司内部专有系统与工作流

• IDE 扩展： 添加自定义命令与导航辅助

您可以从注册表安装插件，或在组织内部构建并配置其响应的事件。Hooks 与插件协同打造可扩展的平台，使 Claude Code 适配您现有的基础设施。

其他高级功能

2026 年，Claude Code 新增了多项重要功能，扩展了其使用方式与使用场景：

• 计划模式： 先设计后实现的工作流，Claude 会在写代码前生成详细的实现计划。我在所有非平凡任务中都会使用它。
• 自动模式： 一种权限分类器，让 Claude 在更少打断下工作，适合您不想对每次写文件都逐一批准的长任务。
• Routines： 基于 cron、GitHub 事件（如打开 PR）或 webhook 调用触发的定时云端代理。无需保持您的机器运行。
• IDE 集成： 为 VS Code、Cursor 和 JetBrains IDE 提供官方扩展，支持行内 diff、检查点与多会话。
• 远程控制与 Channels： 在手机或其他设备上运行并交互 Claude Code 会话。

结语

在本教程中，我使用 Claude Code 对 Supabase Python SDK 中的一个文件进行了重构、文档化和调试。我们提升了代码可读性、补充了结构化文档，并解决了导入问题。

Claude Code 正在积极进化，新增了计划模式、自动模式与 Routines 等功能，值得您在自己的项目中进行尝试，看看如何融入您的工作流。

作为下一步，建议阅读我们的 Claude Code 最佳实践 教程，了解如何高效利用 Claude 的上下文窗口。若您希望从零开始构建项目，推荐阅读 基于规格驱动的 Claude Code 开发 教程。