Claude Code 代理：自主编码工作流实用指南

如果有人问我，Claude Code 与 ChatGPT 或 GitHub Copilot 的不同之处是什么，我不会从语言模型讲起，而会从工作流讲起。

想象一下，您在一个 Git 仓库内打开终端，只输入一句提示：

Add request validation to every FastAPI endpoint,
write tests for the new validation logic, update the documentation, 
and commit everything using a descriptive Git commit message.

Claude Code 不再追问几十个后续问题，而是直接开始工作。

它会搜索您的项目以理解 API 结构，识别每个端点，编辑相应文件，生成测试、修复失败、更新文档，并创建一条总结变更的 Git 提交。

从您的视角看，这更像是在给一位能干的队友分配任务，而不是与 AI 聊天。

这种转变正是 Claude Code 代理令人兴奋的原因。

实现这一点的关键在于 Claude Code 子代理。Claude Code 并不会强迫单一会话去推理整个仓库，而是可以启动专门的工作者，分别调查项目的不同部分、制定实现计划，或独立修改代码，然后再向主会话汇报。

Claude Code 不再试图在一段对话内解决所有问题，而是可以把工作委派给专门的代理。

三种主要的代理类型是：

• Explore（探索），专注于项目探索
• Plan（规划），专注于构建实现计划，以及
• 通用型（General-purpose），用于编辑代码和执行命令。

这改变了我处理开发工作的方式。我不再问“AI 能写这个函数吗？”，而是会问“我能安全地交给它的最大一块工作是什么？”

阅读完本指南，您将了解如何高效使用 Claude Code 代理、何时使用不同的子代理类型、如何用 CLAUDE.md 配置持久项目记忆，以及如何构建既省时又不丧失控制的自主工作流。

前置条件

本指南假设您熟悉使用终端，并能用 cd、ls 或 dir 等基本命令行命令在目录间导航。

您不需要精通 Bash，但应能自如地在命令行中工作。

您还需要：

• 在您的机器上安装 Node.js
• 一个 Anthropic API 密钥
• 一个可用于试验的 Git 仓库
• 对 Python、JavaScript 或其他编程语言的基本了解

如果您完全是 Claude Code 新手，建议在深入了解子代理之前先阅读Claude Code：含实用示例的指南。

什么是 Claude Code 代理？

Claude Code 代理是自主的工作者，它们使用您的本地仓库、终端和开发工具来完成多步骤的软件开发任务。

与 ChatGPT 或 Claude Chat 不同，Claude Code 能检查文件、执行 Bash 命令、编辑源码，并在返回结果前自行校验工作。

大多数 AI 编码助手仍遵循对话式工作流。

您提问，收到回答，然后再决定下一步该做什么。

这对编写 SQL 查询或讲解 scikit-learn 流水线很有效，但当一个任务跨越 20 个文件、需要多条终端命令，或依赖于对陌生仓库的理解时，这种方式就会失灵。

Claude Code 的处理方式不同。

由于它直接在您的 Git 仓库内工作，它可以在做决定前先调查代码。不用让您把文件粘贴进聊天窗口，它会自己读取项目并收集所需上下文。

假设您提出：

Replace every custom customer ID validator with Pydantic models, 
update the FastAPI endpoints, rewrite the affected pytest tests, 
and summarize the migration.

传统聊天机器人可能会生成示例代码并索要更多信息。

Claude Code 则会搜索仓库、识别现有校验逻辑、编辑相关文件、运行测试套件、修复它引入的回归，并汇报完成的工作。

这种从“回答问题”到“完成目标”的转变，使基于 Claude Code 的代理式编码在日常开发中与众不同。

代理循环如何工作？

每个 Claude Code 代理都遵循相同的决策循环：读取信息，决定下一步，执行操作，然后评估结果，再重复该过程。

循环很简单，但重复几十次后，代理能从错误中恢复，而不是在一次失败后就停下。

设想让 Claude Code 修复失败的测试套件。工作流通常如下所示：

图示展示了 Claude Code 在修复失败测试时的运作方式

我认为这是理解 Claude Code 最容易的心智模型。

代理并不是想一步解决整个问题。它会基于上一步动作的结果，连续做出一系列小决策。

子代理遵循完全相同的循环，但会在各自隔离的上下文中进行。

这种区别很重要，因为一次工具调用只能执行一个动作，而子代理可以在汇报前，花费几十个推理步骤朝一个目标推进。

为什么 Claude Code 要使用子代理？

Claude Code 使用子代理，是因为大型仓库很难放进单一的工作上下文中。一个包含 Python 服务、React 应用、SQL 迁移与 Terraform 配置的 monorepo，信息量远超出单个代理一次应当推理的范围。

Claude Code 不会把仓库当作一个巨大的任务，而是把有重点的调查委派给专门的工作者。

一个 Explore 代理可能分析鉴权，另一个检查数据库模型，第三个审查 API 路由。编排器会在决定下一步前整合这些发现。

这种架构还有一个实用优势：许多调查可以并行进行。

您无需自己阅读每个目录，也不用等一个代理检查完整个仓库，多个子代理可以同时探索不同区域。

您会在后续教程中看到这一模式。Explore 代理收集信息，Plan 代理组织实现方案，而通用型代理执行实际的开发工作。

若您想更广泛地了解超出 Claude Code 的自主 AI 系统如何工作，DataCamp 的文章LLM Agents Explained: Architecture, Frameworks, and Use Cases 提供了出色的概念概览。

如何安装并设置 Claude Code？

在开始使用 Claude Code 代理前，我们需要先完成安装。

好消息是，入门只需几分钟。

安装 Claude Code

Claude Code 以 npm 包形式发布，因此您需要在机器上安装 Node.js。关于安装方法，建议参阅npm 文档中的 Node.js 与 npm 安装说明。

全局安装 Claude Code：

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

然后在 Anthropic Console 中创建一个 Anthropic API 密钥，并将其添加到您的环境变量中。

在 macOS 或 Linux 上：

export ANTHROPIC_API_KEY="your_api_key_here"

在 Windows PowerShell 上：

$env:ANTHROPIC_API_KEY="your_api_key_here"

要验证一切安装正确，运行：

claude --version

如果 Claude Code 输出其已安装的版本号，说明您已准备就绪。

此时也值得确认 Git 是否可用，因为许多 Claude Code 工作流涉及读取仓库历史、创建提交或对比变更。

如果尚未安装 Git，请按照Git 安装指南进行安装。

在继续之前，请确保上述两个命令都能成功执行。

您的第一个 Claude Code 会话

安装好 Claude Code 后，使用 cd my-project 进入任意 Git 项目。

然后启动 Claude Code：claude。

在让它写代码之前，先花几分钟了解它如何探索仓库。我通常会从这些提示开始：

• “这个仓库是做什么的？”
• “请解释架构。”
• “查找所有 TODO 注释。”
• “哪些模块包含核心业务逻辑？”
• “鉴权是如何实现的？”

这些问题不会直接产出新功能，但会为 Claude Code 提供与新队友在写代码前相同的背景知识。

我发现，先投入两三分钟做探索，通常比直接提出功能需求能得到更好的实现。

下一步是使用 CLAUDE.md 配置持久的项目记忆。就我的经验而言，没有哪一个文件能在长期里对 Claude Code 的工作质量产生更大的影响。

为什么 CLAUDE.md 对 Claude Code 来说是最重要的文件？

CLAUDE.md 是一份持久的指令文件，它在 Claude 开始推理任务之前，告知您的偏好以及项目的工作方式。

您无需每次开启新会话都重新解释技术栈、编码约定和开发流程，而是一次性记录下来，让后续每个代理都能基于这份共享上下文开展工作。

很多人在了解 Claude Code 代理时，往往把注意力放在提示词上。我认为这本末倒置了。

写好一份 CLAUDE.md 对结果质量的提升，远超过反复打磨提示词的措辞，因为每个代理都会从对您项目的相同理解出发。

想想您如何让一位新工程师上手项目。

您大概不会先扔给 TA 一个 Jira 工单。您会先解释仓库、演示如何运行测试套件、指出一些编码约定，并提醒哪些代码库部分不要动。

CLAUDE.md 的作用正是如此。

一旦开始使用 Claude Code 的自主工作流，这份投入就会变得更加物超所值。

要让代理独立工作，就需要可靠的项目上下文。

没有它，Claude Code 就会花时间重复发现信息，或基于与您团队标准不匹配的假设开展工作。

您的 CLAUDE.md 应该包含什么？

一份好的 CLAUDE.md 不是项目文档或 README.md 的替代品。它是 Claude Code 在读代码、写功能和运行开发工具时反复需要的指令合集。

我通常把它分为五个部分：项目概览、技术栈、编码约定、常用命令，以及需要避免的目录。下面我会逐一简述。

项目概览

先用一段简短描述说明项目到底做什么。

Customer analytics platform built with FastAPI.
The application serves machine learning predictions through REST APIs.
Production deployments run through GitHub Actions.

这三行会立刻告诉 Claude Code，它面对的是 FastAPI、GitHub Actions，以及一个机器学习应用，而不是一个通用的 Python 仓库。

技术栈

接下来，直接罗列定义该项目的主要库与框架。

Python 3.12
FastAPI
Pydantic v2
SQLAlchemy
PostgreSQL
Pytest
Ruff

凡是重要的地方我都会附上版本号。

Pydantic v2 的推荐用法和 v1 不同，Claude Code 不应该去猜您使用的是哪个 API。

如果您在用较老的包，这就尤为重要，避免让它基于错误假设展开工作。

编码约定

本节记录您经常需要重复的规则。

Always use type hints.
Prefer dependency injection.
Write tests for every new feature.
Keep business logic separate from API routes.
Reuse existing utility functions before creating new ones.

注意这些是工程实践规则，而非样式偏好。

Claude Code 通常能从现有文件中推断格式，但它并不会自动知道您的团队期望每个端点都使用依赖注入，或每个功能都要包含一份 pytest 测试。

常用命令

Claude Code 经常通过运行开发命令来验证自己的工作。提供团队实际使用的精确命令能避免不必要的反复试错。

这可以是特定的 task 动作或 CI 脚本等。

pytest
Run one test file:
pytest tests/test_api.py
Lint:
ruff check .
Format:
ruff format .
Start the development server:
uvicorn app.main:app --reload

对于带有自定义脚本、Docker 工作流，或使用 poetry、uv、tox 等工具的仓库，这一节尤其有用。

需要避免的文件和目录

每个仓库都有不应被自动修改的文件。

示例包括：

Never edit generated files.
Do not modify Alembic migrations.
Avoid changing Terraform configuration unless requested.
Do not update dependency versions automatically.

我发现这一节能避免的错误比大多数其他内容都多。用一句话告诉 Claude Code 不要碰生成代码，比起事后审查几十处不必要改动，代价要低得多。

一个 CLAUDE.md 示例

下面是一个面向 Python API 项目的简化示例。

注意我如何使用 markdown 格式提升可读性，并为 Claude 提供更多上下文。

# Project Overview

Customer analytics platform built with FastAPI.

## Technology

- Python 3.12
- FastAPI
- PostgreSQL
- SQLAlchemy
- Pydantic v2
- Pytest
- Ruff

## Coding Standards

- Use type hints everywhere.
- Write tests for new features.
- Prefer dependency injection.
- Keep business logic separate from API routes.

## Common Commands

pytest
ruff check .
ruff format .

## Avoid Editing

generated/
alembic/versions/
terraform/

不必追求第一版就完美。

我的 CLAUDE.md 也随着我发现值得记录的重复性指令而多次调整。把它当作源码对待，而不是一成不变的文档。

如需更深入地了解如何编写高效的指令文件，DataCamp 的《Writing the Best CLAUDE.md：Claude Code 完整指南》覆盖了更大的示例和更高级的模式。

应使用项目级还是用户级的 CLAUDE.md？

Claude Code 支持两种指令范围。理解它们的区别有助于将项目规则与您的个人偏好区分开来。

项目级 CLAUDE.md

项目级文件位于仓库内部。

	my-project/
	│
	├── CLAUDE.md
	├── app/
	├── tests/
	└── pyproject.toml

该文件中的内容仅适用于该仓库。我会在其中记录技术选择、测试命令、编码约定、目录结构以及仓库特定规则。

由于文件与源码并存，每位贡献者在克隆项目后都会获得相同的指令。可把它看作是在每个代理开始工作前发放的一本手册。

用户级 CLAUDE.md

Claude Code 也支持全局配置文件。

该文件会伴随您在不同项目间切换。我把它视作个人操作手册，而非项目文档。

例如，我的用户级文件可能包含这样的指令：

Explain architectural trade-offs.
Suggest performance improvements when appropriate.
Default to Python examples unless another language is requested.
Keep explanations concise.

无论我是在用 FastAPI、React，还是 PyTorch，这些偏好都适用。

两份文件如何协同

我刚开始使用 Claude Code 时有一个困惑点：这两份文件并非互斥。

会先加载用户级 CLAUDE.md，然后项目级 CLAUDE.md 会补充与仓库相关的特定指令。

我把它看作一个层级结构。

全局文件定义我的工作偏好；项目文件解释这个仓库如何工作。

二者结合，使每个代理在开始推理前同时具备个人偏好与项目上下文。

Claude Code 会在开始任务前，将用户级偏好与项目级指令合并。

Claude Code 子代理的三种类型是什么？

Claude Code 使用三种专门的子代理类型，因为不同的开发任务需要不同的工具。

调查仓库的代理不需要编辑文件的权限，而实现功能的代理大概率需要访问 Bash、Git 和测试套件。

刚开始使用 Claude Code 时，我总是直接选择通用型代理，因为它看起来最强大。

后来我发现，这会在时间和 Token 上付出超出必要的代价。大多数工作流遵循“先探索，再规划，最后实现”会更快。

三种 Claude Code 子代理对比

名称已经相当直观，但每种代理在更大的工作流中都扮演着独特角色。

什么是 Claude Code Explore 代理？

Claude Code Explore 代理是只读调查员，它会搜索仓库并总结发现，而不修改任何文件。

当我打开一个不熟悉的项目时，这是我最常用的代理。与其自己翻几十个 Python 模块或 JavaScript 组件，不如让 Explore 代理解释子系统如何工作，并指向关键文件。

适用场景包括：

• 查找鉴权的实现位置
• 跨多个服务追踪一次请求
• 审计日志或错误处理
• 定位已弃用的 API
• 总结某个包或目录
• 识别重复的业务逻辑

由于 Explore 代理不能编辑文件或执行 Shell 命令，因此也是最安全的并行运行代理。

选择详尽程度

Explore 代理支持不同的调查深度。

如果只是定位函数，我会用最快设置；如果要为跨多个包的重构做准备，多等一分钟做更深入的调查通常是值得的。

什么是 Claude Code Plan 代理？

Claude Code Plan 代理会分析所请求的变更，并产出一份实现策略，而不修改仓库。

我几乎从不跳过这一步。多花一分钟审阅计划，远比做到一半才发现另一个子系统依赖被改动的代码要划算。

典型计划包括：

• 需要修改的文件
• 推荐的实现顺序
• 依赖与集成点
• 测试策略
• 风险或假设

审阅计划后，您可以继续细化，或直接交给通用型代理执行。

DataCamp 的Claude Code Plan 模式：以设计评审为先的重构循环对这种“先评审再动手”的工作流有更详细的探讨。

什么是通用型 Claude Code 代理？

通用型代理可以读取文件、编辑源码、执行 Bash 命令、运行测试，并持续工作直至满足所请求的目标。

这是实际“构建软件”的代理。它拥有与其他代理相同的仓库上下文，但也获得了做出修改与验证结果的权限。

典型任务包括：

• 实现新功能
• 重构多个模块
• 迁移依赖
• 更新文档
• 协调多个包间的变更

通用型代理会消耗更多 Token，因为它们实际做的工作多得多。

这也是我喜欢“探索 → 规划 → 实现”模式的另一个原因。

更便宜的代理负责前期问题，将更昂贵的实现工作留到路径清晰时再做。

至此，我们已经介绍了让 Claude Code 代理奏效的要素：通过 CLAUDE.md 提供持久项目记忆，以及用于调查、规划、实施的专门子代理。

接下来，我们将把这些要素组合起来，构建完整的代理工作流，您可以在自己的项目中直接使用。

运行您的第一个 Claude Code 代理工作流

想要最大化 Claude Code 的价值，最好是给它一个目标，而非只要某个单点产出。

我形成了一个简单的工作流，适用于 Python 项目、数据科学仓库和 Web 应用：

1. 探索仓库。
2. 创建计划。
3. 评审计划。
4. 实施变更。
5. 验证结果。

这不是硬性规定，但与有经验的工程师处理大变更的方式一致。

花一分钟理解仓库，通常能省下几分钟后续纠正不必要编辑的时间。

创建更充分的提示，哪怕花一小时微调它，也能在后续为您省下数小时的工作。

工作流 1：探索不熟悉的代码库

当您接手一个新仓库，或回到一个许久未动的项目时，从 Explore 代理开始是最好的选择。

与其手动阅读目录，不如让 Claude Code 调查架构并总结要点。

例如：

Use an Explore agent to explain how authentication works. 
Identify the main modules involved, summarize the request flow, 
and highlight any technical debt or TODO comments.

结果不会是一大堆源代码的复制，而通常是对鉴权流程的简洁说明、相关文件列表，以及值得关注的区域。

我常把该总结作为下一步任务的起点，而不是从零写一条新提示。

工作流 2：先规划再实现

理解仓库后，请让 Plan 代理在写代码之前先设计实现方案。

这是最容易养成的习惯之一，也帮我避免了几次方向错误的重构。

提示示例：

Create an implementation plan for adding role-based access control.
Identify the files that should change, potential risks,
dependencies, and a recommended implementation order.
Do not modify any code.

在继续前请先评审计划。如果一切合理，您可以把该计划直接交给通用型代理。

若不合理，调整设计文档远比撤销十几个文件的改动容易得多。

用另一个 Claude Code 会话来评审第一次会话的产出，是充分利用这一步的好方法。一个简单的提示可以是：

This is my current goal: to add role-based access control to this repository. 
Take a look at this existing implementation plan and do an adversarial review.
Once done, create a report that summarizes the strong and weak points of the plan.

工作流 3：并行化仓库探索

我最喜欢的 Claude Code 功能之一是探索不必串行进行。如果您的项目包含多个相互独立的子系统，您可以同时调查它们。

例如，您可以启动一个 Explore 代理检查 API 层，另一个审查数据库模型，第三个查看机器学习流水线。

当这些代理独立工作时，编排器会把它们的发现整合成一个响应。

我不会在每个任务中都用并行代理，但它们非常适合大型 monorepo 或拥有众多服务的成熟应用。与其等待一次漫长的调查，不如同时分析项目的多个部分，更快地理解仓库。

最佳做法是用一个“大代理”来编排多个代理。

这种代理编排可以在不启动多个会话的情况下并行完成工作，并把结果汇聚到单一上下文中。

一个不错的提示示例是：

I want you to look at the following components: 
Inspect the API layer, review the DB models, and examine the ML pipeline. 
Look for weaknesses. 
I want this done in parallel, so spawn subagents using Opus/Sonnet models 
in order to do this work and have each generate a concise report and share out 
one master document that outlines the work needed to be done.

Claude Code 代理的最佳实践

使用 Claude Code 遇到的大多数问题并非由模型本身引起，而是由于提示含糊、缺少项目上下文，或要求它解决一个自己并未充分理解的问题。

在经常使用 Claude Code 之后，以下这些习惯对我的结果影响最大。

编写可执行的提示

当目标、范围和成功标准明确时，Claude Code 的表现最佳。

不要只用宽泛的措辞描述终极目标，而应明确告诉代理应检查哪个仓库、应修改哪些文件，以及如何判定任务完成。

例如：

❌ 含糊 改进 API。

✅ 具体 将 FastAPI 的鉴权端点更新为使用 Pydantic v2 校验，生成或更新相关的 pytest 测试，运行测试套件，并对每个被修改的文件进行总结。

第二条提示为 Claude Code 提供了清晰的目标、边界与验证方式，通常能减少后续提示与人工清理。

在上下文成为问题前进行管理

对话时间一长，Claude Code 就会把更多 Token 用在记住既往讨论上，而不是推理当前任务。

这时请使用 /compact 来总结对话，同时保留重要上下文。我发现及早压缩要比等到性能明显下降后再做更好。

一份好的 CLAUDE.md 也很有帮助，因为项目约定无需在每个会话重复。Claude Code 会自动加载这些上下文，把更多时间留给您要求它完成的工作。

关于上下文管理、测试驱动开发与提示设计的更多建议，请参见Claude Code 最佳实践：规划、上下文传递与 TDD。

考虑 Token 成本

并非所有任务都需要通用型代理。

如果您只是想找出某个函数的定义位置，Explore 代理通常更快且更省。

如果在评审大规模架构变更，Plan 代理往往能提供足够信息，而无需修改仓库。

把通用型代理保留给真正需要执行的任务，例如编辑文件、运行 Bash 命令或运行测试。让合适的代理匹配合适的任务，有助于控制运行时间和 Token 用量。

知道何时不该用代理

Claude Code 代理会带来一些开销，因为涉及上下文与 Token 的交换。

它们会调查仓库、推理任务并验证工作。对于非常小的改动，这种开销未必划算。

对于以下情况，您大概不需要代理：

• 重命名单个变量。
• 修正文档中的一个错字。
• 解释一条 Python 报错信息。
• 回答一个简单的 SQL 问题。

这些场景下，普通的 Claude Code 对话甚至手动编辑往往更快。我通常会在启动代理前问自己一个问题：解释这个任务所花的时间，会不会比我自己动手更久？如果答案是肯定的，我就保持简单。

结语

Claude Code 代理改变了 AI 在软件开发中的角色。它们不再只是生成零散片段，而是可以以较少的监督，完成更复杂的问题，如调查仓库、设计实现、修改代码、执行测试，并推进多步骤目标。

我最大的体会是，优秀的工作流比优秀的提示更重要。

一份清晰的 CLAUDE.md，几分钟的仓库探索，再加上一份经过思考的实现计划，几乎总能比直接跳进代码生成带来更好的结果。

随着您花更多时间使用 Claude Code，您可能会发展出自己的工作流。而我的做法几乎每次都相同：先探索，再规划，最后实现。

这是个简单的习惯，却为我省下了无数次评审循环，也让我比刚开始使用时更信任自主工作流。

如果您想进一步了解自主系统背后的更广泛理念，推荐以下资源：

• Introduction to AI Agents
• Introduction to Claude Models
• Claude Code Hooks：工作流自动化实用指南
• Claude Agent SDK 教程：使用 Claude Sonnet 4.5 创建代理
• 如何构建 Claude Code 插件
• Claude Code 2.1：含实用示例的指南
• Model Context Protocol（MCP）：含演示项目的指南
• AI Agents with Hugging Face smolagent