Claude Code 教程：实践中的安装、重构与调试

什么是 Claude Code？

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

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

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

无论是参与开源项目还是管理企业级代码库，Claude Code 都能提供与您的编码风格和项目需求相适配的智能自动化能力。近期更新新增了 auto 模式（更少的权限中断）、plan 模式（以设计为先的工作流），以及 Routines（在不启动本机的情况下按触发条件运行的定时云端代理）。

以下人群尤其适合使用：

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

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 账户。

根据您的操作系统和终端，在终端中运行以下命令之一即可完成安装。

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

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

随后，您会收到一个登录链接，打开后获取验证码，并将其输入运行 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 做了如下改进：

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

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

代码文档化

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

我们使用 Claude Code 改进了 client.py 的文档，带来了如下结果：

• 清晰的模块级文档字符串，解释文件用途。
• 详尽的板块注释，对导入进行分类（错误类型、客户端实现、存储服务）。
• 用于描述错误类型、客户端函数和重要组件的内联注释。

以下是重构后与文档化后的并排对比。

提示：通过添加注释对 client.py 进行文档化，以提升理解度。

文档添加完成后，您可以提示 Claude 检查其是否符合项目标准：

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

修复缺陷

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

使用 Claude Code 调试的方法如下：

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

Claude Code 为解决 client.py 中与导入相关的问题做了以下调整：

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

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

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

Claude Code 命令

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

我也建议查看 Anthropic 官方教程 以及我们的 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 以阻止操作。

Hooks 的常见用例如下：

• 代码格式化：在写入代码后自动运行 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 新增了多项重要能力，扩展了其使用场景与方式：

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

结语

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

Claude Code 正在快速演进，新增了 plan 模式、auto 模式与 Routines，值得您在自己的项目中多加尝试，看看它如何融入您的工作流。

欲进一步学习，建议阅读我们的 Claude Code 最佳实践 教程，了解如何充分利用 Claude 的上下文窗口。若您希望从零开始构建项目，推荐阅读我们的 使用 Claude Code 的规格驱动开发 教程。