本节目标

完成本节后，你将能够：

1. 识别并避开 Claude Code 新手最常见的 10 个错误

2. 写出不会被 AI 误读的 CLAUDE.md 规则

3. 正确配置权限，既不繁琐也不危险

4. 理解 API 计费陷阱，控制月度开销

5. 完成从"Vibe Coding"到"Agentic Engineering"的思维跃迁

---

核心知识点

TOP 10 新手常见错误及解决方案

错误 1：期望 AI"像人一样理解我"

症状：发一条模糊的指令如"帮我优化这个项目"，然后对结果不满意。

根因：AI 不是你的同事。它不知道你的项目背景、业务逻辑和你脑子里的未说出口的假设。

解决方案：遵守"完整上下文原则"——

• 告诉它你在做什么项目（一句话）

• 告诉它你想要的具体结果（一段话，具体到文件路径）

• 告诉它有什么约束（风格、性能、兼容性要求）

• 示例："我在做一个 NestJS 后端项目，需要给 src/modules/user/user.service.ts 中的 createUser 方法添加事务支持。数据库是 PostgreSQL，使用 TypeORM。必须保证邮箱唯一性检查和新用户创建在同一个事务中。"

错误 2：不看 Diff 就直接 Approve

症状：每次修改都直接按 A（Approve），改完了才发现 AI 把别的地方也改了。

根因：把 AI 当成"可靠的黑盒"，放弃了质量审查的责任。

解决方案：建立"必看 Diff 的铁律"——

• 超过 10 行的修改：必须看完整 Diff

• 涉及 3 个以上文件的修改：逐个文件看 Diff

• 涉及配置文件的修改：必须理解每行变化

• 涉及依赖的修改：必须检查版本号

错误 3：一个会话做太多不相关的事

症状：同一个会话里，先让 AI 改前端页面，又让它写后端 API，再让它配 Docker，最后让它写周报。会话持续了 2 小时，40+ 轮对话。

根因：不理解上下文窗口的有限性。

解决方案：遵守"一个会话一个主题"原则——

• 新功能开发 → 独立会话

• Bug 修复 → 独立会话

• 代码重构 → 独立会话

• 文档撰写 → 独立会话

• 部署配置 → 独立会话

• 切换任务时用 /clear 或新开会话

错误 4：把 CLAUDE.md 当成"万能兜底"

症状：在 CLAUDE.md 里写了几百行规则，试图覆盖所有可能的情况。结果 CLAUDE.md 超过 300 行，每次加载消耗大量 token。

根因：CLAUDE.md 是"操作规范"不是"百科全书"。你无法（也不应该）用规则覆盖所有情况。

解决方案：

• CLAUDE.md 控制在 150 行以内

• 只写"绝对必要"的规则

• 把背景知识和历史决策放 README 或 Wiki

• 每月审视一次，删除不再适用的规则

错误 5：权限配置"一劳永逸"

症状：第一天就设置了一大堆 Allow 规则，之后再也不调整。

根因：把权限配置当成一次性的"安装步骤"，而不是持续演进的安全策略。

解决方案：

• 新项目从 defaultMode: "ask" 开始

• 每次遇到"这个操作我每次都要手动批准"时，才加一条 Allow 规则

• 每周审视一次 Allow 列表，移除不再需要的

• 在项目进入维护模式后，收紧权限

错误 6：不会"及时止损"——在错误方向上反复修补

症状：AI 第一次没改对，给反馈 → 第二次还是不对，再给反馈 → 第三次依然跑偏，但还是不甘心，继续修补。最终花了 6 轮才得到一个能用但不优雅的结果。

根因：沉没成本谬误——已经投入了时间和 token，不想"重来"。

解决方案：严格执行"两改原则"（详见第 5 节）——

• 第一次改不对 → 给更具体的反馈

• 第二次还不对 → /clear + 重新描述需求

• 永远不要在同一会话中做第三次修补

错误 7：忽视 /cost，月底收到账单吓一跳

症状：每天都在用 Claude Code，但从不看 /cost。月底查看 Anthropic Console 的 Usage 页面，发现花了 $150+。

根因：不了解 token 消耗的规模和影响因子。

解决方案：

• 每次用完执行 /cost，建立"花费感"

• 理解哪些操作最费 token：输出 > 标准输入 > 缓存输入

• 对于简单的查询和检查，考虑使用 Haiku 模型（更便宜）

• 在 Anthropic Console 设置月度消费上限（Usage Limits）

• 合理利用 prompt caching——CLAUDE.md 和 System Prompt 的缓存命中是免费的午餐

错误 8：在包含敏感数据的目录中不加限制地运行 Claude Code

症状：在生产服务器的项目目录中直接运行 claude，没有额外的安全检查。

根因：没有区分"开发环境"和"生产环境"的安全需求差异。

解决方案：

• 在生产环境目录中，使用严格的 settings.json（大量 deny 规则）

• 或者干脆不在生产目录中运行 Claude Code

• 如果必须在生产环境排查问题，使用 --bare --max-turns 3 只做查询不做修改

错误 9：不区分模型的使用场景

症状：无论是写一个简单的日志分析脚本还是做复杂的架构重构，都用同一个模型。

根因：不了解不同模型的能力、速度和价格差异。

解决方案：

任务类型	推荐模型	理由
简单查询、解释代码	Haiku 3.5	够用、快、便宜（1/4 价格）
日常开发、重构、写测试	Sonnet 4	最佳性价比，90% 的场景
复杂架构决策、深度分析	Opus 4	最多推理深度，但贵 5 倍

# 日常开发用 Sonnet（默认）
claude
​
# 快速查询用 Haiku
claude --model claude-haiku-3-5-20241022 -p "解释这个正则表达式"
​
# 复杂任务用 Opus
claude --model claude-opus-4-20250514

错误 10：不清楚 --continue 和 --session-id 的用法

症状：会话意外退出后不知道怎么恢复，之前讨论的上下文全部丢失。

根因：不了解 Claude Code 的会话管理机制。

解决方案：

# 如果上一个会话意外退出（终端崩溃、SSH 断开等）
claude --continue
# 这会恢复你上一个会话的完整上下文
​
# 如果你想管理多个并行的会话
claude --session-id "feature-user-auth"
# 然后在另一个终端中继续同一个会话
claude --session-id "feature-user-auth" --continue

5 个 CLAUDE.md 编写陷阱

1. "代码要有良好的可读性" → 太模糊。改成"函数不超过 40 行，变量名使用有意义的完整单词，禁止缩写（除了 i/j/k 循环变量）"

2. "遵循最佳实践" → 不可验证。改成"React 组件使用函数式组件和 hooks，禁止 class 组件"

3. "注意性能优化" → 无法执行。改成"禁止在循环中使用 await，禁止在 render 中创建新对象"

4. "不要做危险操作" → AI 不知道什么算"危险"。改成"禁止删除 .git 目录，禁止修改 CI 配置文件，禁止引入评分 < 80% 的 npm 包"

5. CLAUDE.md 写了 400 多行 → 信息过载反而降低规则遵守率。严格执行 150 行上限

3 个权限配置陷阱

1. "为了省事全部 Allow" → 放弃了所有安全检查。正确做法：只 Allow 那些你确认安全且频繁使用的操作。

2. "Git 操作全放开" → git push --force 可能会被 AI 误触发。正确做法：Allow git status/diff/log/add/commit/branch，Deny git push/reset --hard。

3. "deny 规则写得不够具体" → Bash(rm) 不会阻止 rm -rf。正确做法：用通配符 Bash(rm:*) 覆盖所有 rm 变体。

API 连接和计费问题速查

问题	原因	解决
Connection refused	代理未配置或不正确	检查 HTTPS_PROXY 环境变量
401 Unauthorized	API Key 无效或过期	在 console.anthropic.com 检查 Key 状态
429 Rate Limited	请求频率过高	等待几秒后重试，或升级 API 套餐
Insufficient balance	API 账户余额不足	在 console 中充值
账单比预期高 3 倍	大量使用了 Opus 模型	检查你使用的模型，日常用 Sonnet

从 Vibe Coding 到 Agentic Engineering 的思维转变

"Vibe Coding"是 2025 年兴起的一个术语，描述了一种"凭感觉让 AI 写代码"的风格——描述一个模糊的想法，让 AI 生成代码，然后复制粘贴、不断试错直到"看起来能跑"。

"Agentic Engineering"是 Claude Code 代表的工程化方法——你定义清晰的规则（CLAUDE.md）、设定安全边界（权限配置）、描述具体的预期结果，然后让 AI 在规则框架内自主完成任务。你是工程管理者，AI 是执行者。

关键转变：

维度	Vibe Coding	Agentic Engineering
描述方式	"帮我做个好看的登录页"	"创建一个登录页组件，包含邮箱和密码输入框，使用 React Hook Form 验证，错误状态显示红色提示文字"
质量控制	"看起来能用就行"	跑测试、看 Diff、检查覆盖率
知识沉淀	无（每次都是新对话）	CLAUDE.md 持续迭代，项目规则不断精炼
对 AI 的定位	魔法盒子	可预测的工程工具
长期成本	高（大量试错和返工）	低（精确指令减少重复）

---

实操步骤

步骤 1：自我诊断——你现在在哪个阶段？

诚实地回答以下问题（答案只有"是"或"否"）：

1. 我每次让 Claude Code 修改文件时都会仔细看 Diff 吗？

2. 我的 CLAUDE.md 不超过 150 行吗？

3. 我每完成一个会话都会用 /cost 查看消耗吗？

4. 我遇到"改了两次还不对"的情况会 /clear 重来而不是继续修补吗？

5. 我的权限配置是逐步调整的而不是一次性设置的？

6. 我会根据任务类型选择不同的模型吗？

如果 6 个问题中有 3 个以上回答"否"，说明你还有典型的"Vibe Coding"习惯。下一周的实践中有意识地改进这些点。

步骤 2：对照清单检查你的项目

打开你当前使用 Claude Code 最多的项目，逐项检查：

• CLAUDE.md 是否在 150 行以内？
• 每条规则是否"可验证"？
• .claude/settings.json 是否包含 deny 规则？
• deny 规则是否使用了正确的通配符？
• 敏感文件（.env, *.pem, *.key）是否在保护范围内？
• Git 破坏性操作是否被禁止？
• 最近 5 次会话是否都用了 /cost？

步骤 3：写一份"避坑总结"——建立个人最佳实践

基于你过去一周使用 Claude Code 的经验，写一份属于你自己的"5 条铁律"。例如：

我的 Claude Code 铁律：
1. 每次 Approve 前必须看 Diff（超过 10 行去 VSCode 看）
2. 如果 AI 两次没改对，/clear 重来
3. 每天结束时用 /cost 记录当日消耗
4. 不在同一个会话中处理超过 3 个不相关的任务
5. 新项目第一天永远不放开权限

你的铁律可能和别人的不同——没关系。重要的是它们是你自己的经验总结，所以你会真正遵守。

---

避坑指南

本节就是避坑指南本身——但这里有三条"元避坑建议"：

避坑建议 1：不要试图一天改掉所有坏习惯

一口气读完本节的 10 个错误，试图明天全部改正，结果一个都没坚持下来。

正确做法：每周专注改进 2 个方面。第一周专注 CLAUDE.md 精炼和 Diff 审查；第二周专注权限配置和模型选择；第三周专注会话管理和成本控制。

避坑建议 2：不要照搬别人的配置

网上找到的 settings.json 或 CLAUDE.md 模板可能不适合你的项目。别人的 "Allow" 规则在你手里可能是安全隐患。

正确做法：理解每个配置项的含义，然后从零开始逐步构建。模板可以作为参考，但不能直接复用。

避坑建议 3：不要因为一次翻车就放弃权限控制

某次你设置了严格的权限，觉得"太烦了每次都要确认"，于是一气之下全部 Allow。这种"全或无"的思维是最大的安全风险。

正确做法：权限系统的摩擦感是好事——它在提醒你 AI 正在做一个可能产生后果的操作。你应该学会分辨哪些摩擦是无意义的（读文件、运行测试），哪些摩擦是必要的（修改数据库、删除文件），然后针对性地调整。

---

课后作业

1. 自我审计：用本节的 TOP 10 错误清单逐项检查你过去一周的 Claude Code 使用记录。找出你最常犯的 3 个错误，写在便利贴上贴到显示器旁边。

2. CLAUDE.md 精炼：打开你的 CLAUDE.md，删除所有模糊的、不可验证的、过时的规则。目标：从当前行数减到 150 行以内。

3. 成本分析：登录 Anthropic Console 的 Usage 页面，分析过去 30 天的 API 消费。找出花费最高的 3 天，回忆那天做了什么任务。思考：如果用 Haiku 替代某些任务，能省多少钱？

4. 铁律制定：写一份你的"个人 Claude Code 使用铁律"（5 条），放在 ~/.claude/CLAUDE.md 的顶部。

---

总结

从新手到熟练 Claude Code 用户，本质上是完成两个转变：

第一个转变：从"它能做什么"到"我应该怎么让它做"

新手关心 Claude Code 能做什么（改文件、跑命令、搜代码），而熟练用户关心的是如何用 CLAUDE.md 约束它、用权限系统保护自己、用会话管理提高效率。

第二个转变：从"Vibe Coding"到"Agentic Engineering"

Vibe Coding 是"感觉对了就行"的试错模式，Agentic Engineering 是"定义规则、设置边界、审查结果"的工程模式。两者的差距不在于技术能力，而在于你是否把 AI 当成一个需要管理的工程工具。

本课程的 Level 1（零基础入门）到此结束。你学到的不是"Claude Code 有哪些功能"——这你可以从文档中查询——而是"如何安全、高效、专业地使用 Claude Code 完成真正的编程工作"。这是 Level 2（进阶实战）的基础。

祝你在 Agentic Engineering 的路上越走越稳。