Claude Code（五）:CC + Git Worktree

要点

自定义命令：学习在 .claude/commands/目录下创建自定义的 Markdown 命令，通过 $ARGUMENTS 变量接收参数，实现工作流自动化。
Git Worktree 的核心价值：理解 git worktree 如何允许我们在同一个仓库中同时检出多个工作目录，为并行开发提供物理隔离，从根本上避免文件覆盖问题。
并行开发工作流：掌握从创建 Worktree、在隔离环境中运行独立的 Claude Code 会话，到最终合并成果的完整流程。
AI 辅助解决合并冲突：观察 Claude Code 如何在合并不同 Worktree 的代码时，自动分析并解决冲突，展示其在处理复杂 Git 操作时的能力。

一、自定义斜杠命令

在深入并行开发之前，课程首先介绍了一个非常实用的功能：创建自定义斜杠命令。

我们已经熟悉了 /init, /output-style（最近上新，非常牛逼）等内置命令。Claude Code 允许我们通过在项目根目录下的 .claude/commands/ 文件夹中创建 Markdown 文件来定义自己的命令。文件名即命令名。

例如，为了封装一个“实现前端功能”的流程，我们可以创建一个 implement-feature.md 文件：

这个命令文件的内容是一个 Prompt 模板，其中有几个关键点：

$ARGUMENTS：这是一个特殊的变量，它会捕获用户在命令后输入的所有文本。例如，当用户输入 /implement-feature 添加一个主题切换按钮时，$ARGUMENTS 的值就是添加一个主题切换按钮。
指令约束：我们可以加入明确的指令，比如 IMPORTANT: Only do this for front-end features，来约束 AI 的行为。
自动化流程：可以定义一系列固定的操作，比如 write the changes you made to file called frontend-changes.md，将重复性工作自动化。

CLAUDE.md 文件中的内容会在每次启动 Claude Code 会话时自动加载到上下文中，它适合存放项目级的、全局性的背景信息和高频指令。

而 .claude/commands/ 中的自定义命令则不会自动加载。它们只有在被用户显式调用时才会生效。这种设计非常适合封装那些非全局、特定场景下才会使用的工作流。

课程中，Elie 老师还演示了一个常见操作：让 Claude Code 自行提交代码变更。

这个 add and commit changes made 的 Prompt 确实很实用。我的思考是，对于像 commit 这样高频且有固定规范的操作，将其封装成一个强大的自定义命令会是更好的选择。

此外，为了避免每次执行 git 等命令时都弹出授权确认，我们可以在 .claude/settings.local.json 文件中配置命令白名单，实现真正的自动化。

二、Git Worktree

现在，我们来解决核心问题：如何同时在同一个代码库上安全地进行多项开发任务？

直接打开多个终端窗口，在同一个分支上运行多个 Claude Code 实例，几乎必然会导致灾难。当两个实例试图修改同一个文件时，后保存的会覆盖先保存的，造成代码丢失和逻辑混乱。

Git 提供了完美的解决方案：worktree。

git worktree 是一个 Git 命令，它允许你将仓库的多个分支同时检出到文件系统上的不同目录中。每个目录都是一个独立的、功能齐全的工作区，拥有自己的工作文件、暂存区和分支状态，但它们共享同一个底层的 .git 数据库。

这与 git clone 不同。clone 会创建一个全新的、独立的仓库副本。而 worktree 只是创建了多个“视图”或“工作台”，它们都指向同一个中央仓库。这使得它非常轻量，且便于在不同任务之间共享提交和对象。

2.1 创建并行工作环境

课程中，我们通过以下步骤建立了并行开发环境：

创建 Worktree 目录：首先，创建一个用于存放所有 Worktree 的文件夹，例如 .trees，并将其加入 .gitignore。
添加 Worktree：针对每一项开发任务，使用 git worktree add 命令创建一个新的工作目录。每个 Worktree 都会自动基于 main 分支创建一个同名的新分支。

# 任务1: UI 功能开发
$ git worktree add .trees/ui_feature

# 任务2: 测试框架增强
$ git worktree add .trees/testing_feature

# 任务3: 代码质量工具集成
$ git worktree add .trees/quality_feature

执行后，我们的项目结构会如下图所示：

现在我们有了三个物理隔离但共享 Git 历史的工作区。接下来，我们为每个 Worktree 目录打开一个独立的终端窗口，并分别启动 Claude Code 会话。

2.2 并行执行三项任务

我们在三个并行的会话中，分别给 Claude Code 分配了不同的任务：

UI Feature (位于 .trees/ui_feature)：
- 任务：使用我们刚创建的 /implement-feature 命令，添加一个亮色/暗色主题切换按钮。
- Prompt：/implement-feature Toggle Button Design - Create a toggle button...
Testing Feature (位于 .trees/testing_feature)：
- 任务：增强现有的测试框架，为 FastAPI 端点添加 API 测试。
- Prompt：Enhance the existing testing framework for the RAG system...
Quality Feature (位于 .trees/quality_feature)：
- 任务：集成 black 代码格式化工具，并创建运行质量检查的脚本。
- Prompt：Add essential code quality tools to the development workflow...

Elie 老师只在第一个 UI 任务中使用了自定义的 /implement-feature 命令。这可能是因为后两个任务更多是工程配置而非狭义的“功能”开发。

这三个 Claude Code 实例开始并行工作。它们各自修改文件、安装依赖。值得注意的是，任务 2（测试）和任务 3（代码质量）都需要修改 pyproject.toml 这个配置文件。由于它们在不同的 Worktree 中操作，因此不会发生实时覆盖。这个潜在的冲突被推迟到了最后的合并阶段。

2.3 合并与冲突解决

当所有任务在各自的 Worktree 中完成后，我们为每个 Worktree 的变更分别创建了 commit。

# 在 .trees/ui_feature 终端中
claude> add and commit with a descriptive message

# 在 .trees/testing_feature 终端中
claude> add and commit with a descriptive message

# 在 .trees/quality_feature 终端中
claude> add and commit with a descriptive message

现在，我们关闭这三个终端，回到主工作目录的终端，准备将所有成果合并到 main 分支。

我向 Claude Code 发出了一个总括性的指令，让它负责整个合并过程，并处理可能出现的任何冲突。

Claude Code 开始按顺序合并 ui_feature、testing_feature 和 quality_feature 分支。前两个合并很顺利。当合并 quality_feature 时，预期的冲突发生了——因为 main 分支（已经合并了 testing_feature 的变更）和 quality_feature 分支都修改了 pyproject.toml 文件。

此时，Claude Code 展现了它处理复杂工作流的能力。它检测到了合并冲突，并自动进入冲突解决模式。