作为一个长期深度使用Claude Code的开发者，我逐渐意识到这个工具的价值并不在于单一的功能，而在于如何将各种工作流程有机整合，形成一套高效的开发模式。

从接手陌生项目的代码库快速理解，到复杂的代码重构、测试覆盖，再到最终的代码审查和自动化集成，每个环节都有其特定的最佳实践。

本文档汇总了我在实际使用中验证过的常见工作流程，帮助开发者们避免摸索，直接获得事半功倍的效果。

第一部分：代码库理解与探索

1.1 快速获取新代码库概览

场景：刚加入新项目，需要在最短时间内了解其整体架构和核心概念。

执行步骤：

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?

最佳实践：

• 从广泛的架构问题开始，逐步缩小到具体组件
• 请求项目中使用的编码约定和命名规范
• 要求Claude生成一份领域术语词汇表，加速后续沟通

1.2 精准定位相关代码

场景：需要找到与特定功能相关的所有代码文件。

执行步骤：

1. 明确指定查找目标：> 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

最佳实践：

• 使用项目中的具体领域术语表述问题，而不是模糊的通用词汇
• 逐层追踪数据流向，理解组件间的依赖关系
• 记录关键的文件路径和函数入口点，便于后续参考

---

第二部分：代码修复与调试

2.1 高效修复错误

场景：遇到编译或运行时错误，需要快速定位并修复。

执行步骤：

1. 分享完整的错误信息和堆栈跟踪：> I'm seeing an error when I run npm test [粘贴完整错误输出]
2. 获取修复建议：> suggest a few ways to fix the @ts-ignore in user.ts
3. 由Claude执行修复：> update user.ts to add the null check you suggested
4. 验证修复效果：重新运行失败的测试或命令

最佳实践：

• 提供重现问题的完整命令步骤
• 告知Claude错误是否为间歇性（偶发）或持续性（每次都发生）
• 分享相关的环境信息（Node版本、依赖版本等），如错误与环境相关

---

第三部分：代码现代化与重构

3.1 安全的代码重构流程

场景：需要将旧代码库升级到现代标准（如ES2024、TypeScript 5.0等）。

执行步骤：

1. 识别需要重构的遗留代码：> find deprecated API usage in our codebase
2. 获取现代化建议：> suggest how to refactor utils.js to use modern JavaScript features
3. 执行重构并验证行为：> refactor utils.js to use ES2024 features while maintaining the same behavior
4. 运行测试确保完整性：> run tests for the refactored code

最佳实践：

• 要求Claude详细解释现代方法相比旧模式的优势（性能、可维护性、安全性等）
• 在重构大型代码块时，分批小幅改动并及时测试，而非一次性全量修改
• 在涉及公共API时保持向后兼容性，通过deprecation warnings引导用户迁移

---

第四部分：专业工具与工作流优化

4.1 使用专门化的子代理

概念：Claude Code提供了子代理（subagent）功能，可针对特定任务创建专业化的AI助手。

基本用法：

1. 查看所有可用子代理：> /agents
2. 自动委派任务（Claude自动选择合适的子代理）：
   • > 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
   • > have the debugger subagent investigate why users can't log in

创建自定义子代理：

1. 运行> /agents，选择"Create New subagent"
2. 定义以下配置项：
   • 唯一标识符（如code-reviewer、api-designer）
   • 激活时机：Claude何时应自动使用此代理
   • 工具权限：指定代理可访问的工具集合
   • 系统提示：描述代理的角色、目标和行为规范
3. 将自定义子代理存储在.claude/agents/目录中，团队成员可共享使用

最佳实践：

• 使用描述性的description字段，使Claude能够自动选择合适的子代理
• 最小化子代理的工具权限范围，仅授予必需的权限
• 为安全审查、性能优化、文档生成等常见任务创建专用代理

4.2 计划模式：安全的代码分析

概念：计划模式指示Claude通过只读操作分析代码，不进行任何修改。这对于探索复杂项目、规划大型重构或安全审查特别有价值。

使用场景：

• 多步骤功能实现：在修改前制定详细计划
• 代码库深度探索：研究现有实现而不改变代码
• 交互式开发：与Claude迭代讨论方案，最后再执行修改

启用方式：

• 临时切换：在活跃会话中按Shift+Tab循环切换权限模式（显示⏸ plan mode on）
• 启动新会话：claude --permission-mode plan
• 无头查询：claude --permission-mode plan -p "Analyze the authentication system and suggest improvements"
• 全局默认：在~/.claude/settings.json中配置：

  {
    "permissions": {
      "defaultMode": "plan"
    }
  }

实战案例：规划OAuth2迁移

claude --permission-mode plan
> I need to refactor our authentication system to use OAuth2. Create a detailed migration plan.
> What about backward compatibility?
> How should we handle database migration?

Claude会在计划模式下分析现有实现并生成全面的迁移方案，而不修改任何代码。

4.3 扩展思考（Extended Thinking）：深度推理

概念：扩展思考为Claude保留部分输出令牌预算，用于逐步推理复杂问题，在详细模式中可见。

适用场景：

• 复杂的架构设计决策
• 具有挑战性的调试问题
• 多步骤实现规划
• 评估不同技术方案的权衡

启用方式：

• 快捷键切换：按Option+T（macOS）或Alt+T（Windows/Linux）
• 单次请求：在提示中包含ultrathink关键字

  > ultrathink: design a caching layer for our API

• 全局配置：通过/config命令设置默认开启
• 环境变量控制：export MAX_THINKING_TOKENS=1024

令牌预算说明：

• 思考启用时，Claude最多可使用31,999个令牌进行内部推理
• 自定义MAX_THINKING_TOKENS环境变量会覆盖默认预算
• 所有使用的思考令牌都会产生费用
• 按Ctrl+O切换详细模式，查看Claude的推理过程（显示为灰色斜体）

---

第五部分：测试与质量保证

5.1 系统化的测试覆盖工作流

场景：为现有代码库添加测试覆盖，包括单元测试和边界情况测试。

执行步骤：

1. 识别未测试的代码：> find functions in NotificationsService.swift that are not covered by tests
2. 生成测试框架：> add tests for the notification service
3. 添加边界情况测试：> add test cases for edge conditions in the notification service
4. 运行并验证：> run the new tests and fix any failures

最佳实践：

• Claude会自动分析你的现有测试文件，匹配项目的测试框架和断言风格
• 在请求测试时指定验证的具体行为，而不仅仅是"增加测试"
• 要求Claude识别容易遗漏的边界情况：
  • 错误条件和异常处理
  • 边界值（NULL、空集合、最大值等）
  • 并发和竞态条件
  • 意外输入类型
• 对关键路径和公共API优先进行测试覆盖

---

第六部分：代码管理与文档

6.1 创建高质量的拉取请求

场景：为代码变更生成规范、清晰的PR描述和变更摘要。

执行步骤：

1. 总结你的变更：> summarize the changes I've made to the authentication module
2. 由Claude生成PR：> create a pr
3. 增强PR描述：> enhance the PR description with more context about the security improvements
4. 添加测试信息：> add information about how these changes were tested

最佳实践：

• 直接要求Claude为你生成完整的PR，而不仅仅是描述
• 在提交前审查Claude生成的内容，确保准确性和适当性
• 要求Claude突出潜在的风险或需要注意的事项
• 包含以下信息：
  • 变更的动机和背景
  • 实现的关键决策
  • 测试覆盖范围和验证方法
  • 向后兼容性影响
  • 已知限制或未来改进方向

6.2 文档生成与维护

场景：为代码添加或更新文档注释。

执行步骤：

1. 识别缺少文档的代码：> find functions without proper JSDoc comments in the auth module
2. 生成文档：> add JSDoc comments to the undocumented functions in auth.js
3. 增强文档内容：> improve the generated documentation with more context and examples
4. 验证符合标准：> check if the documentation follows our project standards

最佳实践：

• 指定文档风格：JSDoc、Docstrings、Javadoc等，Claude会自动匹配项目风格
• 优先记录：
  • 公共API和导出函数
  • 复杂的业务逻辑
  • 系统接口和关键类
  • 非显而易见的参数和返回值
• 请求代码示例，特别是对于通用库函数

---

第七部分：高级集成与自动化

7.1 使用图像进行可视化分析

场景：通过截图、图表或设计稿来获取Claude的建议。

添加图像的方式：

• 拖放到Claude Code窗口
• 复制图像并用Ctrl+V（Windows/Linux）或Cmd+V（Mac）粘贴
• 提供图像路径：> Analyze this image: /path/to/your/image.png

应用案例：

> Here's a screenshot of the error. What's causing it?
> This is our database schema diagram. How should we modify it for the new feature?
> Generate CSS to match this design mockup
> What HTML structure would recreate this UI component?

最佳实践：

• 当文字描述过于冗长或不够清晰时，使用图像
• 包含错误堆栈跟踪的截图以获得更好的上下文
• 提供数据库模式图、架构图等复杂结构的可视化
• 在一个对话中可使用多个图像进行对比分析
• 当Claude引用图像时（如[Image #1]），按Cmd+Click（Mac）或Ctrl+Click（Windows/Linux）在默认查看器中打开

7.2 使用@符号引用文件和目录

概念：快速将文件或目录内容包含在对话中，无需等待Claude逐一读取。

使用方式：

> Explain the logic in @src/utils/auth.js
> What's the structure of @src/components?
> Show me the data from @github:repos/owner/repo/issues

特性说明：

• 单个文件引用@file.js：包含文件的完整内容
• 目录引用@directory：提供目录列表而非内容（更高效）
• MCP资源：使用@server:resource格式从连接的MCP服务器获取数据
• 在CLAUDE.md中定义的上下文会自动添加
• 支持相对路径和绝对路径，支持多个文件引用

7.3 将Claude集成到构建和CI/CD流程

场景：将Claude用作代码质量工具，集成到linting、测试和审查流程。

在build脚本中集成（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, security, and code style. report the filename and line number on one line, and a description of the issue on the second line.'"
  }
}

通过管道处理数据：

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

控制输出格式：

# 纯文本格式（默认）
cat data.txt | claude -p 'summarize this data' --output-format text > summary.txt

# JSON格式（包含元数据）
cat code.py | claude -p 'analyze this code for bugs' --output-format json > analysis.json

# 流式JSON（实时输出）
cat log.txt | claude -p 'parse this log file for errors' --output-format stream-json

最佳实践：

• 在CI/CD管道中使用计划模式进行自动代码审查
• 为不同的验证场景创建多个专用脚本（linting、security-check、doc-check等）
• 使用--output-format json获取结构化输出，便于工具集成
• 设置合理的超时和错误处理，防止CI流程阻塞

7.4 创建自定义斜杠命令

概念：为项目定义可重用的斜杠命令，提高团队工作效率。

创建项目特定的命令：

1. 创建命令目录：mkdir -p .claude/commands
2. 创建Markdown文件（文件名成为命令名）：

   echo "Analyze the performance of this code and suggest three specific optimizations:" > .claude/commands/optimize.md

3. 在Claude中使用：> /optimize

带参数的命令（使用$ARGUMENTS占位符）：

echo 'Find and fix issue #$ARGUMENTS. Follow these steps: 
1. Understand the issue described in the ticket 
2. Locate the relevant code in our codebase 
3. Implement a solution that addresses the root cause 
4. Add appropriate tests 
5. Prepare a concise PR description' > .claude/commands/fix-issue.md

使用：> /fix-issue 123

创建个人命令（跨项目通用）：

mkdir -p ~/.claude/commands
echo "Review this code for security vulnerabilities, focusing on..." > ~/.claude/commands/security-review.md
> /security-review

最佳实践：

• 命令名称从文件名自动生成（optimize.md → /optimize）
• 在子目录中组织相关命令（.claude/commands/frontend/component.md）
• 项目命令存储在.claude/commands/，团队所有成员可用
• 个人命令存储在~/.claude/commands/，仅自己可用，跨所有项目
• 使用描述性的文件名和$ARGUMENTS创建灵活的命令模板

---

第八部分：会话管理与并行工作流

8.1 会话的恢复与管理

场景：管理多个并行的开发任务，每个任务对应一个会话。

基本操作：

claude --continue           # 继续当前目录最近的会话
claude --resume             # 打开交互式会话选择器
claude --resume auth-refactor  # 按名称恢复指定会话

会话命名：

> /rename auth-refactor    # 给当前会话起名
> /resume                   # 打开选择器，按R可重命名任何会话

会话选择器快捷键：

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

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

• 会话名称或初始提示
• 上次活动时间
• 消息计数
• 关联的Git分支
• 使用/rewind或--fork-session创建的分叉会话，在根会话下分组显示

最佳实践：

• 尽早命名会话：开始不同任务时立即使用/rename
• 用--continue快速访问最近的会话
• 用--resume打开选择器在多个会话间浏览选择
• 按P在恢复前预览会话内容，确保是正确的会话
• 用脚本在非交互模式中恢复会话：claude --continue --print "prompt"

8.2 使用Git工作树进行并行开发

概念：Git工作树允许在同一仓库中检出多个分支到不同目录，每个目录都有独立的工作状态，但共享Git历史。

创建新工作树：

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

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

在每个工作树中独立运行Claude：

cd ../project-feature-a
claude

# 在另一个工作树中
cd ../project-bugfix
claude

管理工作树：

git worktree list              # 列出所有工作树
git worktree remove ../project-feature-a  # 完成后移除

最佳实践：

• 每个工作树有独立的文件状态和Claude实例，避免冲突
• 使用描述性目录名（project-feature-auth、project-bugfix-payment）
• 所有工作树共享Git历史，可无缝集成更改
• 在新工作树中初始化开发环境：
  • JavaScript：npm install
  • Python：设置虚拟环境
  • 其他：遵循项目标准流程
• 长期运行的任务可在一个工作树中进行，同时在另一个工作树继续开发

第九部分：提示与技巧

9.1 询问Claude的功能与限制

Claude可以回答自己的功能问题：

> can Claude Code create pull requests?
> how does Claude Code handle permissions?
> what slash commands are available?
> how do I use MCP with Claude Code?
> what are the limitations of Claude Code?

Claude拥有实时访问最新文档的能力，无论你使用的是哪个版本。

9.2 提出具体问题

比起模糊的问题，具体的问题能获得更详细的答案。避免泛泛而谈，给出：

• 你想解决的具体问题
• 当前的代码上下文
• 你尝试过的解决方案
• 期望的最终效果

总结

经过一段时间的深度使用和实践，我发现Claude Code的真正价值不只适用于开发，而是能够把开发能力整合成高效的工作流。

从代码库的快速理解，到精准的错误修复，再到大型重构的规划和执行，每个环节都有其对应的最佳实践。

特别值得强调的是几个关键工作流：

• 计划模式让我们能安心地探索和规划，而无需担心意外修改
• 子代理和斜杠命令将重复性任务自动化，大幅提升效率
• 会话管理和工作树使并行开发变得无缝和高效
• 扩展思考为复杂决策提供了深度的推理能力

与其被工具的功能淹没，我们应该逐步构建适合自己的工作流。

尝试不同的工作方式，积累自定义命令，训练团队采用统一的实践，这才是真正事半功倍的秘诀。