{/* TRANSLATED — 已翻译为中文 */}

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

# 常见工作流

> 使用 Claude Code 探索代码库、修复 bug、重构、测试和其他日常任务的分步指南。

本页面收集了日常开发的简短方案。有关提示和上下文管理的更高层次指导，请参阅[最佳实践](/en/best-practices)。

本页面涵盖：

* [提示方案](#prompt-recipes)：用于探索代码、修复 bug、重构、测试、PR 和文档
* [恢复之前的对话](#resume-previous-conversations)：使任务可以跨多个会话
* [使用工作树运行并行会话](#run-parallel-sessions-with-worktrees)：使并发编辑不会冲突
* [编辑前先规划](#plan-before-editing)：在更改写入磁盘之前审查更改
* [将研究委派给子代理](#delegate-research-to-subagents)：保持主上下文干净
* [将 Claude 管道到脚本中](#pipe-claude-into-scripts)：用于 CI 和批处理

## 提示方案

这些是用于日常任务的提示模式，如探索不熟悉的代码、调试、重构、编写测试和创建 PR。每个方案适用于任何 Claude Code 界面；根据您的项目调整措辞。

### 理解新代码库

有关在 monorepo 或大型代码库中配置 Claude Code，请参阅[Monorepo 和大型仓库](/en/large-codebases)。

#### 获取快速代码库概览

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

<Steps>
  <Step title="导航到项目根目录">
    ```bash theme={null}
    cd /path/to/project 
    ```
  </Step>

  <Step title="启动 Claude Code">
    ```bash theme={null}
    claude 
    ```
  </Step>

  <Step title="请求高层概览">
    ```text theme={null}
    give me an overview of this codebase
    ```
  </Step>

  <Step title="深入了解特定组件">
    ```text theme={null}
    explain the main architecture patterns used here
    ```

    ```text theme={null}
    what are the key data models?
    ```

    ```text theme={null}
    how is authentication handled?
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 从广泛的问题开始，然后缩小到特定领域
  * 询问项目中使用的编码约定和模式
  * 请求项目特定术语的词汇表
</Tip>

#### 查找相关代码

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

<Steps>
  <Step title="让 Claude 查找相关文件">
    ```text theme={null}
    find the files that handle user authentication
    ```
  </Step>

  <Step title="获取组件如何交互的上下文">
    ```text theme={null}
    how do these authentication files work together?
    ```
  </Step>

  <Step title="理解执行流程">
    ```text theme={null}
    trace the login process from front-end to database
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 从广泛的问题开始，然后缩小到特定领域
  * 使用项目中的领域语言
  * 为您使用的语言安装[代码智能插件](/en/discover-plugins#code-intelligence)，为 Claude 提供精确的"转到定义"和"查找引用"导航
</Tip>

***

### 高效修复 bug

假设您遇到了错误消息，需要找到并修复其来源。

<Steps>
  <Step title="与 Claude 分享错误">
    ```text theme={null}
    I'm seeing an error when I run npm test
    ```
  </Step>

  <Step title="请求修复建议">
    ```text theme={null}
    suggest a few ways to fix the @ts-ignore in user.ts
    ```
  </Step>

  <Step title="应用修复">
    ```text theme={null}
    update user.ts to add the null check you suggested
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 告诉 Claude 复现问题的命令以获取堆栈跟踪
  * 提及重现错误的任何步骤
  * 让 Claude 知道错误是间歇性的还是持续的
</Tip>

***

### 重构代码

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

<Steps>
  <Step title="识别需要重构的遗留代码">
    ```text theme={null}
    find deprecated API usage in our codebase
    ```
  </Step>

  <Step title="获取重构建议">
    ```text theme={null}
    suggest how to refactor utils.js to use modern JavaScript features
    ```
  </Step>

  <Step title="安全地应用更改">
    ```text theme={null}
    refactor utils.js to use ES2024 features while maintaining the same behavior
    ```
  </Step>

  <Step title="验证重构">
    ```text theme={null}
    run tests for the refactored code
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 让 Claude 解释现代方法的好处
  * 在需要时要求更改保持向后兼容性
  * 以小的、可测试的增量进行重构
</Tip>

***

### 使用测试

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

<Steps>
  <Step title="识别未测试的代码">
    ```text theme={null}
    find functions in NotificationsService.swift that are not covered by tests
    ```
  </Step>

  <Step title="生成测试脚手架">
    ```text theme={null}
    add tests for the notification service
    ```
  </Step>

  <Step title="添加有意义的测试用例">
    ```text theme={null}
    add test cases for edge conditions in the notification service
    ```
  </Step>

  <Step title="运行并验证测试">
    ```text theme={null}
    run the new tests and fix any failures
    ```
  </Step>
</Steps>

Claude 可以生成遵循您项目现有模式和约定的测试。在请求测试时，请具体说明您想要验证的行为。Claude 会检查您现有的测试文件以匹配正在使用的风格、框架和断言模式。

要获得全面覆盖，请让 Claude 识别您可能遗漏的边界情况。Claude 可以分析您的代码路径并建议针对错误条件、边界值和意外输入的测试，这些很容易被忽略。

***

### 创建拉取请求

您可以通过直接要求 Claude 来创建拉取请求（"create a pr for my changes"），或逐步指导 Claude：

<Steps>
  <Step title="总结您的更改">
    ```text theme={null}
    summarize the changes I've made to the authentication module
    ```
  </Step>

  <Step title="生成拉取请求">
    ```text theme={null}
    create a pr
    ```
  </Step>

  <Step title="审查和完善">
    ```text theme={null}
    enhance the PR description with more context about the security improvements
    ```
  </Step>
</Steps>

当您使用 `gh pr create` 创建 PR 时，会话会自动链接到该 PR。要稍后返回，请运行 `claude --from-pr <number>` 或将 PR URL 粘贴到 [`/resume` 选择器](/en/sessions#use-the-session-picker)搜索中。

<Tip>
  在提交之前审查 Claude 生成的 PR，并让 Claude 强调潜在风险或注意事项。
</Tip>

### 处理文档

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

<Steps>
  <Step title="识别未文档化的代码">
    ```text theme={null}
    find functions without proper JSDoc comments in the auth module
    ```
  </Step>

  <Step title="生成文档">
    ```text theme={null}
    add JSDoc comments to the undocumented functions in auth.js
    ```
  </Step>

  <Step title="审查和增强">
    ```text theme={null}
    improve the generated documentation with more context and examples
    ```
  </Step>

  <Step title="验证文档">
    ```text theme={null}
    check if the documentation follows our project standards
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 指定您想要的文档风格（JSDoc、docstrings 等）
  * 要求在文档中包含示例
  * 要求为公共 API、接口和复杂逻辑提供文档
</Tip>

***

### 在笔记和非代码文件夹中工作

Claude Code 可在任何目录中工作。在笔记库、文档文件夹或任何 markdown 文件集合中运行它，以搜索、编辑和重组内容，就像处理代码一样。

`.claude/` 目录和 `CLAUDE.md` 与其他工具的配置目录并存，不会冲突。Claude 在每次工具调用时都会重新读取文件，因此在下次读取该文件时会看到您在另一个应用程序中进行的编辑。

***

### 使用图像

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

<Steps>
  <Step title="向对话中添加图像">
    您可以使用以下任何方法：

    1. 将图像拖放到 Claude Code 窗口中
    2. 复制图像并使用 ctrl+v 粘贴到 CLI 中（不要使用 cmd+v）
    3. 向 Claude 提供图像路径。例如，"Analyze this image: /path/to/your/image.png"
  </Step>

  <Step title="让 Claude 分析图像">
    ```text theme={null}
    What does this image show?
    ```

    ```text theme={null}
    Describe the UI elements in this screenshot
    ```

    ```text theme={null}
    Are there any problematic elements in this diagram?
    ```
  </Step>

  <Step title="使用图像作为上下文">
    ```text theme={null}
    Here's a screenshot of the error. What's causing it?
    ```

    ```text theme={null}
    This is our current database schema. How should we modify it for the new feature?
    ```
  </Step>

  <Step title="从视觉内容获取代码建议">
    ```text theme={null}
    Generate CSS to match this design mockup
    ```

    ```text theme={null}
    What HTML structure would recreate this component?
    ```
  </Step>
</Steps>

<Tip>
  提示：

  * 当文本描述不清楚或繁琐时使用图像
  * 包含错误截图、UI 设计或图表以获得更好的上下文
  * 您可以在对话中使用多个图像
  * 图像分析适用于图表、截图、模型等
  * 当 Claude 引用图像（例如 `[Image #1]`）时，在 Mac 上 `Cmd+Click` 或在 Windows/Linux 上 `Ctrl+Click` 链接以在默认查看器中打开图像
</Tip>

***

### 引用文件和目录

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

<Steps>
  <Step title="引用单个文件">
    ```text theme={null}
    Explain the logic in @src/utils/auth.js
    ```

    这会将文件的完整内容包含在对话中。
  </Step>

  <Step title="引用目录">
    ```text theme={null}
    What's the structure of @src/components?
    ```

    这会提供带有文件信息的目录列表。
  </Step>

  <Step title="引用 MCP 资源">
    ```text theme={null}
    Show me the data from @github:repos/owner/repo/issues
    ```

    这会使用 @server:resource 格式从连接的 MCP 服务器获取数据。详情请参阅 [MCP 资源](/en/mcp#use-mcp-resources)。
  </Step>
</Steps>

<Tip>
  提示：

  * 文件路径可以是相对路径或绝对路径
  * @ 文件引用会将文件所在目录和父目录中的 `CLAUDE.md` 添加到上下文中
  * 目录引用显示文件列表，而不是内容
  * 您可以在一条消息中引用多个文件（例如，"@file1.js and @file2.js"）
</Tip>

***

### 定时运行 Claude

假设您希望 Claude 自动定期处理任务，例如每天早上审查打开的 PR、每周审计依赖项或在夜间检查 CI 失败。

根据您希望任务运行的位置选择调度选项：

| 选项                                                 | 运行位置                     | 最适合                                                                                                                                                                                                 |
| :----------------------------------------------------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Routines](/en/routines)                               | Anthropic 托管的基础设施  | 即使计算机关闭也应该运行的任务。除了调度外，还可以通过 API 调用或 GitHub 事件触发。在 [claude.ai/code/routines](https://claude.ai/code/routines) 配置。 |
| [桌面定时任务](/en/desktop-scheduled-tasks) | 您的机器，通过桌面应用 | 需要直接访问本地文件、工具或未提交更改的任务。                                                                                                                             |
| [GitHub Actions](/en/github-actions)                   | 您的 CI 管道                  | 与仓库事件（如打开的 PR）绑定的任务，或应与工作流配置并存的 cron 调度。                                                                                            |
| [`/loop`](/en/scheduled-tasks)                         | 当前 CLI 会话           | 会话打开时的快速轮询。任务在您开始新对话时停止；`--resume` 和 `--continue` 可恢复未过期的任务。                                                                 |

<Tip>
  为定时任务编写提示时，请明确说明成功的样子以及如何处理结果。任务自主运行，因此无法提出澄清问题。例如："Review open PRs labeled `needs-review`, leave inline comments on any issues, and post a summary in the `#eng-reviews` Slack channel."
</Tip>

***

### 询问 Claude 关于其功能

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

#### 示例问题

```text theme={null}
can Claude Code create pull requests?
```

```text theme={null}
how does Claude Code handle permissions?
```

```text theme={null}
what skills are available?
```

```text theme={null}
how do I use MCP with Claude Code?
```

```text theme={null}
how do I configure Claude Code for Amazon Bedrock?
```

```text theme={null}
what are the limitations of Claude Code?
```

<Note>
  Claude 提供基于文档的答案来回答这些问题。要获得实际操作演示，请运行 `/powerup` 进行带有动画演示的交互式课程，或参考上面的特定工作流部分。
</Note>

<Tip>
  提示：

  * Claude 始终可以访问最新的 Claude Code 文档，无论您使用的版本如何
  * 提出具体问题以获得详细答案
  * Claude 可以解释复杂功能，如 MCP 集成、企业配置和高级工作流
</Tip>

***

## 恢复之前的对话

当任务跨多个会话时，从您上次停下的地方继续，而不是重新解释上下文。Claude Code 在本地保存每个对话。

```bash theme={null}
claude --continue
```

这会恢复当前目录中的最近会话；如果还没有，则打印 `No conversation found to continue` 并退出。使用 `claude --resume` 从列表中选择，或在运行中的会话中使用 `/resume`。有关命名、分支和完整选择器参考，请参阅[管理会话](/en/sessions)。

## 使用工作树运行并行会话

在一个终端中处理功能，同时 Claude 在另一个终端中修复 bug，而不会导致编辑冲突。每个工作树是其自己分支上的单独检出。

```bash theme={null}
claude --worktree feature-auth
```

在第二个终端中使用不同的名称运行相同的命令以启动隔离的并行会话。有关清理、`.worktreeinclude` 和非 git VCS 支持，请参阅[工作树](/en/worktrees)。要从一个屏幕而不是单独的终端监视并行会话，请参阅[后台代理](/en/agent-view)。

## 编辑前先规划

对于您想在写入磁盘之前审查的更改，请切换到计划模式。Claude 读取文件并提出计划，但在您批准之前不进行任何编辑。

```bash theme={null}
claude --permission-mode plan
```

您也可以在会话中按 `Shift+Tab` 切换到计划模式。有关审批流程和在文本编辑器中编辑计划，请参阅[计划模式](/en/permission-modes#analyze-before-you-edit-with-plan-mode)。

## 将研究委派给子代理

探索大型代码库会用文件读取填满您的上下文。委派探索工作，只返回结果。

```text theme={null}
use a subagent to investigate how our auth system handles token refresh
```

子代理在其自己的上下文窗口中读取文件并报告摘要。有关定义具有自己工具和提示的自定义代理，请参阅[子代理](/en/sub-agents)。

## 将 Claude 管道到脚本中

为 CI、pre-commit 钩子或批处理非交互式运行 Claude。Stdin 和 stdout 像任何 Unix 工具一样工作。

```bash theme={null}
git log --oneline -20 | claude -p "summarize these recent commits"
```

有关输出格式、权限标志和扇出模式，请参阅[非交互模式](/en/headless)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="最佳实践" icon="lightbulb" href="/en/best-practices">
    充分利用 Claude Code 的模式
  </Card>

  <Card title="管理会话" icon="rotate-left" href="/en/sessions">
    恢复、命名和分支对话
  </Card>

  <Card title="工作树" icon="code-branch" href="/en/worktrees">
    运行隔离的并行会话
  </Card>

  <Card title="扩展 Claude Code" icon="puzzle-piece" href="/en/features-overview">
    添加技能、钩子、MCP、子代理和插件
  </Card>
</CardGroup>