用好 Claude Code 的那些门道

从第一次尝试让 AI 帮忙写代码，到真正把它变成日常开发里顺手好用的伙伴，中间往往隔着几条不成文的经验。这篇文章想把这些经验整理出来------不是教条，而是一路上摸索出来的、确实管用的做法。

Claude Code 本质上是一个"能动起来"的编程环境。它跟普通的聊天机器人不太一样：后者是问一句答一句，而 Claude Code 能自己去读文件、跑命令、改代码，甚至一个人琢磨着把问题解决掉，开发者可以在一旁看着、中途纠正，或者干脆走开让它慢慢跑。

这种工作方式确实不一样。以前是自己写代码然后让 AI 来审，现在变成描述想要什么，Claude 自己琢磨怎么实现。它会探索、会规划、会动手。

当然，这种自由度也意味着需要适应它的"脾气"。下面这些经验，来自 Anthropic 内部团队以及在不同代码库、不同语言环境下使用 Claude Code 的工程师们。它们都围绕着一个核心约束展开：Claude 的上下文窗口，填满的速度比想象中快。

---

上下文窗口：那个需要时刻留心的资源

每一次对话、每一个文件、每一条命令的输出，都会被塞进 Claude 的上下文窗口里。这个窗口填满的速度相当快------一个调试会话或者代码库探索，动辄消耗几万甚至几十万 token。

这很重要，因为大语言模型在上下文快满的时候，表现会明显下降。它会"忘记"前面的指令，或者犯更多低级错误。上下文窗口可以说是最需要管理的资源。

那怎么知道窗口快满了呢？可以定制状态栏实时查看用量，也可以参考官方文档里关于减少 token 用量的策略。总之，心里有这根弦，后面很多做法就顺理成章了。

---

给它一个自己检验自己的办法

这是所有建议里最管用的一条：让 Claude 自己能验证结果对不对。

提供测试用例、截图、或者预期输出，让 Claude 跑完自己检查。一个能自检的 Claude，比不能自检的表现要好出一大截。

如果没有明确的标准，它可能产出看起来正确、实际上跑不通的东西。开发者就成了唯一的反馈回路，每个错误都得亲自来修。

看看几种常见场景的对比：

场景	不太好的问法	更好的问法
写函数	"实现一个验证邮箱地址的函数"	"写一个 validateEmail 函数。示例测试用例：user@example.com 应返回 true，invalid 返回 false，user@.com 返回 false。实现后运行这些测试。"
UI 改动	"让仪表盘好看点"	"[贴截图] 按这个设计实现。完成后截图对比，列出差异并修正。"
修构建错误	"构建失败了"	"构建失败，错误是：[贴错误]。修复并验证构建成功。解决根本原因，不要只是把错误提示关掉。"

UI 改动还可以用 Claude in Chrome 扩展来验证------它会在浏览器里打开新标签页，测试 UI，反复迭代直到代码正确。

验证可以是测试套件、linter、或者检查输出的 Bash 命令。花时间把验证机制做扎实，是回报率最高的投入。

---

先探索，再计划，最后动手

把研究和规划跟实际编码分开，可以避免解决错误的问题。

如果让 Claude 直接跳进代码，它可能产出解决错误问题的代码。用"计划模式"可以把探索和执行分开。

一个推荐的四步流程：

1. 探索
   进入计划模式，Claude 只读代码，不做任何改动。

claude (计划模式)
读一下 /src/auth，搞明白我们怎么处理会话和登录的。
再看看环境变量里的 secrets 是怎么管理的。

2. 计划
   让 Claude 制定详细的实现计划。

claude (计划模式)
我想加 Google OAuth。需要改哪些文件？
会话流程是怎样的？帮我制定一个计划。

按 Ctrl+G 可以在编辑器里直接改计划。

3. 实现
   切回普通模式，让 Claude 按计划写代码。

claude (普通模式)
按你的计划实现 OAuth 流程，给回调处理器写测试，跑通测试套件并修复失败。

4. 提交
   让 Claude 提交代码、开 PR。

claude (普通模式)
用描述性的消息提交，然后开一个 PR

计划模式很好用，但也会增加一些开销。对于范围明确、改动很小的事情（比如改个拼写、加条日志、重命名变量），直接让 Claude 做就行。

什么时候需要计划？当不确定怎么做的时候、改动涉及多个文件的时候、或者对要改的代码不熟悉的时候。如果改动一句话就能说清楚，那就不用计划了。

---

在提示词里给出具体上下文

指令越精确，后面需要纠正的次数就越少。

Claude 能猜到意图，但它没法读心。具体到文件、提到约束、指出可以参考的例子，这些细节都很重要。

策略	不太好的问法	更好的问法
明确范围	"给 foo.py 加测试"	"给 foo.py 写测试，覆盖用户登出时的边界情况。不要用 mock。"
指向来源	"ExecutionFactory 的 API 怎么这么奇怪？"	"翻翻 ExecutionFactory 的 git 历史，总结一下它的 API 是怎么变成现在这样的。"
参考现有模式	"加一个日历组件"	"看看首页现有组件是怎么实现的，HotDogWidget.php 是个好例子。按那个模式，实现一个新的日历组件，让用户能选月份、前后翻页选年份。纯手写，除了代码库里已有的库，不要用别的。"
描述症状	"修一下登录的 bug"	"用户反馈会话超时后登录失败。检查 src/auth/ 里的认证流程，特别是 token 刷新。先写一个会失败的测试复现问题，再修复。"

当然，模糊的提示也不是没用。在探索阶段，一句"这个文件有什么可以改进的？"往往能挖出一些自己没想到的问题。

---

用更丰富的方式给它信息

用 @ 引用文件、直接粘贴图片、或者用管道传数据，都可以让 Claude 拿到更丰富的信息。

• 用 @ 引用文件：不用描述代码在哪，Claude 会在回答前读文件。
• 直接粘贴图片：截图拖进去或者复制粘贴都行。
• 给文档链接 ：贴上 API 文档或参考链接，用 /permissions 把常用域名加白。
• 管道传数据 ：cat error.log | claude 直接把文件内容送进去。
• 让它自己去拿：告诉 Claude 用 Bash 命令、MCP 工具、或者读文件来获取需要的上下文。

---

把环境配好

几个小配置能让 Claude Code 在所有会话里都更顺手。

写一份好用的 CLAUDE.md

运行 /init 可以根据当前项目结构生成一个初始的 CLAUDE.md 文件，然后再慢慢打磨。

CLAUDE.md 是 Claude 每次对话开始时都会读的一个特殊文件。里面可以放 Bash 命令、代码风格、工作流规则------这些是 Claude 光看代码猜不出来的信息。

/init 会分析代码库，识别构建系统、测试框架、代码模式，搭好一个基础框架。

CLAUDE.md 没有固定格式，但尽量简短、易读。举个例子：

# 代码风格
- 使用 ES 模块（import/export），不用 CommonJS（require）
- 尽可能解构导入（例如 import { foo } from 'bar'）

# 工作流程
- 做完一系列代码改动后，记得做类型检查
- 优先运行单个测试，不要跑整个测试套件，速度更快

CLAUDE.md 每次会话都会加载，所以只放那些普遍适用的东西。那些只在某些时候相关的领域知识或工作流，可以考虑用技能（skills）代替------技能是按需加载的，不会让每个对话都变得臃肿。

保持简洁。每一条规则，都可以问自己："如果去掉这条，Claude 会犯错吗？"如果不会，就删掉。太长的 CLAUDE.md 反而会被 Claude 忽略。

应该放的内容	不应该放的内容
Claude 猜不到的 Bash 命令	Claude 读代码就能知道的东西
跟默认习惯不同的代码风格	标准语言惯例（Claude 已经知道了）
测试指令和偏好的测试运行器	详细的 API 文档（放链接就好）
仓库规范（分支命名、PR 约定）	频繁变化的信息
项目特有的架构决策	长篇大论的教程
开发者环境里的特殊要求（必需的 env var）	逐个文件的代码库描述
常见的坑或非直观的行为	不言自明的做法（比如"写整洁代码"）

如果 Claude 明明有规则禁止却还老犯，说明文件太长了，规则被淹没了。如果 Claude 问的问题明明 CLAUDE.md 里有答案，那可能是表述不够清楚。把 CLAUDE.md 当代码对待：出问题了就审一遍，定期修剪，改了之后观察 Claude 的行为有没有变化。

可以通过加强语气（比如"重要"、"必须"）来让 Claude 更遵守指令。把 CLAUDE.md 提交到 git，让团队一起维护。这个文件会随着时间积累，越来越有价值。

CLAUDE.md 还可以用 @路径 引入其他文件：

参见 @README.md 了解项目概览，@package.json 了解可用的 npm 命令。

# 补充指令
- Git 工作流：@docs/git-instructions.md
- 个人覆盖规则：@~/.claude/my-project-instructions.md

CLAUDE.md 可以放在几个不同位置：

• 主目录 ~/.claude/CLAUDE.md：所有 Claude 会话通用
• 项目根目录 ./CLAUDE.md：提交到 git 跟团队共享
• 父级目录：对 monorepo 很友好，根目录和子目录的 CLAUDE.md 都会被自动引入
• 子目录：当处理该目录下的文件时，Claude 会按需读取

配置权限

用"自动模式"让一个分类器来处理审批，或者用 /permissions 把特定命令加白名单，再或者用沙箱做系统级隔离。这些都能减少打断，同时保持可控。

默认情况下，Claude Code 对会改动系统的操作（写文件、执行 Bash 命令、调用 MCP 工具等）都会请求许可。安全但有点烦------到后来其实也不是真在审，就是机械地点确认。有三种方法可以减少打断：

• 自动模式：一个独立的分类器模型会审查命令，只拦截看起来有风险的（比如权限升级、未知基础设施、被恶意内容驱动的操作）。适合当信任任务的大方向，但不想每一步都点确认。
• 权限白名单 ：允许某些明确安全的工具，比如 npm run lint 或 git commit。
• 沙箱：启用系统级隔离，限制文件系统和网络访问，让 Claude 在明确边界内自由干活。

用好命令行工具

告诉 Claude Code 用 gh、aws、gcloud、sentry-cli 这些 CLI 工具跟外部服务打交道。

CLI 工具是与外部服务交互最省上下文的方式。如果用 GitHub，装一下 gh CLI。Claude 知道怎么用它来建 issue、开 PR、读评论。没有 gh 的话，Claude 也能调 GitHub API，但没认证的话容易触发限流。

Claude 学新 CLI 工具也挺快。可以试试这样的提示："用 'foo-cli-tool --help' 学习 foo 工具，然后用它解决 A、B、C。"

连上 MCP 服务器

运行 claude mcp add 可以接入 Notion、Figma、数据库这些外部工具。

有了 MCP 服务器，可以让 Claude 从 issue 追踪器实现功能、查数据库、分析监控数据、从 Figma 拿设计、自动化工作流等等。

配置钩子（hooks）

钩子能在 Claude 工作流程的特定节点自动运行脚本，保证某个动作每次都发生，没有例外。

跟 CLAUDE.md 那种"建议性"的规则不同，钩子是确定性的，能保证动作一定执行。

Claude 自己就能写钩子。试试这样的提示："写一个钩子，每次文件编辑后运行 eslint。"或者"写一个钩子，禁止对 migrations 目录的写入。"手动配置的话，直接编辑 .claude/settings.json，运行 /hooks 可以浏览当前配置。

创建技能（skills）

在 .claude/skills/ 目录下放 SKILL.md 文件，给 Claude 提供领域知识和可复用的工作流。

技能扩展了 Claude 的知识，可以放项目、团队或特定领域的信息。Claude 会在相关时自动应用，或者直接通过 /技能名 调用。

创建一个技能：在 .claude/skills/ 下建一个目录，里面放 SKILL.md：

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

---
name: api-conventions
description: 我们服务的 REST API 设计规范
---
# API 规范
- URL 路径用 kebab-case
- JSON 属性用 camelCase
- 列表接口必须带分页
- API 版本放在 URL 路径里（/v1/、/v2/）

技能也可以定义可直接调用的可重复工作流：

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

---
name: fix-issue
description: 修复一个 GitHub issue
disable-model-invocation: true
---
分析和修复 GitHub issue：$ARGUMENTS。

1. 用 `gh issue view` 获取 issue 详情
2. 理解问题描述
3. 搜索代码库找到相关文件
4. 实现修复
5. 写测试并运行验证
6. 确保代码通过 lint 和类型检查
7. 写描述性的提交消息
8. 推送并创建 PR

运行 /fix-issue 1234 就能调用它。用 disable-model-invocation: true 来标识那些有副作用、需要手动触发的工作流。

创建子代理

在 .claude/agents/ 下定义专门的助手，让 Claude 可以把隔离的任务交给它们。

子代理在自己的上下文里运行，有自己的工具集。适合那些要读很多文件、或者需要专注某个领域、不想弄乱主会话的任务。

.claude/agents/security-reviewer.md

---
name: security-reviewer
description: 审查代码的安全漏洞
tools: Read, Grep, Glob, Bash
model: opus
---
你是资深安全工程师。审查代码时关注：
- 注入漏洞（SQL、XSS、命令注入）
- 认证和授权缺陷
- 代码里的密钥或凭证
- 不安全的数数据处理

给出具体的行号和修复建议。

然后就可以让 Claude 明确调用："用一个子代理来审查这段代码的安全问题。"

安装插件

运行 /plugin 浏览插件市场。插件把技能、钩子、子代理、MCP 服务器打包成一个可安装的单元。如果用带类型的语言，装一个代码智能插件，能让 Claude 获得精确的符号导航和自动错误检测。

---

有效沟通的方式

怎么跟 Claude Code 沟通，对结果质量影响挺大。

问代码相关的问题

可以把 Claude 当成一个资深工程师来问问题。

刚接触一个新代码库时，可以用 Claude Code 来学习和探索：

• 日志是怎么工作的？
• 怎么新建一个 API 端点？
• foo.rs 第 134 行的 async move { ... } 是干什么的？
• CustomerOnboardingFlowImpl 处理了哪些边界情况？
• 为什么第 333 行调的是 foo() 而不是 bar()？

这样用 Claude 是一个很有效的上手方式，能缩短上手时间，减少对其他工程师的打扰。不需要什么特殊提示，直接问就行。

让 Claude 先采访你

对于大一点的功能，可以让 Claude 先采访你。

从一个极简的提示开始，让 Claude 用 AskUserQuestion 工具来采访：

我想做一个[简要描述]。用 AskUserQuestion 工具详细采访我。

问技术实现、UI/UX、边界情况、顾虑和取舍。别问显而易见的问题，深挖那些我可能没考虑到的难点。

持续采访直到都覆盖了，然后写一份完整的规格说明到 SPEC.md。

规格写完后，开一个新会话来执行它。新会话的上下文是干净的，全部精力都在实现上，手里还有一份写好的规格文档。

---

会话管理

对话是持久化的，还可以撤销。善用这个特性！

及早纠偏

发现 Claude 跑偏了，尽早纠正。

最好的结果往往来自紧密的反馈循环。虽然 Claude 偶尔第一次就完美解决，但快速纠偏通常能更快得到更好的方案。

• Esc：按一下就能让 Claude 停下手头的事，上下文还在，可以重定向。
• 两次 Esc 或 /rewind：打开回滚菜单，可以恢复之前的对话和代码状态，或者从选中的消息开始总结。
• "撤销那个"：让 Claude 自己撤回改动。
• /clear：在无关任务之间重置上下文。长会话里堆着不相关的上下文，会拖累表现。

如果同一个问题在同一个会话里纠正了两次还不对，说明上下文里已经堆满了失败的方法。运行 /clear，用一个更精确的提示重新开始，把刚才学到的东西融进去。一个新会话配上好提示，往往比一个塞满了修正的长会话效果更好。

主动管理上下文

在无关任务之间运行 /clear 来重置上下文。

Claude Code 会在接近上下文限制时自动压缩对话历史，保留重要的代码和决策，释放空间。

长会话里，上下文窗口很容易被无关对话、文件内容、命令输出填满。这会拖累表现，甚至让 Claude 分心。

• 任务之间用 /clear 完全重置上下文
• 自动压缩触发时，Claude 会总结最重要的信息（代码模式、文件状态、关键决策）
• 想更精细控制，用 /compact <指令>，比如 /compact 关注 API 改动
• 只压缩部分对话，可以用两次 Esc 或 /rewind，选一个消息检查点，选择"从这里开始总结"。这会把该点之后的消息压缩，保留之前的内容
• 在 CLAUDE.md 里定制压缩行为，比如"压缩时，务必保留所有修改过的文件列表和测试命令"，确保关键信息在总结后还在
• 那些不需要留在上下文里的快速问题，用 /btw。答案会出现在一个可关闭的浮层里，不会进入对话历史，查个细节也不会撑大上下文

用子代理做调研

用"用子代理来调研 X"把调研工作委派出去。子代理在单独的上下文里探索，主会话保持干净，专心实现。

既然上下文是核心资源，子代理就是最有力的工具之一。当 Claude 研究代码库时，它会读很多文件，这些文件都消耗主会话的上下文。子代理在独立的上下文窗口里运行，只汇报总结：

用子代理来调研一下我们的认证系统怎么处理 token 刷新，以及有没有现成的 OAuth 工具可以复用。

子代理探索代码库、读相关文件、回来汇报发现，主会话一点没乱。

Claude 实现完东西之后，也可以用子代理来验证：

用一个子代理来审查这段代码，看看有什么边界情况

用检查点回滚

Claude 的每一步操作都会创建一个检查点。可以恢复到任意之前的检查点，可以只恢复对话、只恢复代码、或者两者都恢复。

Claude 在改动前会自动创建检查点。按两下 Esc 或运行 /rewind 打开回滚菜单。可以选择只恢复对话、只恢复代码、两者都恢复，或者从选中的消息开始总结。

有了检查点，就不用小心翼翼了。可以让 Claude 尝试风险高的操作，不行就回滚换条路。检查点跨会话持久化，关掉终端后面还能回滚。

注意：检查点只追踪 Claude 做的改动，不是 git 的替代品。

恢复会话

运行 claude --continue 可以接着上次的对话，--resume 可以从最近的会话里选。

Claude Code 会把对话存在本地。当一个任务跨多个会话时，不用重复解释上下文：

claude --continue    # 恢复最近的会话
claude --resume      # 从最近的会话列表里选

用 /rename 给会话起个名字，比如"oauth-迁移"或"调试-内存泄漏"，以后好找。把会话当分支用：不同工作流可以有各自独立、持久的上下文。

---

自动化与规模化

当一个人用一个 Claude 用得顺手之后，可以试试并行会话、非交互模式、以及扇出模式，成倍放大产出。

非交互模式

在 CI、pre-commit 钩子或脚本里用 claude -p "提示词"。加 --output-format stream-json 可以拿到流式 JSON 输出。

非交互模式是把 Claude 集成到 CI 流水线、pre-commit 钩子或任何自动化工作流的方式。输出格式支持程序化解析：纯文本、JSON、流式 JSON。

# 一次性查询
claude -p "这个项目是做什么的"

# 给脚本用的结构化输出
claude -p "列出所有 API 端点" --output-format json

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

并行运行多个 Claude

可以同时跑多个 Claude 会话，加快开发、做隔离实验、或者启动复杂的工作流。

主要有三种方式：

• Claude Code 桌面应用：可视化地管理多个本地会话，每个会话有独立的工作树
• 网页版 Claude Code：在 Anthropic 的安全云基础设施上，隔离的虚拟机里运行
• Agent 团队：自动协调多个会话，共享任务、消息，有队长

除了并行工作，多会话还能支持一些注重质量的工作流。比如"写代码 / 审代码"模式：

会话 A（写）	会话 B（审）
给我们的 API 端点实现一个限流器
	审查 @src/middleware/rateLimiter.ts 里的限流器实现，找边界情况、竞态条件、以及与现有中间件模式的一致性
这是审查反馈：[会话 B 的输出]。解决这些问题。

类似的模式也可以用在测试上：让一个 Claude 写测试，另一个 Claude 写代码让测试通过。

跨文件扇出

用循环遍历任务，对每个调用 claude -p。配合 --allowedTools 限制权限，适合批量操作。

对于大规模迁移或分析，可以把工作分给多个并行的 Claude 调用：

1. 生成任务列表
   让 Claude 列出所有需要迁移的文件（比如列出 2000 个需要迁移的 Python 文件）
2. 写脚本循环

for file in $(cat files.txt); do
  claude -p "将 $file 从 React 迁移到 Vue。返回 OK 或 FAIL。" \
    --allowedTools "Edit,Bash(git commit *)"
done

3. 先在几个文件上试，再全量跑
   根据前两三个文件的情况调整提示词，然后跑全量。--allowedTools 限制了 Claude 能做什么，在无人值守时很重要。

也可以把 Claude 集成到现有数据处理流水线里：

claude -p "<提示词>" --output-format json | 你的命令

开发调试时用 --verbose，生产环境关掉。

用自动模式自主运行

想要不间断执行又要有后台安全检查，可以用自动模式。一个分类器模型会在命令执行前审查，拦截权限升级、未知基础设施、以及被恶意内容驱动的操作，让日常任务自动跑不用点确认。

claude --permission-mode auto -p "修复所有 lint 错误"

在用 -p 的非交互运行中，如果分类器反复拦截操作，自动模式会中止，因为没有用户可回退。

---

避坑指南

下面这些是常见的问题，早点识别能省不少时间。

"厨房水槽"式会话

从一个任务开始，然后让 Claude 做点不相关的事，再切回第一个任务。上下文里塞满了无关信息。
解法 ：不相关的任务之间用 /clear。

反复纠正

Claude 做错了，纠正，还是错，再纠正。上下文里堆满了失败的尝试。
解法 ：两次纠正之后还没好，/clear 重新开始，写一个更精确的初始提示，把刚才学到的东西放进去。

CLAUDE.md 太臃肿

文件太长，Claude 会忽略一半，因为重要规则被淹没了。
解法：狠心精简。如果 Claude 不用这条规则也能做对，就删掉，或者换成钩子。

"先信后验"的缺口

Claude 产出一个看起来合理的实现，但不处理边界情况。
解法：永远提供验证手段（测试、脚本、截图）。没法验证的代码，不要放过去。

无限探索

让 Claude "调研"某件事但不限定范围，结果它读了上百个文件，把上下文塞满了。
解法：给调研任务限定范围，或者用子代理，这样探索不会占主会话的上下文。

---

培养直觉

上面的这些做法不是铁律，只是普适性好、值得参考的起点，不一定在每个场景都最优。

有时候就应该让上下文积累------因为正深陷在一个复杂问题里，历史记录很有价值。有时候可以跳过计划，让 Claude 自己摸索------因为任务本来就是探索性质的。有时候模糊的提示刚刚好------想看看 Claude 怎么理解问题，不想过早约束它。

留意什么做法管用。当 Claude 输出特别好的时候，回头看看自己做了什么：提示结构、提供的上下文、所处的模式。当 Claude 卡住的时候，想想为什么：上下文太乱？提示太模糊？任务太大一次做不完？

慢慢地，会形成一种直觉，这是任何指南都写不出来的。会知道什么时候要具体、什么时候要开放，什么时候该计划、什么时候该探索，什么时候该清空上下文、什么时候该让它留着。

---

相关资源

• Claude Code 工作原理：代理循环、工具、上下文管理
• 扩展 Claude Code：技能、钩子、MCP、子代理、插件
• 常见工作流：调试、测试、PR 等的分步指南
• CLAUDE.md：存放项目规范和持久化上下文