Claude Code 101实战指南

图像

这篇火爆英文区 100 万流量的 Claude code 101 教程文章。

下面是全文翻译：

做了 7 年软件工程师（SWE），曾在亚马逊、迪士尼和 Capital One 任职。我上线的代码服务于数百万用户，构建过绝不允许崩溃的关键系统。

现在，是一家为企业构建 Agent 的初创公司的 CTO，而 Claude Code 是我日常的主力工具。

这是一份新手实战手册，包含了我在使用 Claude 为大公司构建处理复杂工作负载的稳健系统时，所学到的关于它的一切。希望它能对你有所帮助。

先思考，再动手

大多数人认为，使用 Claude Code 或其他 AI 工具时，第一件事就是打字（或开始说话）。这可能是你一开始能犯的最大错误。实际上，你需要做的第一件事是思考。

每一次（10 次里有 10 次），使用规划模式 (Plan Mode) 得到的结果，都明显优于我直接开始对着 Claude Code 一股脑输出的时候。差距甚至不是一点半点。

对于你们中的一些人来说，这可能说起来容易做起来难。你可能没有多年的软件工程经验来支持你独立思考架构。

对此，有两条建议：

• 开始学习。 如果你从未开始培养这种思维，哪怕只是一点点，你都是在给自己设限（自废武功）。
• 与 ChatGPT/Gemini/Claude 进行深度的来回对话。 描述你想构建什么，询问 LLM 在系统设计方面有哪些选项，最终你们共同确定一个解决方案。你和 LLM 应该互相提问，而不是单向的指令输出。

这适用于所有事情，包括像总结邮件这样的小任务。

在你要求 Claude 构建功能之前，先考虑架构。在你要求它重构之前，先想好终态应该是什么样。在你要求它调试之前，先思考你对这个问题实际上了解多少。你在规划模式下拥有的信息越多，输出的质量就越好，因为输入的质量提高了。

这个模式是一致的：先思考，后打字，所产生的结果要比“先打字并指望 Claude 自己搞定”好得多。

这引出了我的下一个关于架构的观点。架构，特别是在软件工程中，有点像只给一个人输出结果，而不给过程。

这留下了太大的操作空间，而这正是 AI 生成代码的问题所在。如果你说得很宽泛，比如“给我做一个认证系统”，而不是说“使用现有的 User 模型构建邮箱/密码认证，将 session 存储在 Redis 中并设置 24 小时过期，并添加中间件保护 /api/protected 下的所有路由”，你可以看到其中的区别。

按两次 Shift + Tab，你就会进入规划模式（Plan Mode）。 相信我，这会花费你 5 分钟的时间，但会为你以后节省数小时的调试时间。

CLAUDE .md

CLAUDE .md是一个 Markdown 文件。Markdown 是一种 AI 模型处理得非常好的文本格式，而 Claude 对它的处理尤其出色。

当你启动 Claude Code 会话时，Claude 做的第一件事就是读取你的 CLAUDE .md文件。该文件中的每一条指令都会影响 Claude 处理你项目的方式。它本质上是 Claude 每次对话前的入职材料。

大多数人要么完全忽略它，要么在里面塞满垃圾信息，导致 Claude 表现更差而不是更好。这里有一个阈值，信息太多或太少都会导致模型输出变差。

以下是真正重要的几点：

• 保持简短。 Claude 只能可靠地遵循大约 150 到 200 条指令，而 Claude Code 的系统提示词已经占用了大约 50 条。你添加的每一条指令都在争夺它的注意力。如果你的 CLAUDE .md像本小说，Claude 就会开始随机忽略内容，而你根本不知道它忽略了哪些。
• 针对项目具体化。 不要解释什么是组件文件夹。Claude 知道什么是组件。告诉它那些奇怪的东西，比如真正重要的 bash 命令。任何属于你工作流一部分的内容都应该放进去。
• 告诉它“为什么”，不仅仅是“做什么”。 在这方面 Claude 有点像人。当你给出指令背后的原因时，Claude 的执行效果比你只告诉它做什么要好。“使用 TypeScript 严格模式”是可以的。但“使用 TypeScript 严格模式，因为我们曾因隐式 any 类型导致过生产环境 Bug”更好。“为什么”给了 Claude 上下文，让它能做出你未曾预料到的判断。你会惊讶于这实际上有多有效。
• 持续更新。 工作时按 # 键，Claude 会自动将指令添加到你的 CLAUDE .md中。CLAUDE .md

每当你发现自己需要在同一件事上纠正 Claude 两次时，这就是一个信号：它应该被写进文件里。随着时间的推移，你的 CLAUDE .md 会成为你代码库实际运作方式的活文档。

糟糕的CLAUDE .md看起来像给新员工写的文档。优秀的 CLAUDE .md看起来像是如果你知道明天会失忆，留给自己的笔记。

上下文窗口的局限性

Opus 4.5 有 200,000 token 的上下文窗口。但大多数人没有意识到的是：模型在达到 100% 之前很久就已经开始退化了。（这取决于你是通过 API 使用还是桌面应用）。

大约在 20-40% 的上下文使用率时，输出质量就开始受损，即使不算太严重。如果你经历过 Claude Code 进行压缩（compacting）后仍然给出糟糕的输出，这就是原因。模型在压缩发生之前就已经退化了，而压缩并不能神奇地恢复质量。（注：输入 /compact 进行压缩）。

你发送的每一条消息、Claude 读取的每一个文件、它生成的每一段代码、每一个工具结果——所有这些都在累积。一旦质量开始下降，更多的上下文只会让情况变糟，而不是变好。

以下是一些真正有助于避免糟糕上下文的方法：

• 限定对话范围。 每个功能或任务一个对话。不要用同一个对话来构建你的认证系统，然后又用它来重构数据库层。上下文会混在一起，Claude 会感到困惑。我知道你们中至少有一个人在读这段话时感到中枪了。
• 使用外部记忆。 如果你在处理复杂的事情，让 Claude 把计划和进度写入实际的文件中（我使用 SCRATCHPAD .md 或 plan .md）。这些文件跨会话持久存在。当你明天回来时，Claude 可以读取文件并从你停下的地方继续，而不是从零开始。注：如果你有文件层级系统，把这些文件放在最顶层，这样你决定的每个任务/功能都能用到它们。
• 复制粘贴重置法。 这是我经常用的技巧。当上下文变得臃肿时，我会从终端复制所有重要的内容，运行 /compact 获取摘要，然后 /clear 完全清空上下文，只把重要的内容粘贴回去。保留了关键信息的全新上下文，比让 Claude 在退化的上下文中挣扎要好得多。
• 知道何时清空。 如果对话已经跑偏或积累了一堆不相关的上下文，直接 /clear 重新开始。这比试图在混乱中工作要好。Claude 仍然拥有你的 CLAUDE.md，所以你不会丢失项目背景。十次有九次，使用 clear 实际上比不使用要好，尽管这听起来违反直觉。

有效的思维模型：Claude 是无状态的 (Stateless)。 每次对话都是从零开始，除了你明确给它的东西。据此进行规划。

提示词决定一切

人们花数周时间学习框架和工具。却花零时间学习如何与那个实际生成代码的东西进行沟通。

提示工程（Prompting）不是什么玄学。它可能是最基本的沟通形式。像任何沟通一样，清晰总比含糊能带来更好的结果。每一次都是如此。

真正有用的做法：

• 明确你想要的。 “构建一个认证系统”给了 Claude 糟糕的创作自由。“使用现有的 User 模型构建邮箱/密码认证，将 session 存储在 Redis 中，并添加中间件保护 /api/protected 下的路由”给了 Claude 一个清晰的目标。即便这样也还不完美。
• 告诉它不要做什么。 Claude 有它的倾向。特别是 Claude 4.5 喜欢过度设计 (overengineer)——额外的文件、不必要的抽象、你没要求的灵活性。如果你想要极简的东西，说：“保持简单。不要添加我没要求的抽象。如果可能的话，用一个文件。” 另外，一定要交叉检查 Claude 生成的内容，因为你不想背上技术债，特别是如果你在构建非常简单的东西，结果它为了一个几行代码就能解决的任务生成了 12 个不同的文件。
• 你需要记住的是，AI 的设计初衷是加速我们，而不是完全取代我们，特别是在非常专业的软件工程时代。Claude 仍然会犯错。我确信它会继续犯错，即使它会随着时间推移变得更好。所以，能够识别这些错误实际上会解决你的很多问题。
• 提供关于“为什么”的上下文。 “我们需要这个很快，因为它在每个请求上运行”会改变 Claude 处理问题的方式。“这是一个原型，我们要扔掉的”会改变哪些权衡是有意义的。Claude 无法读懂你没提到的约束条件。

记住：输出就是一切，但它只源于输入。 如果你的输出很烂，那是你的输入很烂。这没法绕过去。

糟糕的输入 == 糟糕的输出

当得到糟糕的结果时，人们会责怪模型。“Claude 不够聪明”或者“我需要更好的模型”。

认清现实：是你不行（Reality check: you suck）。 如果你用像 Opus 4.5 这样的好模型却得到糟糕的输出，这意味着你的输入和提示词很烂。句号。

模型很重要。

实际上非常重要。但模型质量在目前只是入场券。瓶颈几乎总是在人这边：你如何构建提示词，如何提供上下文，如何清晰地传达你真正想要的东西。

如果你持续得到糟糕的结果，解决办法不是换模型。

解决办法是在以下方面做得更好：

• 你如何写提示词。 具体 > 含糊。约束 > 开放式。示例 > 描述。
• 你如何构建请求。 把复杂的任务分解成步骤。在实施之前先在架构上达成一致。审查输出并迭代。
• 你如何提供上下文。 Claude 需要知道什么才能做好这件事？你做了哪些 Claude 看不到的假设？

话虽如此，模型之间确实存在差异：

• Sonnet 更快更便宜。 它非常适合执行路径清晰的任务——编写样板代码、基于特定计划重构、实施你已经做出架构决策的功能。
• Opus 。 它更适合复杂的推理、规划，以及你需要 Claude 深入思考权衡的任务。

一个有效的工作流：使用 Opus 进行规划和架构决策，然后切换到 Sonnet（在 Claude Code 中按 Shift+Tab）进行实施。 这取决于你的任务，有时你也可以用 Opus 4.5 进行实施。不过如果你是通过 API 使用量计费的话，这样做之前先考虑去卖个肾。你的 CLAUDE.md确保两个模型在相同的约束下运行，所以交接是干净的。

MCP、工具和配置

Claude 有着多到离谱的功能。MCP 服务器、Hooks（钩子）、自定义斜杠命令、Settings.json 配置、Skills、插件。

你不需要所有这些。但你应该确实去尝试和实验，因为如果你不实验，你可能正在浪费时间或金钱。我向你保证，Claude 至少有一个你不知道的新功能正在发布，如果你关注 Claude Code 的创始人 Boris，你就能学到。

• MCP (Model Context Protocol) 让 Claude 连接到外部服务。Slack、GitHub、数据库、API。如果你发现自己不断从一个地方复制信息到 Claude，可能已经有一个 MCP 服务器可以自动完成这项工作。有很多 MCP 市场，如果没有现成的，MCP 只是获取结构化数据的一种方式，所以你可以为你需要的任何工具创建自己的 MCP 服务器。不过如果你找不到现成的，我会很惊讶。
• Hooks (钩子) 让你在 Claude 进行更改之前或之后自动运行代码。想在 Claude 触碰每个文件时运行 Prettier？用 Hook。想在每次编辑后进行类型检查？用 Hook。这能立即发现问题，而不是让它们堆积。这实际上也有助于消除技术债。如果你设置一个特定的 hook，比如每千行代码触发一次，你就拥有了潜在的安全特性来清理代码。当 Claude 审查你的 PR 时这应该非常有帮助。
• 自定义斜杠命令 只是你重复使用的提示词，打包成命令。创建一个 .claude/commands 文件夹，添加带有你提示词的 markdown 文件，现在你可以用 /commandname 运行它们。如果你经常运行同类任务——调试、审查、部署——把它做成一个命令。

如果你有 Pro Max 计划（我付 200 美元/月），为什么不尝试 Claude 提供的一切呢？看看什么有用，什么没用。反正你都付钱了。

还有一件事：不要因为第一次尝试不成功就放弃。这些模型基本上每周都在进步。一个月前不行东西现在可能行了。做一个早期采用者意味着保持好奇心并重新测试事物。

当 Claude 卡住时

有时 Claude 只是在死循环。它尝试同样的事情，失败，再试，失败，一直持续。或者它自信地实施了一些完全错误的东西，你花二十分钟试图解释为什么。

当这种情况发生时，本能是继续推进。更多指令。更多纠正。更多上下文。但现实是，更好的做法是完全改变方法。

• 从简单开始 - 清空对话。 积累的上下文可能会让它困惑。/clear 给你一个新的开始。
• 简化任务。 如果 Claude 在复杂任务上挣扎，把它分解成更小的部分。在组合它们之前先让每个部分工作。但实际上，如果 Claude 在复杂任务上挣扎，这意味着你的规划模式 (plan mode) 是不充分的。
• 展示而非讲述 (Show instead of tell)。 如果 Claude 一直误解你想要的，你自己写一个最小的例子。“输出应该看起来像这样。现在把这个模式应用到其余部分。” Claude 非常擅长理解成功指标是什么样子的，并且能够遵循好的示例。
• 要有创意。 尝试不同的角度。有时你构建问题的方式不能很好地映射到 Claude 的思维方式。重新构建——“把它作为一个状态机来实现” vs “处理这些转换”——可以解锁进展。

这里的元技能 (meta-skill) 是尽早识别你处于死循环中。如果你已经把同一件事解释了三遍 Claude 还是不懂，更多的解释也不会有帮助。改变一些东西。

构建系统

从 Claude 获得最大价值的人不仅仅是用它做一次性任务。他们在构建系统，而 Claude 是其中的一个组件。但 Claude Code 远不止于此。它有一个 -p 标志用于无头模式 (headless mode)。它运行你的提示词并输出结果，而无需进入交互界面。这意味着你可以脚本化它。将输出通过管道传输给其他工具。与 bash 命令串联。集成到自动化工作流中。

企业正在利用这一点进行自动 PR 审查、自动支持工单回复、自动日志记录和文档更新。所有这些都被记录下来，可审计，并根据什么有效、什么无效随着时间推移而改进。

飞轮效应： Claude 犯了一个错，你查看日志，你改进 CLAUDE.md 或工具，Claude 下次会做得更好。这会复利增长。我现在正在让 Claude 能够改进它自己的 CLAUDE.md 文件。经过几个月的迭代，以这种方式构建的系统比它们刚推出时要好得多——同样的模型，只是配置得更好。

如果你只在交互模式下使用 Claude，你就把价值留在了桌子上（浪费了价值）。思考一下在你的工作流中，哪里可以让 Claude 在你不盯着的情况下运行。

TLDR (太长不看版)

• 先思考再打字。 规划产生的结果比直接开始说话要好得多。
• CLAUDE.md是你的杠杆点。 保持简短、具体，告诉它“为什么”，并持续更新。这单个文件影响每一次交互。
• 上下文在 30% 时就开始退化，而不是 100%。 使用外部记忆，限定对话范围，并且不要害怕使用“复制粘贴重置”技巧来清空并重启。
• 架构比什么都重要。 你不能跳过规划。如果你不先想清楚结构，输出就会很烂。
• 输出源于输入。 如果你用好模型却得到坏结果，你的提示词需要改进。提升沟通能力。
• 尝试工具和配置。 MCP、Hooks、斜杠命令。如果你付了 Pro Max 的钱，尝试所有功能。即使第一次不成功也要保持好奇。
• 卡住时，改变方法。 不要死循环。清空、简化、展示示例、重新构建问题。
• 构建系统，而不是一次性任务。 无头模式、自动化、随时间推移的日志改进。

如果你正在用 Claude 构建东西——无论是你自己的项目还是生产系统——这些就是决定你是与工具对抗还是顺势而为的关键。