Claude Code 最佳实践

Claude Code 真正好用的时候，更像一个反应很快、会写代码、会跑命令的同事，而不是一个你可以完全撒手不管的“自动工程师”。

很多失误都不是模型能力本身的问题，而是使用方式的问题：

• 任务边界太大
• 没有验证闭环
• 会话拖得太长
• 对仓库上下文交代得太含糊
• 还没搞清现状，就直接让它开改

所以关键问题从来不是“怎么让它做更多”，而是：

怎么让它在真实仓库里，持续产出能审、能验、能落地的结果。

第一原则：先给它验证手段

如果只能记一条，那就是这条：一定要让 Claude Code 有办法验证自己。

最有效的验证方式通常是这些：

• 可运行的测试
• 明确的校验命令
• 截图或 UI 目标
• 明确的报错信息
• 可检查的 diff
• 清楚的验收条件

差一点的说法

implement token refresh

好很多的说法

implement token refresh for expired access tokens in src/auth/; do not change session storage format; run the auth tests after changes and show me the diff

再比如 UI：

差一点的说法

make the dashboard match the design

好很多的说法

update the dashboard layout to match this screenshot; keep existing API calls unchanged; after changes, summarize remaining visual differences

Claude Code 一旦失去验证手段，就很容易产出“看起来像对的”东西。
这在真实项目里最危险，因为它会浪费你后面的审查时间。

正确顺序：先读，再想，再改

很多人一上来就让 Claude Code 直接写代码，这其实很容易让它解决错问题。

更稳的流程通常是：

1. 先读代码
2. 再出计划
3. 再动手改
4. 改完验证
5. 最后审 diff

重点不是形式，而是把“理解现状”和“开始实现”拆开。

比如你要改认证逻辑，正常顺序应该是：

• 先让它看现在认证流程怎么走
• 再让它说会影响哪些文件
• 再让它给出实现方案
• 最后再按方案改

这么做能明显减少几类常见问题：

• 改错文件
• 另起一套抽象
• 跟仓库现有模式打架
• 顺手改出一堆不在需求里的东西

CLAUDE.md 要有，但别写成说明书

一个好的 CLAUDE.md 很有用。
一个啰嗦的 CLAUDE.md 基本没用。

它应该只放那些仓库里推断不出来，但又确实会影响实现的信息，比如：

• 改完要跑什么命令
• 项目特有约束
• 团队特有规范
• 目录职责
• 哪些模式可以照着写
• 哪些坑明确别踩

比如这种就比较合适：

# Validation
- Run `pnpm test` for app code changes
- Run `pnpm lint` before finishing
- For schema changes, run `pnpm prisma generate`

# Constraints
- Do not change public API response shapes without explicit approval
- Prefer existing `src/lib/http.ts` helpers over adding new fetch wrappers
- Keep feature flags in `src/config/flags.ts`

# Repo conventions
- Integration tests live under `tests/integration/`
- New background jobs go under `src/jobs/`

反过来，两类内容不要写太多：

1. 太空的话

• 写 clean code
• 保持高可维护性
• 遵循最佳实践

这种基本没有信息量。

2. 太多的细节

把团队手册、架构文档、流程规范全塞进去，最后只会把真正重要的信息淹没。

一个好用的原则是：
只写“Claude 不容易自己看出来，但你又确实希望它遵守”的东西。

范围一定要收窄

Claude Code 最怕的，不是难任务，而是边界发虚的任务。

比如：

refactor the payment system

这种说法基本等于让它自由发挥。最后大概率会偏离目标。

如果换成：

in src/payments/stripe.ts, extract retry handling into a small helper; do not change the public function signatures; run the payment unit tests after edits

结果通常会靠谱很多。

实战里，收窄范围有几种很好用的方法：

• 指定具体文件或目录
• 明确哪些东西不能改
• 指定验证命令
• 一次只做一个子任务
• 把“调查”和“实现”拆开
• 把“重构”和“行为变更”拆开

这听起来不酷，但产出质量会高很多。

上下文是消耗品，不是无限资源

长会话一定会退化，这很正常。

你会慢慢看到这些信号：

• 它开始把猜测说成事实
• 早前说过的约束被忘掉
• 它开始顺手改旁边不相关的代码
• 它对仓库结构越来越自信，但其实越来越偏
• 它开始用补丁叠补丁，而不是回到问题本身

出现这种迹象时，不要继续硬拉当前会话。

比较实用的做法是：

• 一个会话只做一类事情
• 不相关任务之间清上下文
• 同一个问题纠正两次还不对，就新开会话

很多时候，重新讲一遍清楚的问题，比在一个已经混乱的会话里继续“救”它更省时间。

给参考，比讲抽象风格更有效

Claude Code 对“参考现有实现”这类提示，响应通常比“保持风格一致”好得多。

不够具体

make the new component consistent with the rest of the app

更有效

implement the new settings panel using the same form pattern as src/components/ProfileForm.tsx; keep validation style aligned with that file

再比如：

不够具体

use the existing way we do jobs

更有效

follow the enqueue and retry pattern used in src/jobs/sendDigest.ts

为什么参考文件特别有用？因为它能同时解决两个问题：

1. 减少猜测
2. 减少没必要的“创造性发挥”

真实仓库里，大多数时候你要的是第二点。

权限和沙箱，不只是安全设置，也是工作流选择

很多人一嫌权限提示烦，就想直接全关。
这不叫成熟，这只是把风险往后挪。

更合理的做法，是按任务类型选模式。

低风险、高频任务

可以考虑放宽一点的场景：

• 格式化
• lint
• 单元测试
• 只读探索
• 代码搜索
• 文档修改

高风险任务

建议保持更严格控制的场景：

• 任何删除性操作
• 依赖升级
• Git 历史改写
• 环境变量或凭证相关变更
• 部署命令
• schema migration
• 跨目录大量移动文件
• 让它代你 commit 或开 PR

沙箱也是一样。
沙箱更安全，但也可能让很多“验证”不真实，尤其是依赖真实命令执行的任务。

所以不要把权限或沙箱当成一个固定开关。
要看你现在是在做探索、实现、验证，还是在做高风险操作。

先看 diff，再谈 commit

Claude Code 可以帮你写 commit，但太早让它 commit，通常不是好主意。

更合理的顺序应该是：

1. 先实现
2. 先验证
3. 先看 diff
4. 再决定要不要让它帮你整理 commit message 或提交

因为代码就算“逻辑上没错”，diff 也可能有问题：

• 顺手格式化了不相干文件
• 改出一堆无关重命名
• 把顺手清理混进主改动
• 改了你不想碰的配置文件
• 重写了测试 fixture，导致真正变更被淹没

一个很实用的提示是：

show me the diff first and summarize the files changed by purpose

这句话的价值在于，它强制插入了一个“停一下”的步骤。

如果你确实要它帮写 commit message，也最好加约束：

write a commit message focused on the auth timeout fix only; do not mention unrelated refactors

不只是拿它写代码，也拿它做分析

Claude Code 很大的价值，其实来自“先分析，再修改”。

比如这些场景都很适合：

• 总结某个子系统的结构
• 追一个配置值在代码里的流转
• 比较两种实现差异
• 从日志一路追到代码里的故障路径
• 分析 flaky test
• 审一段 diff 的风险点

这些工作通常比“直接生成代码”更稳，尤其是在你对仓库还不熟的时候。

很多团队真正建立起对这类工具的信任，也往往是从分析能力开始的。

中大任务要拆检查点

任务一旦稍微大一点，就别让它一路跑到底。

你可以显式把节点拆出来，比如：

1. 先看 auth flow
2. 列出要改的文件
3. 给出计划
4. 只实现 backend 部分
5. 跑测试
6. 总结 diff
7. 再处理 frontend 接线

即使你不是每一步都真的人工确认，这种结构本身也有价值。
Claude Code 在“任务有形状”的情况下，表现通常更稳定。

特别是下面这几类任务，更应该拆：

• 重构
• 数据迁移
• 跨模块改动
• 带兼容性约束的改动

警惕“补丁叠补丁”的长会话修复模式

一个很常见的劣化路径是这样的：

• 第一版实现错了
• 第二版在第一版上打补丁
• 第三版为了兼容前两版，又加了一层逻辑
• 最后 diff 体积翻倍，清晰度减半

一旦你发现它开始这么干，就该停了。

这时更好的做法通常是：

• 先让它重新总结目标行为
• 重新给一个干净的实现计划
• 基于当前文件重新来一遍，不要沿着错误历史继续修

不要让一个混乱会话在代码里“沉淀地层”。

提示里要明确“不能做什么”

很多结果变差，不是因为要求太少，而是因为禁区没说。

这类限制非常有用：

• do not change public API shapes
• do not rename files
• do not touch migrations
• do not add new dependencies
• do not modify unrelated tests
• do not convert this to a different state management pattern

Claude Code 很容易在附近区域“顺手优化”。
有时这确实有帮助，但更多时候只是范围失控。

把不能做的事情提前讲清楚，能明显减少这种问题。

最后还是按“同事交付”的标准来审

最合理的审查标准不是“这是 AI 写的”，而是：

如果这是一个靠谱但赶时间的同事交上来的改动，我会不会接收？

所以你最终还是要看这些东西：

• 逻辑对不对
• 改动范围是否收得住
• 测试是否足够
• 是否符合仓库现有约定
• 回滚是否清楚
• 有没有额外运维影响

工具提供的是速度。
你要提供的是判断、边界感和最后拍板。

一个够用的操作模型

如果你想要一个比较稳定、可复用的 Claude Code 用法，我建议默认按下面这套来：

1. 给最小可行范围
2. 指到具体文件
3. 说明哪些东西不能动
4. 说明怎么验证
5. 非小任务先要计划，再要实现
6. 会话一旦发浑就重开
7. commit 之前先看 diff
8. 把它当贡献者，不当裁判

做到这些，基本就能拿到它的大部分收益，同时避开最常见的坑。