claude code 官方文档学习（2）：通用工作流与最佳实现

这篇文章我们继续对 claude code 官方文档进行学习，主要学习其通用工作流与最佳实践。

通用工作流

这一部分将涵盖各类日常开发的实用工作流，包括探索陌生代码、调试、代码重构、编写测试、创建拉取请求（PR）和会话管理。每个章节均提供可适配至个人项目的提示词示例。

快速了解新代码库

若你刚加入一个新项目，需要快速熟悉其代码结构，可按以下步骤操作：

1	cd /path/to/project

启动 Claude Code

claude

要求生成代码库高层级概览

1	> give me an overview of this codebase

深入了解特定组件

1
2
3

> explain the main architecture patterns used here
> what are the key data models?
> how is authentication handled?

一些技巧：
- 先提出宽泛的问题，再逐步聚焦具体领域
- 询问项目所使用的编码规范和设计模式
- 要求生成项目专属术语的词汇表

若你需要定位与特定功能相关的代码，可按以下步骤操作：

让 Claude 查找相关文件

1	> find the files that handle user authentication

了解组件间的交互逻辑

1	> how do these authentication files work together?

梳理代码执行流程

1	> trace the login process from front-end to database

一些技巧：
- 明确说明查找目标
- 使用项目的领域专属术语
- 为开发语言安装代码智能插件，让 Claude 可实现精准的 “跳转到定义” 和 “查找引用” 导航功能

高效修复代码漏洞

若你遇到报错信息，需要定位并修复问题根源，可按以下步骤操作：

向 Claude 反馈报错信息

1	> I'm seeing an error when I run npm test

询问修复建议

1	> suggest a few ways to fix the @ts-ignore in user.ts

应用修复方案

1	> update user.ts to add the null check you suggested

一些技巧：
- 告知 Claude 复现问题的命令，以便获取堆栈跟踪信息
- 说明复现错误的具体步骤
- 告知 Claude 该错误是偶发还是持续出现

代码重构

若你需要将旧代码升级为现代开发模式和规范，可按以下步骤操作：

定位需要重构的遗留代码

1	> find deprecated API usage in our codebase

获取重构建议

1	> suggest how to refactor utils.js to use modern JavaScript features

安全地应用代码修改

1	> refactor utils.js to use ES2024 features while maintaining the same behavior

验证重构效果

1	> run tests for the refactored code

技巧：
- 让 Claude 解释现代开发方案的优势
- 若有需要，要求代码修改保持向下兼容
- 分小步进行重构，确保每一步都可测试

使用专业 subagent

若你希望借助专业的 subagent 更高效地完成特定任务，可按以下步骤操作：

查看可用的 subagent，/agents 命令会展示所有可用的 subagent，同时支持创建新的 subagent

> /agents

Claude Code 会自动将合适的任务委派给专业 subagent

1 2	> review my recent code changes for security issues > run all tests and fix any failures

显式调用指定 subagent

1 2	> use the code-reviewer subagent to check the auth module > have the debugger subagent investigate why users can't log in

通过 /agents 为个人工作流创建自定义 subagent。执行命令后选择 Create New subagent（创建新子代理），并按照提示定义以下内容：
- 描述 subagent 用途的唯一标识（例如 code-reviewer 代码审查、api-designer 接口设计）
- Claude 调用该 subagent 的触发场景
- subagent 可访问的工具
- 描述 subagent 角色和行为的系统提示词
技巧：
- 在项目目录 .claude/agents/ 下创建项目专属子，方便团队共享
- 为 subgagent 编写详尽的描述信息，实现任务的自动委派
- 为每个 subagent 配置最小必要的工具访问权限

启用规划模式实现安全的代码分析

规划模式（Plan Mode）会让 Claude 仅通过只读操作分析代码库并制定执行计划，非常适合探索代码库、规划复杂的代码修改或安全地进行代码审查。在规划模式下，Claude 会先通过 AskUserQuestion 工具收集需求、明确开发目标，再制定执行计划。

规划模式的适用场景：

多步骤功能开发：当新功能需要修改多个文件时
代码库探索：希望在修改代码前全面研究代码库时
交互式开发：希望与 Claude 协作迭代开发方向时

规划模式的使用方法：可通过快捷键 Shift+Tab 切换权限模式，在会话中开启规划模式：

若当前为普通模式，首次按 Shift+Tab 会切换至 自动接受模式，终端底部会显示 ⏵⏵ accept edits on
再次按 Shift+Tab，即可切换至规划模式，终端底部会显示 ⏸ plan mode on

使用 --permission-mode plan 参数，启动新会话时直接进入规划模式：

1	claude --permission-mode plan

也可使用 -p 参数，直接以规划模式执行查询（即无界面模式）：

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

在配置文件中添加以下内容，将规划模式设为默认模式：

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

在 Cluade Code 生成计划后，可以通过 Ctrl+G 在默认文本编辑器中打开该计划，也可以在 Claude 执行前直接编辑。

测试操作

若你需要为未覆盖测试的代码编写测试用例，可按以下步骤操作：

定位未测试的代码

1	> find functions in NotificationsService.swift that are not covered by tests

生成测试框架代码

1	> add tests for the notification service

补充有实际意义的测试用例

1	> add test cases for edge conditions in the notification service

运行并验证测试用例

1	> run the new tests and fix any failures

Claude 可根据项目现有模式和规范生成测试代码。请求生成测试代码时，需明确说明要验证的代码行为，Claude 会分析项目现有测试文件，匹配其中的编码风格、测试框架和断言模式。

如需实现全面的测试覆盖，可让 Claude 找出你可能忽略的边界场景。Claude 能分析代码执行路径，并为易被忽略的错误场景、边界值和异常输入推荐对应的测试用例。

创建拉取请求（PR）

你可直接让 Claude 创建 PR（例如输入create a pr for my changes），也可使用 /commit-push-pr 命令，一键完成代码提交、推送和创建 PR：

1	> /commit-push-pr

若你已配置 Slack MCP 服务器，并在项目的 CLAUDE.md 文件中指定了通知频道（例如 post PR URLs to #team-prs），该命令会自动将拉取请求的链接发送至指定频道。

如需更精细地控制流程，可分步引导 Claude 操作，或自定义命令：

总结代码修改内容

1	> summarize the changes I've made to the authentication module

生成拉取请求

1	create a pr

审核并优化 PR

1	> enhance the PR description with more context about the security improvements

使用 gh pr create 命令创建拉取请求后，当前会话会自动与该 PR 关联，后续可通过 claude --from-pr <number> 恢复会话并继续操作。

提交前请审核 Claude 生成的 PR，也可让 Claude 重点标注潜在的风险和注意事项。

处理文档

若你需要为代码添加或更新文档，可按以下步骤进行：

定位未编写文档的代码

1	> find functions without proper JSDoc comments in the auth module

生成文档内容

1	> add JSDoc comments to the undocumented functions in auth.js

审查并优化文档

1	> improve the generated documentation with more context and examples

验证文档合规性

1	> check if the documentation follows our project standards

技巧：
- 明确指定所需的文档格式（如 JSDoc、文档字符串等）；
- 要求在文档中添加使用示例；
- 重点为公共接口、交互协议和复杂业务逻辑编写文档

处理图片

若你需要处理代码库中的图片，并希望 Claude 协助分析图片内容，可按以下步骤操作：

向对话中添加图片，可通过以下任意一种方式添加：
- 将图片拖放至 Claude Code 窗口；
- 复制图片后，在命令行界面使用 ctrl+v 粘贴（Mac 系统请勿使用 cmd+v）；
- 向 Claude 提供图片路径，例如：Analyze this image: /path/to/your/image.png。
让 Claude 分析图片

1
2
3

> What does this image show?
> Describe the UI elements in this screenshot
> Are there any problematic elements in this diagram?

以图片为上下文开展工作

1 2	> 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?

根据图片内容获取代码建议

1 2	> Generate CSS to match this design mockup > What HTML structure would recreate this component?

技巧：
- 当文字描述难以清晰表达时，优先使用图片；
- 上传报错截图、UI 设计稿或流程图，为 Claude 提供更完整的上下文；
- 可在单次对话中上传并处理多张图片；
- 图片分析功能支持流程图、截图、设计稿等多种类型；
- 当 Claude 引用图片时（例如 [Image #1]），Mac 系统按下 Cmd + 单击、Windows/Linux 系统按下 Ctrl + 单击该链接，即可在默认图片查看器中打开

引用文件和目录

使用 @ 符号可快速将文件或目录纳入对话上下文，无需等待 Claude 读取文件内容。

引用单个文件，该操作会将文件完整内容纳入对话。

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

引用目录，该操作会展示目录的文件列表及相关信息。

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

引用 MCP 资源，该操作会通过 @服务器:资源 的格式，从已连接的 MCP 服务器获取数据，详情可参阅 MCP 资源文档

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

技巧：
- 文件路径支持相对路径和绝对路径
- 使用 @ 引用文件时，该文件所在目录及上级目录中的 CLAUDE.md 文件也会被纳入上下文
- 引用目录仅会展示文件列表，不会展示文件内容
- 可在单条消息中引用多个文件（例如：@file1.js and @file2.js）

启用扩展思考模式（思考模式）

扩展思考（Extended thinking）模式为默认开启状态，该模式会让 Claude 在做出响应前，分步推理复杂问题，预留充足的思考空间。在详细模式下可查看推理过程，通过 Ctrl+O 进行开启/关闭。

此外，Opus 4.6 版本新增了自适应推理功能（adaptive reasoning）：不再使用固定的思考 token 预算，模型会根据你设置的工作力度（effort level），动态分配思考资源。扩展思考模式与自适应推理功能协同工作，让你可自主控制 Claude 做出响应前的推理深度。

扩展思考模式在以下场景中尤为实用：复杂的架构决策、疑难漏洞排查、多步骤开发实现规划，以及不同方案的权衡分析。

需要注意的是，think（思考）、think hard（深入思考）、think more（进一步思考）等表述，仅会被当作普通的提示词指令，不会额外分配思考令牌。

思考模式为默认开启状态，你可根据需求调整或关闭该模式，具体配置方式如下表：

配置范围	配置方法	详细说明
工作力度	在 `/model` 中调整或设置 `CLAUDE_CODE_EFFORT_LEVEL`	为 Opus 4.6 控制推理深度：低、中、高（默认）。详见 `调整工作力度` 文档
快捷键切换	按下 Option+T (macOS) 或 Alt+T (Windows/Linux)	为当前会话切换思考模式的开启/关闭（支持所有模型）。可能需要配置终端以启用 Option 键快捷键
全局默认设置	使用 `/config` 命令切换思考模式	为所有项目设置思考模式的默认状态（支持所有模型）。配置会保存至 `~/.claude/settings.json` 文件的 `alwaysThinkingEnabled` 字段
限制令牌预算	设置 `MAX_THINKING_TOKENS` 环境变量	将思考预算限制为指定的令牌数量（Opus 4.6 版本会忽略该设置，除非设为 0）。示例：`export MAX_THINKING_TOKENS=10000`

按下 Ctrl+O 切换至详细模式，可查看 Claude 的推理过程，推理内容会以灰色斜体文本展示。

扩展思考模式的工作原理

扩展思考模式控制 Claude 做出响应前的内部推理深度，更多的思考资源意味着 Claude 能更充分地探索解决方案、分析边界场景并自我修正错误。

Opus 4.6 版本中，思考模式采用自适应推理机制：模型会根据你选择的工作力度（低、中、高）动态分配思考令牌，这是平衡响应速度和推理深度的推荐方式
其他模型中，思考模式会从输出令牌预算中分配最高 31999 个令牌作为固定的思考预算，你可通过
MAX_THINKING_TOKENS 环境变量限制该预算，也可通过 /config 命令或 Option+T/Alt+T 快捷键彻底关闭思考模式
需要注意的是，Opus 4.6 和 Sonnet 4.6 版本会忽略 MAX_THINKING_TOKENS 环境变量，因这两个版本由自适应推理功能控制推理深度。唯一例外：将 MAX_THINKING_TOKENS 设为 0 时，所有模型都会彻底关闭思考模式。若需关闭自适应推理、恢复固定思考预算，可设置环境变量 CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

恢复之前的会话

启动 Claude Code 时，可通过以下命令恢复之前的会话：

claude --continue：恢复当前目录下最近一次的对话；
claude --resume：打开会话选择器，或通过会话名称恢复指定对话
claude --from-pr 123：恢复与指定 PR 关联的会话

在活跃的会话中，可使用 /resume 命令切换至其他对话。会话按项目目录存储，/resume 会话选择器会展示同一 Git 仓库（包括工作树）下的所有会话。

命名会话

为会话设置描述性名称，方便后续查找，这在同时处理多个任务或功能开发时是最佳实践。

为当前会话命名：在会话中使用 /rename 命令，为会话设置易记的名称：

1	> /rename auth-refactor

也可在会话选择器中重命名任意会话：执行 /resume 打开选择器，导航至目标会话并按下 Ctrl+R 键
之后就可以通过名称恢复会话

# 从命令行恢复
claude --resume auth-refactor

# 在活跃会话中恢复：
> resume auth-refactor

使用会话选择器

执行 /resume 命令（或直接执行无参数的 claude --resume），会打开交互式会话选择器，该选择器包含以下功能：

↑ / ↓ 在会话间上下导航
→ / ← 展开 / 折叠分组的会话
Enter 选中并恢复高亮的会话
还有其他快捷键，具体可以参见界面上的提示

回话选择器会展示会话的实用元数据，帮助你快速识别：

会话名称或初始提示词；
距离上次操作的时间；
消息数量；
Git 分支（如有）。

通过 /rewind 命令或 --fork-session 标志创建的分支会话，会归组在其根会话下，方便查找相关对话。

会话使用技巧：

尽早为会话命名：开始处理特定任务时，立即使用 /rename 命令，相比 explain this function（解释此函数），payment-integration（支付集成） 这类名称更易查找
快速访问最近对话：使用 --continue 命令恢复当前目录下最近一次的会话
已知会话名称时：使用 --resume session-name 直接恢复
需浏览选择时：使用无参数的 --resume 打开选择器
脚本中使用：通过 claude --continue --print "prompt" 以非交互模式恢复会话；
会话配置继承：恢复后的会话会沿用原会话的模型和配置

会话恢复的工作原理

对话存储：所有对话的完整消息历史会自动本地保存
消息反序列化：恢复会话时，会还原全部消息历史，保持上下文完整；
工具状态：保留上一次对话中的工具使用记录和执行结果；
上下文还原：恢复后的会话会保留所有先前的上下文信息。

结合 Git Worktree 并行运行多个 Claude Code 会话

同时处理多个任务时，需要为每个 Claude 会话分配独立的代码库副本，避免代码变更冲突。Git 工作树可解决该问题：它会创建独立的工作目录，每个目录拥有专属的文件和分支，同时共享同一仓库的历史记录和远程连接。这意味着你可让 Claude 在一个工作树中开发功能，同时在另一个工作树中修复漏洞，两个会话互不干扰。

启动 Claude 时使用 --worktree（简写 -w）标志创建独立的工作树，传入的参数会成为工作树目录名和分支名：

# 启动 Claude 并创建名为 "feature-auth" 的工作树
# 在 .claude/worktrees/feature-auth/ 目录下创建新分支
claude --worktree feature-auth

# 在另一个独立工作树中启动新会话
claude --worktree bugfix-123

若省略名称，Claude 会自动生成随机名称：

1 2	# 自动生成如 "bright-running-fox" 这类随机名称 claude --worktree

工作树会创建在 <repo>/.claude/worktrees/<name> 目录下，并基于默认远程分支创建新分支，分支名称为 worktree-<name>。

你也可在会话中直接让 Claude 在工作树中工作 或 创建工作树，Claude 会自动完成创建操作。

子 Agent工作树

子代理（Subagents）还可以利用工作树隔离（worktree isolation）来实现并行工作且互不冲突。你可以通过以下两种方式开启此功能：

直接对话：要求 Claude 为你的代理使用工作树（use worktrees for your agents）。
配置文件：在自定义子代理的 Frontmatter 中添加 isolation: worktree 配置

在此模式下，每个子代理都会获得一个独立的工作树；如果子代理结束工作时未产生任何更改，该工作树会被自动清理。

工作树清理 (Worktree Cleanup)

当你退出一个工作树会话时，Claude 会根据你是否进行了更改来处理清理工作：

未做出更改：该工作树及其关联分支将被自动移除
存在更改或提交（Commits）： Claude 会提示你选择保留或移除该工作树
- 保留：维持目录和分支现状，以便你稍后返回继续工作。
- 移除：删除工作树目录及其分支，同时丢弃所有未提交的更改和已有的提交。

如果你需要在 Claude 会话之外清理工作树，请使用手动工作树管理。建议将 .claude/worktrees/ 添加至项目的 .gitignore 文件，避免工作树内容在主仓库中显示为未跟踪文件。

手动管理工作树

若需要更灵活地控制工作树的存储位置和分支配置，可直接通过 Git 创建工作树，适用于需要检出特定现有分支，或将工作树放置在仓库外的场景：

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

# 创建工作树并关联现有分支
git worktree add ../project-bugfix bugfix-123

# 进入工作树并启动 Claude
cd ../project-feature-a && claude

# 完成工作后清理工作树
git worktree list
git worktree remove ../project-feature-a

请注意，需根据项目的搭建规范，在每个新工作树中初始化开发环境。根据技术栈的不同，可能需要执行依赖安装（npm install、yarn）、配置虚拟环境，或遵循项目的标准搭建流程。

非 Git 版本控制系统的适配

工作树隔离默认适用于 Git 版本控制系统。对于 SVN、Perforce、Mercurial 等其他版本控制系统，可配置WorktreeCreate 和 WorktreeRemove 钩子，自定义工作树的创建和清理逻辑。配置完成后，使用 --worktree 标志时，会用自定义逻辑替代默认的 Git 工作树行为。

配置 Claude 消息通知，及时获取关注提醒

当你启动长时间运行的任务并切换至其他窗口时，可配置桌面通知，在 Claude 完成任务或需要你介入时及时提醒。该功能基于 Notification 钩子事件实现，当 Claude 需要获取操作权限、处于空闲状态等待新提示词，或完成身份验证时，会触发该事件。

配置步骤

打开钩子菜单：输入 /hooks 命令，从事件列表中选择 Notification（通知）。
配置匹配规则
- 选择 + Match all (no filter)（匹配所有事件，不筛选），为所有通知类型触发提醒；
- 若仅需为特定事件配置提醒，选择 + Add new matcher…（添加新匹配规则），并输入以下任一匹配值
  - permission_prompt：Claude 需要你批准工具使用权限时
  - idle_prompt：Claude 完成工作，等待你的下一个提示词时
  - auth_success：身份验证完成时
  - elicitation_dialog：Claude 向你发起问题咨询时
- 添加通知命令：选择 + Add new hook…（添加新钩子），并根据操作系统输入对应的通知命令
  - 对于 Linux，使用 notify-send 命令（多数带通知守护进程的 Linux 桌面系统均预装）：
- 保存至用户设置：选择 User settings（用户设置），让该通知配置在所有项目中生效。

将 Claude 用作类 Unix 工具

若你希望将 Claude Code 用作代码检查工具或代码审查工具，可将其添加至项目的构建脚本：

// 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.'"
    }
}

将 Claude 集成至 CI/CD 流水线，实现自动化代码审查
自定义提示词，让 Claude 检查与项目相关的特定问题
可为不同类型的验证任务，创建多个对应的脚本

若你希望通过管道将数据传入 Claude，并以结构化格式获取输出，可使用以下方式：

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

技巧：

通过管道将 Claude 集成至现有的 Shell 脚本；
与其他 Unix 工具结合使用，实现强大的工作流；
可使用 --output-format 标志指定结构化输出格式。

当你需要将 Claude 的输出集成至脚本或其他工具时，可指定特定的输出格式：

使用文本格式（默认）：--output-format text
JSON 格式，该方式会输出包含元数据（费用、耗时）的 JSON 数组格式消息：--output-format json
使用流式 JSON 格式，该方式会在 Claude 处理请求的过程中，实时输出一系列 JSON 对象。单个消息为有效的 JSON 对象，但拼接后的整体输出并非有效的 JSON 格式：--output-format stream-json

咨询 Claude 的功能特性

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

> can Claude Code create pull requests?
> how does Claude Code handle permissions?
> what skills are available?
> how do I use MCP with Claude Code?
> how do I configure Claude Code for Amazon Bedrock?
> what are the limitations of Claude Code?

Claude 会基于官方文档解答上述问题。

无论你使用哪个版本的 Claude Code，Claude 均可访问最新的官方文档；
提出具体问题，可获取更详尽的解答；
Claude 可解释复杂功能，如 MCP 集成、企业级配置和高级工作流等。

最佳实践

Claude Code 是一个代理式编码环境。与等待回答问题的聊天机器人不同，Claude Code 可以读取你的文件、运行命令、进行更改，并在你观察、重定向或完全离开的情况下自主解决问题。

这改变了你的工作方式。与其自己编写代码并要求 Claude 审查，不如描述你想要什么，让 Claude 想出如何构建它。Claude 会进行探索、规划和实现。

但这种自主性仍有学习曲线。Claude 在某些你需要了解的约束下工作。本指南涵盖了经 Anthropic 内部团队以及在各种代码库、语言和环境中通过 Claude Code 验证有效的模式。

核心限制：上下文窗口管理

大多数最佳实践都基于一个核心限制：Claude 的上下文窗口填充速度很快，且随着填充，性能会下降。

Claude 的上下文窗口会存储整个对话内容，包括每一条消息、Claude 读取的所有文件以及所有命令输出，其存储空间会快速被占满。一次简单的调试会话或代码库探索，就可能生成并消耗数万个令牌。

这一点至关重要，因为大语言模型的性能会随上下文占满而下降。当上下文窗口即将存满时，Claude 可能会开始 遗忘 早前的指令，或出现更多错误。上下文窗口是你需要重点管理的核心资源，可通过自定义状态行持续跟踪上下文使用情况，也可参阅减少令牌消耗来了解具体的优化策略。

为 Claude 提供成果验证方式

为 Claude 提供测试用例、截图或预期输出结果，使其能自主校验工作成果，这是你能采取的最高价值的操作。当 Claude 可以自主验证成果时 —— 比如运行测试、对比截图、校验输出结果，其表现会大幅提升。

若缺乏明确的成功判定标准，Claude 生成的内容可能看似合理，实际却无法正常运行。此时你将成为唯一的反馈渠道，每一个错误都需要你亲自介入处理。

可通过 Claude 谷歌浏览器扩展程序 验证 UI 修改效果，该插件会在浏览器中打开新标签页、测试 UI 效果，并持续迭代直至代码运行正常
你也可以将测试套件、代码检查工具（linter）或用于校验输出的 Bash 命令作为验证手段，务必打造一套可靠的成果验证体系

先探索，再规划，最后编码

若让 Claude 直接开始编码，可能会写出解决错误问题的代码。建议使用规划模式（Plan Mode），将探索环节与执行环节分离。推荐的工作流分为四个阶段：

探索：进入规划模式，Claude 会读取文件、解答问题，但不会对代码做出任何修改。

1 2	read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets.

规划：让 Claude 制定详细的实现方案。

1 2	I want to add Google OAuth. What files need to change? What's the session flow? Create a plan.

在 Claude 开始执行前，按下Ctrl+G可在文本编辑器中打开计划并直接编辑。

实现：切换回普通模式，让 Claude 按照计划编码，并对照计划验证成果。

1 2	implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures.

提交：让 Claude 撰写描述性的提交信息并提交代码，同时创建拉取请求（PR）。

1	commit with a descriptive message and open a PR

需要注意，规划模式虽实用，但会增加一定的操作成本。对于范围明确、修改量小的任务（如修复拼写错误、添加日志行、重命名变量），可直接让 Claude 处理。当你对实现方案存疑、修改涉及多个文件，或对目标代码不熟悉时，规划环节能发挥最大价值。如果能用一句话描述清楚代码的修改差异，可直接跳过规划步骤。

在提示词中提供具体的上下文信息

你的指令越精准，后续需要的修正操作就越少。Claude 能推断你的意图，但无法读懂你的想法。在提示词中需标注具体文件、说明约束条件，并给出可参考的代码模式。

在探索阶段，模糊的提示词会有一定价值：你有足够的空间调整方向。例如 what would you improve in this file? 这类提示词，可能会让你发现一些未曾留意的问题。

你可通过多种方式为 Claude 提供丰富的信息：

用@符号引用文件，而非描述代码所在位置，Claude 会在回复前先读取该文件；
直接粘贴图片，可将图片复制粘贴或拖拽至提示词输入框；
提供文档和 API 参考的网址，可通过 /permissions 命令将常用域名加入白名单
通过管道传递数据，例如执行 cat error.log | claude，将文件内容直接发送给 Claude；
让 Claude 自主获取所需信息，可让其通过 Bash 命令、MCP 工具或读取文件的方式拉取上下文

配置开发环境

完成几个简单的配置步骤，就能让 Claude Code 在所有会话中都保持高效运行。

编写高效的 CLAUDE.md 文件

执行/init命令，可基于当前项目结构生成 CLAUDE.md 初始文件，后续可根据需求持续优化。CLAUDE.md 是一个特殊文件，Claude 会在每次会话开始时读取。文件中可写入 Bash 命令、代码风格规范和工作流规则，为 Claude 提供无法从代码中直接推断的持久化上下文信息。

/init 命令会分析代码库，自动识别构建系统、测试框架和代码模式，为你打造一个可直接优化的基础版本
CLAUDE.md 无固定格式要求，但需保证简洁、易读。示例如下：

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md 会在每次会话中加载，因此仅需写入通用规则。针对特定领域知识或仅在部分场景适用的工作流，建议使用技能（skills）功能：Claude 会按需加载，不会造成会话上下文冗余。

保持文件简洁：对每一条规则都问自己 如果删除这条规则，Claude 会出现操作失误吗？，如果答案是否定的，就果断删除。过于臃肿的 CLAUDE.md 会让 Claude 忽略你的实际指令！

✅ 建议写入	❌ 建议排除
Claude 无法自主推断的 Bash 命令	可通过读取代码获取的所有信息
与默认规则不同的代码风格规范	Claude 已掌握的标准语言约定
测试执行说明和首选的测试运行器	详细的 API 文档（可替换为文档链接）
代码仓库规范（分支命名、拉取请求约定）	频繁变动的信息
项目专属的架构决策	冗长的解释或教程
开发环境的特殊要求（必需的环境变量）	逐文件的代码库说明
常见的陷阱或非直观的代码行为	“编写整洁的代码” 这类不言自明的准则

如果已在 CLAUDE.md 中制定规则，但 Claude 仍出现违规操作，大概率是文件过于冗长，规则被淹没在无关信息中；如果 Claude 提出的问题在 CLAUDE.md 中已有答案，可能是规则表述模糊。请像对待代码一样对待 CLAUDE.md：出现问题时及时复盘、定期精简内容，并通过观察 Claude 的操作行为，验证规则修改的效果。

可通过添加强调词（如 “IMPORTANT（重要）” 或 “YOU MUST（必须）”）优化指令表述，提升 Claude 的规则遵守度。将 CLAUDE.md 提交至 Git 仓库，方便团队成员共同维护，该文件的价值会随时间推移不断提升。

CLAUDE.md 可通过@path/to/import语法导入其他文件
CLAUDE.md 可放在以下多个位置，实现不同范围的生效：
- 主目录（~/.claude/CLAUDE.md）：对所有 Claude 会话生效
- 项目根目录（./CLAUDE.md）：可提交至 Git 仓库供团队共享，也可命名为 CLAUDE.local.md 并加入 .gitignore 忽略
- 父级目录：适用于单体仓库（monorepos），父目录的 CLAUDE.md 会被自动加载
- 子目录：当处理子目录中的文件时，Claude 会按需加载子目录中的 CLAUDE.md

配置权限

使用 /permissions 命令将安全的命令加入白名单，或通过 /sandbox 开启系统级隔离，在减少操作中断的同时，保持对操作的控制权。

默认情况下，对于可能修改系统的操作（文件写入、Bash 命令执行、MCP 工具调用等），Claude Code 会先请求你的授权。这一机制虽保证安全，但会产生大量重复操作：当授权次数超过 10 次后，你可能只是机械点击确认，而非真正审核操作。可通过两种方式减少这类中断：

权限白名单：将确认安全的工具（如npm run lint、git commit）加入允许列表
沙箱隔离：开启系统级隔离，限制文件系统和网络访问，让 Claude 在指定范围内自由工作

也可使用 --dangerously-skip-permissions 参数跳过所有权限检查，适用于修复代码检查错误、生成样板代码等可控的工作流。需要注意的是，让 Claude 执行任意命令存在数据丢失、系统损坏或通过提示词注入泄露数据的风险，仅可在无网络访问的沙箱环境中使用 --dangerously-skip-permissions 参数。

使用命令行工具（CLI）

命令行工具是与外部服务交互时最节省上下文的方式。若你使用 GitHub，建议安装 gh 命令行工具 —— Claude 可通过它创建问题、打开拉取请求、读取评论。若未安装 gh，Claude 仍可调用 GitHub API，但未认证的请求易触发频率限制。

Claude 也能快速学习未掌握的命令行工具，可使用此类提示词：Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C.。

连接 MCP 服务器

通过 MCP 服务器，你可让 Claude 从问题跟踪工具中获取需求并实现功能、查询数据库、分析监控数据、整合 Figma 中的设计稿，以及自动化工作流。

执行 claude mcp add 命令，连接 Notion、Figma、数据库等外部工具。

设置钩子（Hooks）

钩子会在 Claude 工作流的指定节点自动执行脚本，与 CLAUDE.md 中仅作参考的指令不同，钩子是确定性的，能保证指定操作一定会执行。

你可让 Claude 为你编写钩子：

例如使用提示词：Write a hook that runs eslint after every file edit、Write a hook that blocks writes to the migrations folder

也可以执行 /hooks 命令进行交互式配置，也可直接编辑 .claude/settings.json 文件。

创建技能

在 .claude/skills/ 目录下创建SKILL.md文件，为 Claude 赋予领域知识和可复用的工作流。技能可为 Claude 补充项目、团队或特定领域的专属知识，Claude 会在相关场景自动应用，你也可通过 /技能名称 直接调用。

创建方式：在 .claude/skills/ 下新建目录，并在其中创建SKILL.md文件：

.claude/skills/api-conventions/SKILL.md

---
name: api-conventions
description: REST API design conventions for our services
---
# API Conventions
- Use kebab-case for URL paths
- Use camelCase for JSON properties
- Always include pagination for list endpoints
- Version APIs in the URL path (/v1/, /v2/)

技能也可定义可直接调用的可复用工作流，示例如下：

.claude/skills/fix-issue/SKILL.md

---
name: fix-issue
description: Fix a GitHub issue（修复GitHub问题）
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
（分析并修复指定的GitHub问题：$ARGUMENTS）

1. 使用`gh issue view`获取问题详情
2. 理解问题描述的核心内容
3. 在代码库中搜索相关文件
4. 实施必要的代码修改以修复问题
5. 编写并运行测试用例验证修复效果
6. 确保代码通过代码检查和类型检查
7. 撰写描述性的提交信息
8. 推送代码并创建拉取请求

执行 /fix-issue 1234 即可调用该技能。对于包含副作用、需要手动触发的工作流，可设置 disable-model-invocation: true。

创建自定义子智能体（Subagents）

在.claude/agents/目录下定义专属的 辅助智能体，让 Claude 将孤立的任务委托给它们处理。子智能体在独立的上下文中运行，拥有专属的可用工具列表，适用于需要读取大量文件或专注处理特定任务的场景，避免主会话的上下文被冗余信息占用。

示例如下：

---
name: security-reviewer
description: Reviews code for security vulnerabilities（代码安全漏洞审核）
tools: Read, Grep, Glob, Bash
model: opus
---
你是一名资深安全工程师，需审核代码中是否存在以下问题：
- 注入漏洞（SQL注入、跨站脚本攻击XSS、命令注入）
- 认证与授权缺陷
- 代码中硬编码的秘钥或凭证
- 不安全的数据处理方式

审核结果需标注具体的代码行，并给出修复建议。

可直接让 Claude 使用子智能体：Use a subagent to review this code for security issues.。

安装插件（Plugins）

插件（Plugin）将技能、钩子、子智能体和 MCP 服务器整合为一个可安装的单元，由社区和 Anthropic 官方维护。若你使用强类型语言，建议安装 code intelligence 插件，让 Claude 实现精准的符号导航，并在代码编辑后自动检测错误。

可以通过 /plugin 命令浏览插件市场、管理插件等。这里则是由 Anthropic 管理的高质量Claude代码插件的官方目录，可以通过 /plugin install plugin-name@claude-plugins-official 来安装指定插件。

高效沟通

与 Claude Code 的沟通方式，会极大影响输出结果的质量。

提出代码库相关问题

接入新的代码库时，可使用 Claude Code 进行学习和探索，你可以像向其他工程师提问一样，向 Claude 发出询问，例如：

日志系统的工作机制是怎样的？
如何新建一个 API 接口？
foo.rs 文件 134 行的async move { … }是什么含义？
CustomerOnboardingFlowImpl处理了哪些边缘场景？
为什么这段代码在 333 行调用foo()而非bar()？

这种使用方式是高效的接入流程，能缩短上手时间，减少对其他工程师的依赖。无需特殊的提示词技巧，直接提问即可。

让 Claude 主动向你提问

开发大型功能时，可先让 Claude 向你发起提问。使用极简的提示词，让 Claude 通过 AskUserQuestion 工具对你进行提问。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

需求规格书完成后，可开启新的会话执行开发：新会话拥有干净的上下文，可专注于开发实现，同时你也有书面的规格书可供参考。

管理会话

Claude 的会话是持久化且可回滚的，务必充分利用这一特性！

尽早且频繁地调整方向

一旦发现 Claude 的执行方向偏离预期，立即进行纠正。紧密的反馈环能带来最佳结果：尽管 Claude 偶尔能一次就完美解决问题，但及时的纠正通常能更快得到优质的解决方案。

Esc键：在 Claude 执行过程中按下，可终止当前操作，上下文会保留，你可重新引导执行方向
Esc + Esc 或 /rewind：连续按两次 Esc 键，或执行 /rewind 命令，可打开回滚菜单，恢复到之前的会话和代码状态，也可从指定消息开始生成摘要
输入 Undo that：让 Claude 撤销之前的修改
/clear：在处理不相关任务时重置上下文，过长且包含无关信息的会话会降低 Claude 的性能

若在同一会话中，针对同一问题纠正 Claude 超过两次，上下文会被多次失败的方案占用。此时建议执行 /clear 重置会话，结合已学到的经验，编写更精准的提示词重新开始。一个拥有优质提示词的干净会话，性能远优于积累了大量修正记录的长会话。

严格管理上下文

当接近上下文容量限制时，Claude Code 会自动压缩会话历史，保留重要的代码和决策信息，释放存储空间。在长会话中，Claude 的上下文窗口易被无关的对话、文件内容和命令占满，这会导致性能下降，甚至让 Claude 产生操作偏差。可通过以下方式优化：

在不同任务之间频繁使用 /clear，彻底重置上下文窗口；
自动压缩触发时，Claude 会总结核心信息，包括代码模式、文件状态和关键决策
如需更精细的控制，可执行 /compact <instructions>，例如 /compact Focus on the API changes（仅保留与 API 修改相关的上下文）；
如需仅压缩部分会话，可通过 Esc + Esc 或 /rewind 选择消息检查点，然后点击 从这里开始总结，该操作会压缩检查点后的消息，同时保留之前的上下文
可在 CLAUDE.md 中自定义压缩规则，例如添加 When compacting, always preserve the full list of modified files and any test commands

让子智能体负责调研工作

通过指令 use subagents to investigate X 将调研工作委托给子智能体，它们会在独立的上下文中探索，让主会话保持干净，专注于开发实现。

由于上下文是 Claude 工作的核心约束，子智能体是最强大的工具之一。当 Claude 调研代码库时，会读取大量文件，这些都会占用主会话的上下文；而子智能体在独立的上下文窗口中运行，仅会将调研总结反馈给主会话

1 2	Use subagents to investigate how our authentication system handles token refresh, and whether we have any existing OAuth utilities I should reuse.

子智能体会完成代码库探索、相关文件读取，并将调研结果反馈，全程不会造成主会话的上下文冗余。你也可在 Claude 完成开发后，让子智能体验证成果：

1 2	use a subagent to review this code for edge cases （让子智能体审核这段代码的边缘场景处理情况）

通过检查点回滚

Claude 的每一次操作都会生成检查点，你可将会话、代码或两者同时恢复到任意历史检查点。

Claude 会在修改代码前自动创建检查点，连续按两次 Esc 键或执行 /rewind 命令，可打开回滚菜单，支持仅恢复会话、仅恢复代码、同时恢复两者，或从指定消息生成摘要。

你无需精心规划每一步操作，可大胆让 Claude 尝试有挑战性的方案：若执行失败，直接回滚并尝试其他方案即可。检查点跨会话持久化，即使关闭终端，后续仍可进行回滚操作。

注意：检查点仅跟踪 Claude 做出的修改，不记录外部进程的操作，无法替代 Git 的版本控制功能。

恢复会话

执行 claude --continue 可继续上一次的会话，或执行 --resume 从最近的会话中选择恢复。Claude Code 会在本地保存会话记录，当任务跨多个会话执行时，你无需重新解释上下文。

可使用 /rename 为会话命名，方便后续查找。建议将不同的会话当作分支处理：不同的工作流可拥有独立、持久化的上下文。

自动化与规模化

前文介绍的所有技巧，均基于 一人一 Claude 一会话 的场景，而 Claude Code 支持水平扩展，本节将介绍提升工作效率的进阶技巧。

运行非交互式模式

在持续集成（CI）、提交前钩子（pre-commit hooks）或脚本中，使用 claude -p "prompt" 命令，添加 --output-format stream-json 可输出流式 JSON 数据。

# 一次性查询
claude -p "Explain what this project does"（解释这个项目的功能）

# 为脚本输出结构化的JSON数据
claude -p "List all API endpoints"（列出所有API接口） --output-format json

# 实时处理的流式输出
claude -p "Analyze this log file"（分析这个日志文件） --output-format stream-json

运行多个 Claude 会话

并行运行多个 Claude 会话，提升开发速度、开展独立实验，或启动复杂的工作流。除了提升工作效率，并行会话还能实现以质量为核心的工作流：干净的上下文能提升代码审核的效果。例如可采用 “编写 - 审核” 模式：

会话 A（编写者）	会话 B（审核者）
为我们的 API 接口实现限流功能	-
-	审核 @src/middleware/rateLimiter.ts 中的限流功能实现，重点检查边缘场景、竞态条件，以及是否符合现有中间件的实现模式
根据以下审核反馈修复问题：【会话 B 的输出内容】	-

智能体团队（Agent teams）可以多个会话自动协同工作，共享任务、传递消息，并由主智能体统一管理。

跨文件分布

对于大型的代码迁移或分析任务，可将工作负载分配到多个并行的 Claude 实例中，步骤如下：

生成任务列表：让 Claude 列出所有需要迁移的文件，例如 list all 2,000 Python files that need migrating
编写循环执行的脚本：

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL."
    --allowedTools "Edit,Bash(git commit *)"
done

小范围测试后规模化执行：先在 2-3 个文件上测试脚本，根据执行问题优化提示词，再全量运行

你也可将 Claude 集成到现有的数据 / 处理流水线中：

1	claude -p "<your prompt>" --output-format json \| your_command

开发阶段可使用 --verbose 开启调试模式，生产环境中建议关闭。

安全的自主模式

使用 claude --dangerously-skip-permissions 跳过所有权限检查，让 Claude 无中断地工作，适用于修复代码检查错误、生成样板代码等工作流。

让 Claude 执行任意命令存在数据丢失、系统损坏或通过提示词注入泄露数据的风险，为降低风险，仅可在无网络访问的容器环境中使用 --dangerously-skip-permissions 参数
开启沙箱隔离（/sandbox）后，可在保证安全性的前提下，实现类似的自主工作能力：沙箱通过预先定义边界实现限制，而非简单跳过所有检查。

规避常见的失败模式

以下是使用过程中常见的错误操作，尽早识别能节省大量时间：

杂乱的混合会话：处理一个任务时，中途让 Claude 处理无关问题，之后再回到原任务，导致上下文被大量无关信息占用
- 解决方法：在处理不相关任务时，执行/clear重置上下文
反复纠正同一问题：Claude 操作出错后你进行纠正，结果仍出错，反复多次后，上下文被大量失败的方案污染
- 解决方法：针对同一问题纠正两次后，执行/clear重置会话，结合经验编写更优质的初始提示词重新开始
过度冗余的 CLAUDE.md：文件过于冗长，导致重要规则被淹没，Claude 会忽略大部分内容
- 解决方法：果断精简内容，若 Claude 无需该规则也能正确操作，就删除它，或将其转换为钩子
先信任后验证 的漏洞：Claude 生成的实现方案看似合理，却未处理边缘场景
- 解决方法：始终为 Claude 提供验证手段（测试用例、脚本、截图），无法验证的成果切勿上线
无边界的探索：让 Claude “调研” 某一问题，但未明确范围，导致 Claude 读取数百个文件，占满上下文。
- 解决方法：为调研工作明确范围，或让子智能体负责，避免主会话的上下文被占用

培养使用直觉

本指南介绍的模式并非一成不变的准则，而是经过验证的通用起点，未必适用于所有场景：

有时你需要保留上下文的积累 —— 当深入处理一个复杂问题时，历史会话信息具有重要价值
时模糊的提示词会是最佳选择 —— 你可先观察 Claude 对问题的理解，再逐步缩小范围

关注有效的操作方式：当 Claude 输出优质结果时，留意你使用的提示词结构、提供的上下文信息和会话模式；当 Claude 表现不佳时，思考问题根源：是上下文过于冗余？提示词过于模糊？还是任务难度过高，无法一次完成？

随着使用经验的积累，你会形成独有的使用直觉，这是任何指南都无法替代的。你会逐渐掌握分寸：何时精准描述、何时留有余地；何时规划、何时探索；何时清空上下文、何时保留历史信息。