Claude Code 最佳实践：官方指南与实战经验

官方推荐的工作流 + 社区验证的效率技巧。

Claude Code 官方文档有一份最佳实践指南，来自 Anthropic 内部团队。社区也总结出大量实战经验——一个 GitHub 仓库整理了 84 条实践，我筛选出最实用的内容。

一、给 Claude 验证方式

这是官方强调的最高杠杆建议。

Claude 能验证自己的工作时，表现会好得多：跑测试、比截图、检查输出。没有验证标准，它可能写出看起来对但实际不行的代码。

验证策略对比

Bug 只说"修复"，别微操

这是社区最反直觉的一条建议。

遇到 bug，把错误信息贴给 Claude，说一个词：修复。别指导它怎么修，别猜测原因，别指定方案。

Claude 的调试能力比大多数人想象的强——你越微操，越可能把它带偏。直接让它修，成功率 80%+。

如果两次尝试还不行，停下来。用 /clear 重置上下文，换个角度再试。

你：这个报错是因为数据库连接超时，

可能是连接池配置问题，

你查一下连接池设置...

你：[粘贴错误信息]

修复。

二、探索 → 规划 → 编码

把研究和规划与实现分开，避免解决错误的问题。

Plan Mode 工作流

进入 Plan Mode：按 Shift+Tab 两次。Claude 只读文件、回答问题，不做修改。

推荐流程：

1. 探索（Plan Mode）

claude (Plan Mode) 读取 /src/auth，理解 session 处理逻辑。

2. 规划（Plan Mode）

claude (Plan Mode) 我想添加 Google OAuth。需要改哪些文件？

创建一个计划。

3. 实现（Normal Mode）

claude (Normal Mode) 按计划实现 OAuth 流程。

为回调处理器写测试。

4. 提交

claude (Normal Mode) 用描述性消息提交，打开 PR。

什么时候跳过规划？

能用一句话描述 diff，就跳过计划。

三、CLAUDE.md 保持在 60 行以内

这是新手最容易犯的错误。

我刚用 Claude Code 时，CLAUDE.md 写了快 500 行——项目描述、编码规范、API 文档全塞进去。结果是：Claude 会选择性忽略规则，尤其是文件末尾的那些。

经验数据： - 理想长度：60 行以内 - 硬性上限：300 行

Boris Cherny（Claude Code 创作者）的解释：前沿 LLM 可靠执行的指令大约 150-200 条，系统提示已经占了约 50 条。留给用户的空间不多。

我的做法：

CLAUDE.md 只放 Claude 可能忽略的信息：

- 构建命令

- 测试命令

- 分支命名规范

- 项目特定的架构决策

Claude 能从代码推断的，不写进 CLAUDE.md。

规则太多？拆到 .claude/rules/ 按需加载。

关键规则用 <critical> 标签包裹。

四、让 Claude 先面试你

给 Claude 一个简单需求描述，让它用 AskUserQuestion 工具面试你，澄清所有细节。面试完，开新会话执行。

我在做 API 时，Claude 问了"并发请求怎么处理"、"超时策略是什么"——这些我起初根本没考虑。它的提问能帮你发现遗漏的边界情况。

关键点：面试完开新会话。面试过程的长对话会污染上下文。

示例：

你：我要做一个用户认证系统。

Claude 开始面试：

1. 认证方式：JWT 还是 Session？

2. 密码存储：用什么哈希算法？

3. 登录失败限制：几次锁定？

4. Token 过期时间：多久？

5. 多设备登录：允许还是互踢？

你回答完所有问题。

你：/clear（开新会话）

你：按刚才讨论的需求实现用户认证系统。

五、提供具体上下文

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

上下文策略对比

上下文来源清单

src/auth/login.ts

六、要求重写平庸方案

当 Claude 给出的方案能用但不优雅时，别打补丁。直接说：

knowing everything you know now, scrap this and implement the elegant solution

Claude 会基于对问题的完整理解重新设计。我试过几次，重写的版本总比打补丁的好。

类似地，你可以说 prove to me this works，让 Claude 把当前分支和 main 做 diff，验证改动是否正确。

Claude：[实现了一个能用但丑陋的方案]

你：这个方案能用，但不够优雅。

knowing everything you know now, scrap this and implement the elegant solution.

Claude：[基于完整理解重新设计，方案更简洁]

七、提示词里加"用子 Agent"

在提示词里加一句 use subagents，Claude 会把任务拆成多个子 Agent 并行处理。

特别适合代码审查和大规模重构。有人用 9 个并行子 Agent 做代码审查，每个专注一个质量维度。

你：审查这个 PR，检查安全性、性能、代码风格。

use subagents

Claude 启动 3 个子 Agent：

- 子 Agent 1：安全审查

- 子 Agent 2：性能审查

- 子 Agent 3：风格审查

主会话只收到汇总报告。

技巧：创建子 Agent 时，让它功能具体（如"前端组件 Agent"）而不是泛泛的（"QA Agent"）。功能越具体，结果越好。

八、Skills 用文件夹结构，加 Gotchas 区

很多人写个 SKILL.md 就算完事。但 Skills 应该是完整的文件夹结构：

.claude/skills/my-skill/

├── SKILL.md # 核心规则和索引

├── references/ # 详细文档

├── scripts/ # 可执行脚本

└── examples/ # 示例文件

这种渐进式披露是关键——Claude 只在需要时读取子目录内容，而不是一次把所有东西塞进上下文。

另一个技巧：每个 Skill 里建一个 Gotchas（陷阱记录）区，每次 Claude 犯错就记录失败模式。时间长了，这是信噪比最高的内容。

## Gotchas（陷阱记录）

- ❌ "值得注意的是" → 太啰嗦，直接说重点

- ❌ "在...的背景下" → 翻译腔，改成"在...情况下"

- ❌ 连续三个四字短语 → AI 腔，换表达

九、上下文用到 50% 就手动压缩

这是最重要的工作流级实践。

Claude Code 有个"Agent 呆滞区"——上下文超过 60-70% 时，性能明显下降，Claude 开始忽略指令、犯低级编码错误。

仓库建议：在 50% 时手动执行 /compact，别等自动压缩，那时候通常已经晚了。

你：/context

Claude：当前上下文 90K/200K，使用率 45%

你：[继续读文件...]

你：/context

Claude：当前上下文 105K/200K，使用率 52%

你：/compact

Claude：已压缩对话历史，当前上下文 35K/200K

用 /statusline 实时监控用量。

十、跑偏时按 Esc Esc 回滚

Claude 跑偏了怎么办？大多数人的本能是在当前会话里纠正。

建议：直接按两次 Esc（或用 /rewind）回滚到上一个检查点。在同一个上下文里纠正跑偏，往往越改越乱——因为错误推理还在上下文里，Claude 会被自己的错误逻辑带偏。

我的习惯： - 跑偏一次 → Esc Esc 回滚 - 同一问题跑偏两次 → /clear 重开

Claude：[开始重构整个架构，但你只想改一个函数]

你：Esc Esc（回滚到重构前）

你：我只改 validateToken 这个函数，不动其他文件。

十一、早纠正，频纠正

Claude 不怕被纠正。它怕的是你沉默。

纠正时机

• 方向错了：立即打断，说明正确方向

• 方法对了但细节错：让它继续，完成后再调整

• 完成度 50% 时：快速检查，确认方向正确

纠正方式对比

"不对，重来"

"方向对了，但不要用 mock，用真实数据库。

当前的测试会在 CI 失败，因为 mock 的响应格式和真实 API 不一致。"

十二、小任务别用复杂工作流

原生 Claude Code 处理小任务比任何复杂工作流都快。

我以前改个变量名也要走完整的 Plan → Execute → Review 流程。其实一句话就行。

那些复杂工作流（Superpowers、Spec Kit 等）是为涉及多文件多步骤的大任务设计的。三五分钟能搞定的事，原生最快。

判断标准：

能用一句话描述改动的 → 直接说

涉及 3 个以上文件的 → 用工作流

需要多轮验证的 → 用工作流

改动逻辑复杂的 → 先 Plan Mode

十三、自动化和扩展

非交互模式

适合 CI/CD、脚本、后台任务：

claude --print "analyze the test failures in src/tests/"

并行会话

用 Git Worktree 运行多个 Claude 实例：

git worktree add ../feature-a feature-branch

cd ../feature-a

claude "implement feature A" &

Auto Mode

让 Claude 完全自主运行：

claude --auto

十四、常见失败模式

模式一：没有验证标准

症状：Claude 写出看起来对但实际不行的代码。

解决：提供测试、截图、预期输出。

模式二：一次性塞太多

症状：Claude 被淹没，开始丢信息。

解决：分阶段，用子 Agent 隔离，50% 就压缩。

模式三：指令模糊

症状：Claude 瞎猜，需要反复纠正。

解决：指明文件、约束、示例。

模式四：忽略上下文管理

症状：上下文快满了才发现，Claude 开始"失忆"。

解决：定期 /context，超过 70% 就 /compact。

模式五：不及时纠正

症状：Claude 走偏了很久才发现，需要大改。

解决：在完成度 50% 时检查。

总结

核心实践速查表：

参考

• Claude Code 最佳实践文档 — https://code.claude.com/docs/en/best-practices

• Claude Code 最佳实践仓库 — https://github.com/shanraisshan/claude-code-best-practice

• Claude Code 常见工作流 — https://code.claude.com/docs/en/common-workflows

• Claude Code 扩展机制 — https://code.claude.com/docs/en/features-overview