Claude Code 避坑指南：新手最常见的 10 个错误

覆盖热词：claude code tips（30📊）| claude code 错误（5🟢）| claude code 避坑（5🟢）

说在前面

Claude Code 确实很强，但它不是万能钥匙。用不对地方、用不对方法，效率反而比手写还低。

这 10 个坑是我自己踩过的，以及从开发者社区收来的真实案例。每一条后面都有怎么绕过去的方法。

坑 1：不给上下文，让 Claude 猜

错误做法：

帮我优化这个 API 的性能。

Claude 不知道你的 API 是什么、跑在什么环境、瓶颈在哪。它可能开始重写整个后端。

正确做法：

帮我优化 @src/api/users.ts 里的 GET /users 接口。
目前一次查询平均 2.3 秒，怀疑是 N+1 查询。
用 Prisma 的 include 做预加载试试。

关键： 告诉 Claude 三件事——改什么文件、问题是什么、你倾向的方案。

坑 2：一次塞太多需求

错误做法：

帮我加用户登录、注册、找回密码、社交登录、
双因素认证、OAuth、SSO……

Claude 会开始写，写到一半忘了前面要什么，代码里开始出现互相矛盾的逻辑。

正确做法：

先帮我加邮箱密码登录。
好了之后，再加 Google OAuth 登录。

关键： 一次一件事。做完了确认，再做下一件。

坑 3：不改 CLAUDE.md

默认情况下，Claude Code 不知道你的项目用 TypeScript 还是 JavaScript，用 yarn 还是 pnpm。

错误表现：

你：帮我加一个按钮
Claude：好的，我创建一个 login.php 文件……
你：？？？

正确做法： 在项目根目录创建 CLAUDE.md，写清楚技术栈和规范。具体怎么写看上一篇文章《进阶技巧》。

坑 4：不检查 Claude 的修改

错误做法：

你：帮我把颜色主题改成暗色
Claude：好的，已修改 style.css
你：（看都不看直接继续下一件事）

结果：Claude 改了颜色，但也顺手改了你没让它动的布局代码。

正确做法： 每次 Claude 改完，先看一眼 diff：

你刚才改了哪些文件？列出来。

或者直接看 git diff：

git diff

Claude 每次修改前会自动 git commit（如果你在 git 项目里），回滚也很方便。

坑 5：让 Claude 写它不擅长的东西

Claude Code 擅长： - 写代码（函数、组件、API） - 改代码（重构、优化、加功能） - 跑命令（安装依赖、执行脚本） - 读文档（解释代码、查用法）

Claude Code 不擅长： - 设计系统架构 - 做视觉设计 - 写文案（特别是营销文案） - 决策（用 A 方案还是 B 方案）

正确做法： 架构你自己想，代码让 Claude 来写。设计你自己画，实现让 Claude 来填。

坑 6：对话太长不换 session

Claude Code 的上下文窗口虽然大，但聊了 200 轮之后，它会开始"遗忘"早期的信息。

错误表现：

Claude：好的，我意识到前面第 3 步的方案有问题，
我们重来。等等，你的项目是干什么来着？

正确做法： 每完成一个功能，退出 Claude（按 Ctrl+C 或输入 /exit），重新启动。新的 session 有干净的上下文。

需要继续前面工作时，用 /resume 恢复最近的 session。

坑 7：不用 / 命令

Claude Code 有很多内置命令，新手往往不知道：

最实用的一个是 /cost—— 随时看看 Claude 帮你写了多少代码、花了多少 API 费。很多新手月底收到账单才惊呼"这么贵"。

坑 8：让 Claude 写整个项目

错误做法：

帮我写一个电商网站，有商品列表、购物车、
支付、后台管理……

Claude 会努力写，但写到后面前面已经忘了，代码质量越来越差，最后你得到一个几乎不可维护的项目。

正确做法：

先帮我初始化一个 Next.js 项目。
→ 再加商品列表页面。
→ 再加购物车功能。
→ 再加支付对接。

关键： 先搭骨架，再填肉。分阶段、分文件，不要一次全塞进去。

坑 9：过度依赖 Claude 写测试

Claude 写测试确实很快，但你得告诉它测什么、怎么测。

错误做法：

帮我写单元测试。

Claude 会写一堆"测试覆盖率 100%"但什么都不测的测试：

test('adds 1 + 2', () => {
  expect(1 + 2).toBe(3);
});

正确做法：

给 @src/utils/calculate.ts 里的 calculateTotal 函数写测试。
这个函数的输入是一组商品 {price, quantity, discount}，
输出是折后总价。
要测：正常计算、折扣为 0、空数组、负数折扣。

坑 10：不看 API 账单

Claude Code 用 Anthropic API 按量计费。如果用 Sonnet 模型干所有事，一个月下来可能几百美元。

省钱技巧：

在 Claude Code 里切换模型：

用 Haiku 模式帮我优化这个函数。

输入 /cost 随时查看当前 session 的花销。

总结

这些坑踩过一次就会记住。关键是：Claude Code 是你手中的工具，不是你老板。 你指挥，它执行。你不指挥，它只能猜。

🔗 相关文章： Claude Code 实战：10分钟用AI搭建一个网页应用 | Claude Code 进阶技巧：CLAUDE.md与MCP配置

📚 Claude Code 中文开发者系列（持续更新中） → Claude Code vs Cursor vs Aider：三个AI编程工具的真实对比 → Anthropic悄悄更新了Claude 4 Sonnet → Claude Code 写了200行代码然后忘了自己在干嘛 → Claude Code 团队协作实战：CLAUDE.md统一、MCP共享、Code Review自动化 → Claude Code CI/CD 集成：GitHub Actions 自动代码审查与测试生成 → Claude Code 写测试实战：TDD、Mock、覆盖率一条龙 → Claude Code 省钱终极攻略：从月消费$200到$30 → Claude Code + 本地模型混合方案：什么时候用云端、什么时候用本地