Claude 官方给出的常用工作流

原文链接： https://code.claude.com/docs/en/common-workflows

文档索引 获取完整的文档索引：https://code.claude.com/docs/llms.txt 在进一步探索之前，请使用此文件发现所有可用页面。

关于本指南 本指南提供了使用 Claude Code 进行探索代码库、修复 Bug、重构、测试以及其他日常任务的步骤说明。

本页面涵盖了日常开发的实用工作流：探索陌生的代码、调试、重构、编写测试、创建 PR 以及管理会话。每个部分都包含你可以应用到自己项目中的示例提示词（Prompts）。关于更高层面的模式和技巧，请参阅最佳实践。

理解新代码库

获取代码库的快速概览

假设你刚刚加入一个新的项目，需要快速了解其结构。

步骤：

1. 导航到项目根目录

cd /path/to/project

2. 启动 Claude Code

claude

3. 要求提供高层级的概览

> give me an overview of this codebase
（给我这个代码库的概览）

4. 深入了解特定组件

> explain the main architecture patterns used here
（解释这里使用的主要架构模式）

> what are the key data models?
（关键的数据模型有哪些？）

> how is authentication handled?
（身份验证是如何处理的？）

提示：

• 从宽泛的问题开始，然后缩小到特定的领域。

• 询问项目中使用的编码规范和模式。

• 请求项目特定术语的词汇表。

查找相关代码

假设你需要定位与特定功能或特性相关的代码。

步骤：

1. 让 Claude 查找相关文件

> find the files that handle user authentication
（查找处理用户身份验证的文件）

2. 获取组件交互的上下文

> how do these authentication files work together?
（这些身份验证文件是如何协同工作的？）

3. 理解执行流程

> trace the login process from front-end to database
（追踪从前端到数据库的登录流程）

提示：

• 明确你要查找的内容。

• 使用项目中的领域语言。

• 为你的语言安装 代码智能插件，以便让 Claude 具备精确的“转到定义”和“查找引用”导航能力。

---

高效修复 Bug

假设你遇到了一条错误信息，需要找到源头并修复它。

步骤：

1. 与 Claude 分享错误信息

> I'm seeing an error when I run npm test
（我运行 npm test 时看到了一个错误）

2. 询问修复建议

> suggest a few ways to fix the @ts-ignore in user.ts
（建议几种修复 user.ts 中 @ts-ignore 的方法）

3. 应用修复

> update user.ts to add the null check you suggested
（更新 user.ts 以添加你建议的空值检查）

提示：

• 告诉 Claude 重现问题的命令并获取堆栈跟踪（stack trace）。

• 提及任何重现错误的步骤。

• 让 Claude 知道错误是间歇性的还是持续性的。

---

重构代码

假设你需要更新旧代码以使用现代模式和实践。

步骤：

1. 识别需要重构的遗留代码

> find deprecated API usage in our codebase
（在我们的代码库中查找已弃用的 API 用法）

2. 获取重构建议

> suggest how to refactor utils.js to use modern JavaScript features
（建议如何重构 utils.js 以使用现代 JavaScript 特性）

3. 安全地应用更改

> refactor utils.js to use ES2024 features while maintaining the same behavior
（重构 utils.js 以使用 ES2024 特性，同时保持原有行为不变）

4. 验证重构结果

> run tests for the refactored code
（为重构后的代码运行测试）

提示：

• 让 Claude 解释现代方法的好处。

• 要求在需要时保持向后兼容性。

• 以可测试的小增量进行重构。

---

使用专用子智能体 (Subagents)

假设你想使用专用的 AI 子智能体来更有效地处理特定任务。

步骤：

1. 查看可用的子智能体

> /agents

这将显示所有可用的子智能体，并允许你创建新的子智能体。 2. 自动使用子智能体 Claude Code 会自动将适当的任务委派给专用的子智能体：

> review my recent code changes for security issues
（审查我最近的代码更改是否存在安全问题）

> run all tests and fix any failures
（运行所有测试并修复任何失败）

3. 显式请求特定子智能体

> use the code-reviewer subagent to check the auth module
（使用 code-reviewer 子智能体检查 auth 模块）

> have the debugger subagent investigate why users can't log in
（让 debugger 子智能体调查为什么用户无法登录）

4. 为你的工作流创建自定义子智能体

> /agents

然后选择 "Create New subagent"（创建新子智能体）并按照提示定义：

• 一个描述子智能体用途的唯一标识符（例如 code-reviewer, api-designer）。
• Claude 何时应该使用此智能体。
• 它可以访问哪些工具。
• 描述智能体角色和行为的系统提示词（System prompt）。

提示：

• 在 .claude/agents/ 中创建特定于项目的子智能体以便团队共享。

• 使用描述性强的 description 字段以启用自动委派。

• 将工具访问权限限制为每个子智能体实际需要的工具。

• 查看 子智能体文档 了解详细示例。

---

使用计划模式 (Plan Mode) 进行安全代码分析

计划模式 (Plan Mode) 指示 Claude 通过只读操作分析代码库来制定计划，非常适合探索代码库、规划复杂更改或安全地审查代码。在计划模式下，Claude 会在提出计划之前使用 AskUserQuestion 来收集需求并澄清你的目标。

何时使用计划模式

• 多步骤实现：当你的功能需要编辑许多文件时。
• 代码探索：当你想要在更改任何内容之前彻底研究代码库时。
• 交互式开发：当你想要与 Claude 迭代开发方向时。

如何使用计划模式

在会话期间开启计划模式

你可以使用 Shift+Tab 在会话期间循环切换权限模式。

如果你处于正常模式（Normal Mode），Shift+Tab 会首先切换到自动接受模式（Auto-Accept Mode），终端底部会显示 ⏵⏵ accept edits on。再次按 Shift+Tab 将切换到计划模式（Plan Mode），显示为 ⏸ plan mode on。

在计划模式下开始新会话

要以计划模式启动新会话，请使用 --permission-mode plan 标志：

claude --permission-mode plan

在计划模式下运行“无头”查询

你也可以使用 -p 直接在计划模式下运行查询（即在 "无头模式" 下）：

claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"

示例：规划复杂的重构

claude --permission-mode plan

> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
（我需要重构我们的身份验证系统以使用 OAuth2。请制定详细的迁移计划。）

Claude 将分析当前的实现并制定一个全面的计划。你可以通过后续追问来完善它：

> What about backward compatibility?
（向后兼容性怎么处理？）
> How should we handle database migration?
（我们应该如何处理数据库迁移？）

提示： 按 Ctrl+G 在你的默认文本编辑器中打开计划，你可以在 Claude 继续之前直接对其进行编辑。

将计划模式配置为默认

// .claude/settings.json
{
  "permissions": {
    "defaultMode": "plan"
  }
}

请参阅 设置文档 了解更多配置选项。

---

处理测试

假设你需要为未覆盖的代码添加测试。

步骤：

1. 识别未测试的代码

> find functions in NotificationsService.swift that are not covered by tests
（查找 NotificationsService.swift 中未被测试覆盖的函数）

2. 生成测试脚手架

> add tests for the notification service
（为 notification service 添加测试）

3. 添加有意义的测试用例

> add test cases for edge conditions in the notification service
（为 notification service 中的边缘情况添加测试用例）

4. 运行并验证测试

> run the new tests and fix any failures
（运行新测试并修复任何失败）

Claude 可以生成遵循你项目现有模式和规范的测试。在要求进行测试时，请明确你要验证的行为。Claude 会检查你现有的测试文件，以匹配已在使用的风格、框架和断言模式。

为了获得全面的覆盖率，可以要求 Claude 识别你可能错过的边缘情况。Claude 可以分析你的代码路径，并建议针对容易被忽视的错误条件、边界值和意外输入的测试。

---

创建拉取请求 (Pull Requests)

你可以直接要求 Claude（“create a pr for my changes”）或使用 /commit-push-pr 技能来创建拉取请求，该技能一步完成提交、推送和打开 PR。

> /commit-push-pr

如果你配置了 Slack MCP 服务器并在 CLAUDE.md 中指定了频道（例如，“post PR URLs to #team-prs”），该技能会自动将 PR 链接发布到这些频道。

若要更好地控制流程，可以一步步引导 Claude 或 创建你自己的技能：

步骤：

1. 总结你的更改

> summarize the changes I've made to the authentication module
（总结我对 authentication 模块所做的更改）

2. 生成拉取请求

> create a pr
（创建一个 PR）

3. 审查并完善

> enhance the PR description with more context about the security improvements
（完善 PR 描述，增加更多关于安全改进的上下文）

当你使用 gh pr create 创建 PR 时，会话会自动链接到该 PR。你可以稍后使用 claude --from-pr <number> 恢复它。

提示： 在提交之前审查 Claude 生成的 PR，并要求 Claude 突出显示潜在的风险或注意事项。

---

处理文档

假设你需要为代码添加或更新文档。

步骤：

1. 识别未记录的代码

> find functions without proper JSDoc comments in the auth module
（在 auth 模块中查找没有正确 JSDoc 注释的函数）

2. 生成文档

> add JSDoc comments to the undocumented functions in auth.js
（为 auth.js 中的未记录函数添加 JSDoc 注释）

3. 审查并增强

> improve the generated documentation with more context and examples
（用更多上下文和示例来改进生成的文档）

4. 验证文档

> check if the documentation follows our project standards
（检查文档是否遵循我们的项目标准）

提示：

• 指定你想要的文档风格（JSDoc, docstrings 等）。

• 要求在文档中包含示例。

• 请求公共 API、接口和复杂逻辑的文档。

---

处理图像

假设你需要处理代码库中的图像，并希望 Claude 帮助分析图像内容。

步骤：

1. 将图像添加到对话中 你可以使用以下任何一种方法：

2. 将图像拖放到 Claude Code 窗口中。

3. 复制图像并在 CLI 中使用 ctrl+v 粘贴（不要使用 cmd+v）。

4. 向 Claude 提供图像路径。例如："Analyze this image: /path/to/your/image.png"。

5. 让 Claude 分析图像

> What does this image show?
（这张图片显示了什么？）

> Describe the UI elements in this screenshot
（描述此截图中的 UI 元素）

> Are there any problematic elements in this diagram?
（此图表中是否有任何有问题的元素？）

3. 使用图像作为上下文

> Here's a screenshot of the error. What's causing it?
（这是错误的截图。是什么原因造成的？）

> This is our current database schema. How should we modify it for the new feature?
（这是我们要当前的数据库架构。为了新功能我们应该如何修改它？）

4. 从视觉内容获取代码建议

> Generate CSS to match this design mockup
（生成 CSS 以匹配此设计模型）

> What HTML structure would recreate this component?
（什么 HTML 结构可以重建此组件？）

提示：

• 当文字描述不清楚或过于繁琐时使用图像。

• 包含错误截图、UI 设计或图表以获得更好的上下文。

• 你可以在一次对话中处理多个图像。

• 图像分析适用于图表、截图、模型等。

• 当 Claude 引用图像时（例如 [Image #1]），按 Cmd+Click (Mac) 或 Ctrl+Click (Windows/Linux) 链接可在默认查看器中打开图像。

---

引用文件和目录

使用 @ 快速包含文件或目录，无需等待 Claude 读取它们。

步骤：

1. 引用单个文件

> Explain the logic in @src/utils/auth.js

这会将文件的完整内容包含在对话中。 2. 引用目录

> What's the structure of @src/components?

这会提供包含文件信息的目录列表。 3. 引用 MCP 资源

> Show me the data from @github:repos/owner/repo/issues

这会从连接的 MCP 服务器获取数据，格式为 @server:resource。有关详细信息，请参阅 MCP 资源。

提示：

• 文件路径可以是相对的或绝对的。

• @ 文件引用会将文件所在目录及父目录中的 CLAUDE.md 添加到上下文中。

• 目录引用显示文件列表，而不是内容。

• 你可以在一条消息中引用多个文件（例如 "@file1.js and @file2.js"）。

---

使用扩展思考 (Extended Thinking)

扩展思考 默认已启用，它预留了一部分输出 Token 预算（最多 31,999 个 Token），供 Claude 一步步推理复杂问题。此推理过程在详细模式（Verbose Mode）下可见，你可以使用 Ctrl+O 开启该模式。

扩展思考对于复杂的架构决策、棘手的 Bug、多步骤实现规划以及评估不同方法之间的权衡特别有价值。它为探索多种解决方案、分析边缘情况和自我纠正错误提供了更多空间。

注意： 像 "think"、"think hard"、"ultrathink" 和 "think more" 这样的短语会被解释为常规提示指令，不会分配思考 Token。

配置思考模式

思考模式默认开启，但你可以调整或禁用它。

范围	如何配置	详情
切换快捷键	按 Option+T (macOS) 或 Alt+T (Windows/Linux)	开启/关闭当前会话的思考模式。可能需要 终端配置 才能启用 Option 键快捷键。
全局默认	使用 /config 切换思考模式	设置所有项目的默认值。 保存在 ~/.claude/settings.json 中的 alwaysThinkingEnabled。
限制 Token 预算	设置 MAX_THINKING_TOKENS 环境变量	将思考预算限制为特定数量的 Token。例如：export MAX_THINKING_TOKENS=10000。

要查看 Claude 的思考过程，请按 Ctrl+O 切换详细模式，内部推理将显示为灰色斜体文本。

扩展思考 Token 预算的工作原理

扩展思考使用 Token 预算，控制 Claude 在响应之前可以执行多少内部推理。

更大的思考 Token 预算提供：

• 更多空间来一步步探索多种解决方法。
• 彻底分析边缘情况和评估权衡的空间。
• 修改推理和自我纠正错误的能力。

思考模式的 Token 预算：

• 当思考 启用 时，Claude 可以使用输出预算中的最多 31,999 个 Token 进行内部推理。
• 当思考 禁用 时（通过开关或 /config），Claude 使用 0 个 Token 进行思考。

限制思考预算：

• 使用 MAX_THINKING_TOKENS 环境变量 来设定思考预算上限。
• 设置后，此值限制 Claude 可用于思考的最大 Token 数。
• 有关有效 Token 范围，请参阅 扩展思考文档。

警告： 即使 Claude 4 模型显示的是摘要后的思考内容，你仍需为使用的所有思考 Token 付费。

---

恢复之前的对话

启动 Claude Code 时，你可以恢复之前的会话：

• claude --continue 继续当前目录中最近的对话。
• claude --resume 打开会话选择器或按名称恢复。
• claude --from-pr 123 恢复链接到特定拉取请求的会话。

在活动会话中，使用 /resume 切换到不同的对话。

会话按项目目录存储。/resume 选择器显示来自同一 git 仓库（包括 worktrees）的会话。

为你的会话命名

给会话起描述性的名称以便稍后查找。当同时处理多个任务或功能时，这是一个最佳实践。

步骤：

1. 命名当前会话 在会话期间使用 /rename 给它一个好记的名字：

> /rename auth-refactor

你也可以在选择器中重命名任何会话：运行 /resume，导航到一个会话，然后按 R。 2. 稍后按名称恢复 从命令行：

claude --resume auth-refactor

或者在活动会话中：

> /resume auth-refactor

使用会话选择器

/resume 命令（或不带参数的 claude --resume）会打开一个具有以下功能的交互式会话选择器：

选择器中的键盘快捷键：

快捷键	动作
↑ / ↓	在会话之间导航
→ / ←	展开或折叠分组会话
Enter	选择并恢复高亮的会话
P	预览会话内容
R	重命名高亮的会话
/	搜索以过滤会话
A	在当前目录和所有项目之间切换
B	过滤显示当前 git 分支的会话
Esc	退出选择器或搜索模式

会话组织：

选择器显示带有有用元数据的会话：

• 会话名称或初始提示词。
• 自上次活动以来经过的时间。
• 消息计数。
• Git 分支（如果适用）。

分叉会话（使用 /rewind 或 --fork-session 创建）会分组在其根会话下，便于查找相关对话。

提示：

• 尽早命名会话：开始一项独特任务时使用 /rename——以后查找 "payment-integration"（支付集成）比查找 "explain this function"（解释这个函数）要容易得多。

• 使用 --continue 快速访问当前目录中最近的对话。

• 当你确切知道需要哪个会话时，使用 --resume session-name。

• 当你需要浏览和选择时，使用 --resume（不带名称）。

• 对于脚本，使用 claude --continue --print "prompt" 以非交互模式恢复。

• 在恢复之前按 P 预览会话。

• 恢复的对话将使用与原始对话相同的模型和配置开始。

工作原理：

1. 对话存储：所有对话及其完整消息历史记录都会自动保存在本地。

2. 消息反序列化：恢复时，还原整个消息历史记录以保持上下文。

3. 工具状态：保留先前对话中的工具使用情况和结果。

4. 上下文恢复：对话在恢复时保留所有先前的上下文。

---

使用 Git Worktrees 运行并行 Claude Code 会话

假设你需要同时处理多个任务，并且希望 Claude Code 实例之间实现完全的代码隔离。

步骤：

1. 了解 Git Worktrees Git worktrees 允许你将同一个仓库的多个分支检出到不同的目录中。每个 worktree 都有自己的工作目录和隔离的文件，同时共享相同的 Git 历史记录。在 Git worktree 官方文档 中了解更多信息。
2. 创建一个新的 Worktree

# 使用新分支创建一个新的 worktree
git worktree add ../project-feature-a -b feature-a

# 或者使用现有分支创建一个 worktree
git worktree add ../project-bugfix bugfix-123

这将创建一个带有单独仓库工作副本的新目录。 3. 在每个 Worktree 中运行 Claude Code

# 导航到你的 worktree
cd ../project-feature-a

# 在这个隔离的环境中运行 Claude Code
claude

4. 在另一个 Worktree 中运行 Claude

cd ../project-bugfix
claude

5. 管理你的 Worktrees

# 列出所有 worktrees
git worktree list

# 完成后移除 worktree
git worktree remove ../project-feature-a

提示：

• 每个 worktree 都有自己独立的文件状态，非常适合并行的 Claude Code 会话。

• 在一个 worktree 中所做的更改不会影响其他 worktree，防止 Claude 实例相互干扰。

• 所有 worktrees 共享相同的 Git 历史记录和远程连接。

• 对于长时间运行的任务，你可以让 Claude 在一个 worktree 中工作，而你自己在另一个 worktree 中继续开发。

• 使用描述性的目录名称，以便轻松识别每个 worktree 的任务。

• 记得根据项目设置在每个新 worktree 中初始化开发环境。根据你的技术栈，这可能包括：

• JavaScript 项目：运行依赖安装 (npm install, yarn)。

• Python 项目：设置虚拟环境或使用包管理器安装。

• 其他语言：遵循项目的标准设置流程。

---

将 Claude 用作 Unix 风格工具

将 Claude 添加到你的验证流程

假设你想将 Claude Code 用作 linter（代码检查工具）或代码审查员。

将 Claude 添加到构建脚本：

// package.json
{
    ...
    "scripts": {
        ...
        "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
    }
}

（提示词含义：你是一个 linter。请查看相对于 main 分支的更改，并报告任何与拼写错误相关的问题。在一行上报告文件名和行号，在第二行上描述问题。不要返回任何其他文本。）

提示：

• 在 CI/CD 管道中使用 Claude 进行自动代码审查。

• 自定义提示词以检查与项目相关的特定问题。

• 考虑为不同类型的验证创建多个脚本。

输入管道与输出管道 (Pipe in, pipe out)

假设你想将数据通过管道传输给 Claude，并以结构化格式获取数据。

通过管道将数据传输给 Claude：

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

（提示词含义：简明扼要地解释此构建错误的根本原因）

提示：

• 使用管道将 Claude 集成到现有的 shell 脚本中。

• 与其他 Unix 工具结合使用，实现强大的工作流。

• 考虑使用 --output-format 获取结构化输出。

控制输出格式

假设你需要 Claude 以特定格式输出，特别是在将 Claude Code 集成到脚本或其他工具中时。

步骤：

1. 使用文本格式（默认）

cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

这仅输出 Claude 的纯文本响应（默认行为）。 2. 使用 JSON 格式

cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

这会输出一个包含元数据（包括成本和持续时间）的消息 JSON 数组。 3. 使用流式 JSON 格式 (Streaming JSON)

cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

这会在 Claude 处理请求时实时输出一系列 JSON 对象。每条消息都是有效的 JSON 对象，但如果连接在一起，整个输出则不是有效的 JSON。

提示：

• 在只需要 Claude 响应的简单集成中使用 --output-format text。

• 当你需要完整的对话日志时，使用 --output-format json。

• 使用 --output-format stream-json 获取每一轮对话的实时输出。

---

询问 Claude 自身的能力

Claude 内置了对其文档的访问权限，可以回答有关其自身功能和限制的问题。

示例问题

> can Claude Code create pull requests?
（Claude Code 可以创建拉取请求吗？）

> how does Claude Code handle permissions?
（Claude Code 如何处理权限？）

> what skills are available?
（有哪些技能可用？）

> how do I use MCP with Claude Code?
（我如何在 Claude Code 中使用 MCP？）

> how do I configure Claude Code for Amazon Bedrock?
（如何为 Amazon Bedrock 配置 Claude Code？）

> what are the limitations of Claude Code?
（Claude Code 的局限性是什么？）

注意： Claude 提供基于文档的答案来回答这些问题。有关可执行的示例和实际演示，请参阅上面的具体工作流部分。

提示：

• 无论你使用的是哪个版本，Claude 始终可以访问最新的 Claude Code 文档。

• 提出具体问题以获得详细答案。

• Claude 可以解释复杂的功能，如 MCP 集成、企业配置和高级工作流。

---