推荐语

Claude Code官方文档精华版，手把手教你从代码理解到重构的全流程指南。

核心内容：
1. 快速掌握新代码库的4步操作法
2. 错误修复的精准定位三板斧
3. 代码重构的现代化改造方案

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

嗨，朋友你好，我是诗康妈咪，致力于探索如何把AI应用于普通人生活的方方面面。 今天继续学习Claude Code的使用方式，文章内容来源就是Cladue官方提供的文档，做了全文的翻译。

常见工作流程

了解使用 Claude Code 的常见工作流程。

本文档中的每个任务都包含清晰的说明、示例命令和最佳实践，帮助您充分利用 Claude Code。

一、理解新代码库

1.1 获取代码库快速概览

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

步骤 1: 导航到项目根目录

cd /path/to/project

步骤 2: 启动 Claude Code

claude

步骤 3: 请求高层次概览

> 给我这个代码库的概览

步骤 4: 深入了解特定组件

> 解释这里使用的主要架构模式

> 关键的数据模型有哪些？

> 身份验证是如何处理的？

💡 提示

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

1.2 查找相关代码

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

步骤 1: 让 Claude 查找相关文件

> 找到处理用户身份验证的文件

步骤 2: 了解组件如何交互的上下文

> 这些身份验证文件是如何协同工作的？

步骤 3: 理解执行流程

> 追踪从前端到数据库的登录过程

💡 提示

• 对您要查找的内容要具体
• 使用项目中的领域语言

二、高效修复错误

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

步骤 1: 与 Claude 分享错误

> 我在运行 npm test 时看到一个错误

步骤 2: 请求修复建议

> 建议几种修复 user.ts 中 @ts-ignore 的方法

步骤 3: 应用修复

> 更新 user.ts 以添加您建议的空值检查

💡 提示

• 告诉 Claude 重现问题的命令并获取堆栈跟踪
• 提及重现错误的任何步骤
• 让 Claude 知道错误是间歇性的还是一致的

三、重构代码

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

步骤 1: 识别需要重构的遗留代码

> 在我们的代码库中查找已弃用的 API 使用

步骤 2: 获取重构建议

> 建议如何重构 utils.js 以使用现代 JavaScript 特性

步骤 3: 安全地应用更改

> 重构 utils.js 以使用 ES2024 特性，同时保持相同的行为

步骤 4: 验证重构

> 为重构的代码运行测试

💡 提示

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

四、使用专门的子代理

假设您想使用专门的 AI 子代理来更有效地处理特定任务。

步骤 1: 查看可用的子代理

> /Agents

这显示所有可用的子代理并让您创建新的子代理。

步骤 2: 自动使用子代理

Claude Code 将自动将适当的任务委托给专门的子代理：

> 审查我最近的代码更改是否存在安全问题

> 运行所有测试并修复任何失败

步骤 3: 明确请求特定子代理

> 使用 code-reviewer 子代理检查认证模块

> 让 debugger 子代理调查用户无法登录的原因

步骤 4: 为您的工作流程创建自定义子代理

> /agents

然后选择"Create New subagent"并按照提示定义：

• 子代理类型（例如，api-designer、performance-optimizer）
• 何时使用它
• 它可以访问哪些工具
• 其专门的系统提示

💡 提示

• 在 .claude/agents/ 中创建项目特定的子代理以供团队共享
• 使用描述性的 description 字段来启用自动委托
• 将工具访问限制为每个子代理实际需要的内容
• 查看
  子代理文档获取详细示例

五、处理测试

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

步骤 1: 识别未测试的代码

> 查找 NotificationsService.swift 中未被测试覆盖的函数

步骤 2: 生成测试脚手架

> 为通知服务添加测试

步骤 3: 添加有意义的测试用例

> 为通知服务的边缘条件添加测试用例

步骤 4: 运行并验证测试

> 运行新测试并修复任何失败

💡 提示

• 请求涵盖边缘情况和错误条件的测试
• 在适当时请求单元测试和集成测试
• 让 Claude 解释测试策略

六、创建拉取请求

假设您需要为您的更改创建一个文档完善的拉取请求。

步骤 1: 总结您的更改

> 总结我对认证模块所做的更改

步骤 2: 使用 Claude 生成 PR

> 创建一个 pr

步骤 3: 审查和完善

> 在 PR 描述中添加更多关于安全改进的上下文

步骤 4: 添加测试详情

> 添加关于这些更改如何测试的信息

💡 提示

• 直接让 Claude 为您创建 PR
• 在提交之前审查 Claude 生成的 PR
• 让 Claude 突出显示潜在的风险或考虑因素

七、处理文档

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

步骤 1: 识别未文档化的代码

> 查找认证模块中没有适当 JSDoc 注释的函数

步骤 2: 生成文档

> 为 auth.js 中未文档化的函数添加 JSDoc 注释

步骤 3: 审查和增强

> 改进生成的文档，添加更多上下文和示例

步骤 4: 验证文档

> 检查文档是否遵循我们的项目标准

💡 提示

• 指定您想要的文档样式（JSDoc、docstrings 等）
• 在文档中请求示例
• 为公共 API、接口和复杂逻辑请求文档

八、处理图像

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

步骤 1: 向对话添加图像

您可以使用以下任何方法：

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

步骤 2: 让 Claude 分析图像

> 这张图像显示了什么？

> 描述这个截图中的 UI 元素

> 这个图表中是否有任何有问题的元素？

步骤 3: 使用图像作为上下文

> 这是错误的截图。是什么导致的？

> 这是我们当前的数据库架构。我们应该如何为新功能修改它？

步骤 4: 从视觉内容获取代码建议

> 生成与此设计原型匹配的 CSS

> 什么 HTML 结构可以重新创建这个组件？

💡 提示

• 当文本描述不清楚或繁琐时使用图像
• 包含错误截图、UI 设计或图表以获得更好的上下文
• 您可以在对话中处理多个图像
• 图像分析适用于图表、截图、模型等

九、引用文件和目录

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

步骤 1: 引用单个文件

> 解释 @src/utils/auth.js 中的逻辑

这将文件的完整内容包含在对话中。

步骤 2: 引用目录

> @src/components 的结构是什么？

这提供了带有文件信息的目录列表。

步骤 3: 引用 MCP 资源

> 显示来自 @github:repos/owner/repo/issues 的数据

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

💡 提示

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

十、使用扩展思考

假设您正在处理复杂的架构决策、具有挑战性的错误或需要深度推理的多步骤实现规划。

步骤 1: 提供上下文并让 Claude 思考

> 我需要为我们的 API 实现一个使用 OAuth2 的新认证系统。深入思考在我们的代码库中实现这个的最佳方法。

Claude 将从您的代码库收集相关信息并使用扩展思考，这将在界面中可见。

步骤 2: 通过后续提示完善思考

> 思考这种方法中的潜在安全漏洞

> 更深入地思考我们应该处理的边缘情况

💡 提示

从扩展思考中获得最大价值的提示：

扩展思考对复杂任务最有价值，例如：

• 规划复杂的架构更改
• 调试复杂问题
• 为新功能创建实施计划
• 理解复杂的代码库
• 评估不同方法之间的权衡

您提示思考的方式会导致不同程度的思考深度：

• "think" 触发基本扩展思考
• 强化短语如 "think more"、"think a lot"、"think harder" 或 "think longer" 触发更深层的思考

有关更多扩展思考提示技巧，请参见扩展思考技巧。

注意 Claude 将在响应上方以斜体灰色文本显示其思考过程。

十一、恢复之前的对话

假设您一直在使用 Claude Code 处理任务，需要在稍后的会话中从中断的地方继续。

Claude Code 提供两个恢复之前对话的选项：

• --continue 自动继续最近的对话
• --resume 显示对话选择器

步骤 1: 继续最近的对话

claude --continue

这立即恢复您最近的对话，无需任何提示。

步骤 2: 在非交互模式下继续

claude --continue --print "继续我的任务"

使用 --print 与 --continue 在非交互模式下恢复最近的对话，非常适合脚本或自动化。

步骤 3: 显示对话选择器

claude --resume

这显示一个交互式对话选择器，显示：

• 对话开始时间
• 初始提示或对话摘要
• 消息计数

使用箭头键导航并按 Enter 选择对话。

💡 提示

• 对话历史存储在您的机器本地
• 使用 --continue 快速访问您最近的对话
• 当您需要选择特定的过去对话时使用 --resume
• 恢复时，您将在继续之前看到整个对话历史
• 恢复的对话以与原始对话相同的模型和配置开始

工作原理：

1. 对话存储：所有对话都自动保存在本地，包含完整的消息历史
2. 消息反序列化：恢复时，整个消息历史被恢复以保持上下文
3. 工具状态：之前对话中的工具使用和结果被保留
4. 上下文恢复：对话恢复时保持所有之前的上下文完整

示例：

# 继续最近的对话
claude --continue

# 使用特定提示继续最近的对话
claude --continue --print "显示我们的进度"

# 显示对话选择器
claude --resume

# 在非交互模式下继续最近的对话
claude --continue --print "再次运行测试"

十二、使用 Git 工作树运行并行 Claude Code 会话

假设您需要同时处理多个任务，并在 Claude Code 实例之间完全隔离代码。

步骤 1: 了解 Git 工作树

Git 工作树允许您将同一存储库的多个分支检出到单独的目录中。每个工作树都有自己的工作目录和隔离的文件，同时共享相同的 Git 历史。在官方 Git 工作树文档中了解更多。

步骤 2: 创建新的工作树

# 使用新分支创建新工作树
git worktree add../project-feature-a -b feature-a

# 或使用现有分支创建工作树
git worktree add../project-bugfix bugfix-123

这创建一个新目录，其中包含存储库的单独工作副本。

步骤 3: 在每个工作树中运行 Claude Code

# 导航到您的工作树
cd../project-feature-a

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

步骤 4: 在另一个工作树中运行 Claude

cd../project-bugfix
claude

步骤 5: 管理您的工作树

# 列出所有工作树
git worktree list

# 完成后删除工作树
git worktree remove ../project-feature-a

💡 提示

• 每个工作树都有自己独立的文件状态，非常适合并行 Claude Code 会话
• 在一个工作树中所做的更改不会影响其他工作树，防止 Claude 实例相互干扰
• 所有工作树共享相同的 Git 历史和远程连接
• 对于长时间运行的任务，您可以让 Claude 在一个工作树中工作，同时在另一个工作树中继续开发
• 使用描述性目录名称轻松识别每个工作树用于哪个任务
• 记住根据项目的设置在每个新工作树中初始化您的开发环境。根据您的技术栈，这可能包括：
• JavaScript 项目：运行依赖项安装（npm install、yarn）
• Python 项目：设置虚拟环境或使用包管理器安装
• 其他语言：遵循您项目的标准设置过程

十三、将 Claude 用作 unix 风格的实用程序

13.1 将 Claude 添加到您的验证过程

假设您想将 Claude Code 用作 linter 或代码审查器。

将 Claude 添加到您的构建脚本：

// package.json
{
    ...
"scripts":{
        ...
"lint:claude":"claude -p '你是一个 linter。请查看与 main 的更改并报告任何与拼写错误相关的问题。在一行中报告文件名和行号，在第二行中描述问题。不要返回任何其他文本。'"
}
}

💡 提示

• 在您的 CI/CD 管道中使用 Claude 进行自动化代码审查
• 自定义提示以检查与您的项目相关的特定问题
• 考虑为不同类型的验证创建多个脚本

13.2 管道输入，管道输出

假设您想将数据管道输入 Claude，并以结构化格式获取数据。

通过 Claude 管道数据：

cat build-error.txt | claude -p '简洁地解释这个构建错误的根本原因'> output.txt

💡 提示

• 使用管道将 Claude 集成到现有的 shell 脚本中
• 与其他 Unix 工具结合使用以实现强大的工作流程
• 考虑使用 --output-format 进行结构化输出

13.3 控制输出格式

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

步骤 1: 使用文本格式（默认）

cat data.txt | claude -p '总结这些数据' --output-format text > summary.txt

这只输出 Claude 的纯文本响应（默认行为）。

步骤 2: 使用 JSON 格式

cat code.py | claude -p '分析这段代码的错误' --output-format json > analysis.json

这输出一个包含元数据（包括成本和持续时间）的消息 JSON 数组。

步骤 3: 使用流式 JSON 格式

cat log.txt | claude -p '解析这个日志文件的错误' --output-format stream-json

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

💡 提示

• 对于只需要 Claude 响应的简单集成，使用 --output-format text
• 当您需要完整的对话日志时，使用 --output-format json
• 对于每个对话轮次的实时输出，使用 --output-format stream-json

十四、创建自定义斜杠命令

Claude Code 支持自定义斜杠命令，您可以创建这些命令来快速执行特定提示或任务。

有关更多详情，请参见斜杠命令参考页面。

14.1 创建项目特定的命令

假设您想为项目创建可重用的斜杠命令，所有团队成员都可以使用。

步骤 1: 在项目中创建命令目录

mkdir -p .claude/commands

步骤 2: 为每个命令创建 Markdown 文件

echo"分析这段代码的性能并建议三个具体的优化："> .claude/commands/optimize.md 

步骤 3: 在 Claude Code 中使用您的自定义命令

> /optimize 

💡 提示

• 命令名称来自文件名（例如，optimize.md 变成 /optimize）
• 您可以在子目录中组织命令（例如，.claude/commands/frontend/component.md 创建 /component，描述中显示"(project:frontend)"）
• 项目命令对克隆存储库的每个人都可用
• Markdown 文件内容成为调用命令时发送给 Claude 的提示

14.2 使用 $ARGUMENTS 添加命令参数

假设您想创建可以接受用户额外输入的灵活斜杠命令。

步骤 1: 使用 $ARGUMENTS 占位符创建命令文件

echo"查找和修复问题 #$ARGUMENTS。按照以下步骤：1. 理解票据中描述的问题 2. 在我们的代码库中定位相关代码 3. 实现解决根本原因的方案 4. 添加适当的测试 5. 准备简洁的 PR 描述"> .claude/commands/fix-issue.md 

步骤 2: 使用带有问题编号的命令

在您的 Claude 会话中，使用带有参数的命令。

> /fix-issue 123 

这将在提示中将 $ARGUMENTS 替换为"123"。

💡 提示

• $ARGUMENTS 占位符会被命令后面的任何文本替换
• 您可以在命令模板中的任何位置放置 $ARGUMENTS
• 其他有用的应用：为特定函数生成测试用例、为组件创建文档、审查特定文件中的代码，或将内容翻译为指定语言

14.3 创建个人斜杠命令

假设您想创建在所有项目中都有效的个人斜杠命令。

步骤 1: 在主文件夹中创建命令目录

mkdir -p ~/.claude/commands 

步骤 2: 为每个命令创建 Markdown 文件

echo"审查这段代码的安全漏洞，重点关注："> ~/.claude/commands/security-review.md 

步骤 3: 使用您的个人自定义命令

> /security-review 

💡 提示

• 个人命令在使用 /help 列出时在其描述中显示"(user)"
• 个人命令只对您可用，不与您的团队共享
• 个人命令在您的所有项目中都有效
• 您可以将这些用于跨不同代码库的一致工作流程

十五、询问 Claude 关于其功能

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

示例问题

> Claude Code 可以创建拉取请求吗？

> Claude Code 如何处理权限？

> 有哪些斜杠命令可用？

> 如何在 Claude Code 中使用 MCP？

> 如何为 Amazon Bedrock 配置 Claude Code？

> Claude Code 有哪些限制？

注意 Claude 为这些问题提供基于文档的答案。对于可执行示例和实际演示，请参考上面的特定工作流程部分。

💡 提示

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