Claude Code 新手实战手册

# Claude Code 完整教程

我做软件工程师已有 7 年，先后在 Amazon、Disney 和 Capital One 任职。我交付的代码触达了数百万用户，我构建的系统容不得任何故障。如今我是一家初创公司的 CTO，专门为企业构建 AI 智能体，而 Claude Code 是我每天都在使用的主力工具。

以下是一份面向初学者的实战手册，汇集了我使用 Claude Code 为大型企业构建能够处理复杂工作负载的健壮系统所积累的全部经验。如果对你有帮助，欢迎在下方告诉我。

## 先思考

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

十次里有十次，我在计划模式下得到的输出，都远优于我直接开口把所有内容倾倒给 Claude Code 的结果。差距不是一点点。

对于部分人来说，这说起来容易做起来难。你可能并没有多年的软件工程经验，难以独立完成这样的思考。对此我有两条建议：
1. 开始学习。如果你完全不涉猎这方面的知识，哪怕只是一点一滴地积累，你也是在给自己设置障碍。

2. 与 ChatGPT/Gemini/Claude 进行深度来回对话：详细描述你想构建的内容，请 LLM 列出你在系统设计上可以选择的各种方案，最终你们共同确定一个解决方案。你和 LLM 应该互相提问，而不是单向输出。

这一原则适用于所有事情，包括像汇总邮件这样非常小的任务。在你要求 Claude 构建某个功能之前，先思考架构；在要求它重构某些内容之前，先想清楚最终状态应该是什么样的；在要求它调试之前，先想清楚你对这个问题实际了解多少。你在计划模式中掌握的信息越多，输出结果就越好，因为输入的质量会更高。

这一规律始终如一：先思考再动手，比先动手再指望 Claude 自己想明白，能产生显著更好的结果。

这自然引出我下一个要点：架构。软件工程中的架构，有点像只给一个人看结果而不给任何其他信息。这为如何达到这个结果留下了大量的自由发挥空间，而这本质上正是 AI 生成代码所存在的问题所在。如果你说的是泛泛而谈的"帮我构建一个认证系统"，而不是"使用现有的 User 模型构建邮箱/密码认证，将会话存储在 Redis 中并设置 24 小时过期时间，并添加中间件保护所有 /api/protected 路径下的路由"，你可以看出两者的差异。

按两下 Shift + Tab，你就进入了计划模式。相信我，这会花你 5 分钟时间，但能为你节省后续数小时的调试时间。

## CLAUDE.md（http://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 会开始随机忽略某些内容，而你根本不知道被忽略的是哪些。

**让内容与你的项目息息相关。** 不要解释什么是 components 文件夹。Claude 知道什么是组件。告诉它那些奇特的东西，比如真正重要的 bash 命令。你工作流中的一切都应该写进去。

**说明原因，而不仅仅是要做什么。** Claude 在这一点上有点像人类。当你给出指令背后的理由时，Claude 的执行效果会比你只告诉它该做什么更好。"使用 TypeScript 严格模式"还可以。"使用 TypeScript 严格模式，因为我们曾在生产环境中因隐式 any 类型而遭遇 bug"则更好。原因为 Claude 提供了背景，帮助它在你未预料到的情况下做出正确判断。这实际上有多有效，会让你大吃一惊。

**持续更新它。** 在工作时按下 # 键，Claude 会自动将指令添加到你的 CLAUDE.md 中。每当你发现自己对同一件事纠正了 Claude 两次，那就是一个信号——这件事应该写入文件。随着时间推移，你的 CLAUDE.md 会成为一份记录代码库实际运作方式的活文档。

糟糕的 CLAUDE.md 看起来像写给新员工的文档。好的 CLAUDE.md 看起来像你知道自己明天会失忆，所以给自己留下的笔记。

## 上下文窗口的局限性

举个例子，Opus 4.5 拥有 200,000 个 token 的上下文窗口。但大多数人没有意识到的是：模型的质量在达到 100% 之前就已经开始下降了。（这取决于你是通过 API 还是桌面应用使用，情况会有所不同）

大约在上下文使用率达到 20-40% 时，输出质量就开始悄悄下滑，即便一开始并不明显。如果你曾经历过 Claude Code 执行压缩之后依然给出糟糕输出的情况，这就是原因所在。在压缩发生之前，模型已经处于退化状态，而压缩并不能神奇地恢复质量。（输入 /compact 可执行压缩）

你发送的每一条消息、Claude 读取的每一个文件、它生成的每一段代码、每一个工具调用的结果——这一切都在不断累积。一旦质量开始下降，更多的上下文只会让情况更糟，而不是更好。所以，以下是一些真正有助于避免上下文变得糟糕的方法：

**限定对话范围。** 每个功能或任务单独开一个对话。不要在同一个对话中既构建你的身份验证系统，又重构你的数据库层。这些上下文会互相干扰，让 Claude 感到混乱。我知道你们中至少有一个人读到这里时心虚了。

使用外部记忆。如果你在处理复杂的事情，让 Claude 将计划和进度写入实际文件（我用 SCRATCHPAD.md 或 plan.md）。这些文件在多个会话之间持续存在。明天当你回来时，Claude 可以读取文件并从上次停下的地方继续，而不是从零开始。附注：如果你有文件层级系统，将这些文件保留在最顶层，就能让它们对你决定构建的每一个任务/功能都生效。

复制粘贴重置法。这是我经常使用的技巧。当上下文变得臃肿时，我会把终端中所有重要的内容复制下来，运行 /compact 获取摘要，然后用 /clear 彻底清除上下文，再把真正重要的内容粘贴回去。保留了关键信息的全新上下文，比让 Claude 在退化的上下文中挣扎要好得多。

知道何时清除。如果一段对话已经跑偏，或者积累了一堆无关的上下文，直接 /clear 重新开始。这比试图在混乱中硬撑要好。Claude 仍然会有你的 CLAUDE.md，所以你不会丢失项目上下文。十次中有九次，使用 clear 实际上比不使用更好，尽管听起来违反直觉。

有效的心智模型：Claude 是无状态的。每次对话都从零开始，除非你明确提供信息。请据此做好规划。

## 提示词就是一切

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

提示词不是什么神秘的艺术，它可能是最基本的沟通方式。就像任何沟通一样，表达清晰永远比含糊其辞获得更好的结果。每一次，无一例外。

真正有帮助的是：

明确说明你想要什么。"构建一个身份验证系统"给了 Claude 创作自由，而它会用得很糟糕。"使用现有的 User 模型构建邮箱/密码身份验证，将 session 存储在 Redis 中，并添加保护 /api/protected 路径下路由的中间件"才给了 Claude 一个清晰的目标。即便如此，这仍然还不够完美。

告诉它不要做什么。Claude 有自己的倾向。Claude 4.5 尤其喜欢过度设计——多余的文件、不必要的抽象、你没有要求的灵活性。如果你想要简洁，就说"保持简单。不要添加我没有要求的抽象。尽可能用一个文件。"另外，始终要对照检查 Claude 生成的内容，因为你不想背上技术债务，尤其是当你在构建非常简单的东西时，它最终却为一个实际上几行代码就能解决的任务建出了 12 个不同的文件。

你必须记住的一点是，AI 是为了加速我们而设计的，而不是完全取代我们，尤其是在非常专业的软件工程领域。Claude 仍然会犯错误。我相信它会继续犯错，即使它会随着时间推移不断改进。因此，能够识别这些错误实际上会解决你的很多问题。

给它提供关于"为什么"的上下文。"我们需要这个很快，因为它在每次请求时都会运行"会改变 Claude 处理问题的方式。"这是一个我们会丢弃的原型"会改变什么样的权衡是合理的。Claude 无法读取你对于那些你没有提及的约束条件的想法。

记住：输出就是一切，但输出只来源于输入。如果你的输出很糟糕，那是因为你的输入很糟糕。这一点无从回避。

## 坏的输入 == 坏的输出

人们在得到糟糕结果时会责怪模型。"Claude不够智能"或"我需要一个更好的模型。"

现实检验：是你自己的问题。如果你在使用像Opus 4.5这样优秀的模型时仍然得到糟糕的输出，那意味着你的输入和提示词写得很差。就这么简单。

模型确实很重要。实际上，非常重要。但在当下，模型质量只是基本门槛。瓶颈几乎总是在人这一侧：你如何构建提示词，如何提供上下文，如何清晰地传达你真正想要的东西。

如果你持续得到糟糕的结果，解决方法不是换模型。解决方法是在以下方面变得更好：

**如何编写提示词。** 具体 > 模糊。有约束 > 开放式。举例 > 描述。

**如何构建请求。** 将复杂任务拆分成步骤。在实施之前先就架构达成一致。审查输出并迭代。

**如何提供上下文。** Claude需要了解什么才能把这件事做好？你做了哪些Claude看不到的假设？

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

Sonnet速度更快、成本更低。它非常适合执行路径明确的任务——编写样板代码、基于特定计划进行重构、实现你已经做出架构决策的功能。

Opus速度较慢、成本较高。它更适合复杂推理、规划，以及需要Claude深入思考权衡取舍的任务。

一个行之有效的工作流：使用Opus进行规划和架构决策，然后切换到Sonnet（在Claude Code中按Shift+Tab）来执行实施。这取决于你的任务，有时你也可以用Opus 4.5来做实施。不过，如果你通过API使用量标签来这样做，请考虑好你的肾脏是否还在。你的CLAUDE.md确保两个模型在相同的约束下运行，因此交接是顺畅的。

## MCP、工具与配置

Claude拥有大量功能。MCP服务器、钩子、自定义斜杠命令、Settings.json配置、技能、插件。

你不需要全部用上。但你确实应该去尝试和实验，因为如果你不去实验，你很可能在白白浪费时间或金钱。我可以保证，Claude肯定有至少一项你还不知道的新功能，如果你关注Claude Code的创始人Boris，你就能了解到这些功能。

MCP（模型上下文协议）让Claude能够连接外部服务——Slack、GitHub、数据库、API。如果你发现自己经常要把信息从某个地方复制粘贴给Claude，很可能已经有一个MCP服务器可以自动完成这件事。有大量的MCP市场可以选择，如果找不到现成的MCP，它本质上只是一种获取结构化数据的方式，所以你完全可以为任何当前不存在的所需工具自己创建一个MCP服务器。不过，如果你真的找不到现成的，我会非常惊讶。

钩子让你能够在Claude做出更改之前或之后自动运行代码。想让Prettier在Claude碰过的每个文件上都运行？用钩子。想在每次编辑后进行类型检查？用钩子。这样可以立即捕获问题，而不是让问题不断积累。这实际上也是帮助消除技术债务的方法。如果你在每一千行之后设置一个特定的钩子，让安全功能潜在地清理你的代码，这应该会非常有帮助，尤其是当Claude审查你的PR时。

自定义斜杠命令本质上就是将你反复使用的提示词打包成命令。创建一个 `.claude/commands` 文件夹，添加包含提示词的 Markdown 文件，之后就可以用 `/命令名` 来运行它们。如果你经常执行同类任务——调试、代码审查、部署——把它做成命令吧。

如果你订阅了 Pro Max 计划（我每月付 200 美元），为什么不把 Claude 的所有功能都试一遍？看看哪些有用，哪些没用。反正钱已经花了。

还有一点：某个功能第一次没跑通，别就此放弃。这些模型基本上每周都在进步。一个月前不奏效的东西，现在可能已经没问题了。成为早期用户，意味着保持好奇心，不断重新测试。

## 当 Claude 卡住时

有时候 Claude 就是会陷入循环。它反复尝试同一件事，失败，再试，再失败，周而复始。或者它满怀信心地实现了一个完全错误的东西，你花了二十分钟解释为什么不对。

遇到这种情况，本能反应是继续施压——更多指令、更多纠正、更多上下文。但现实是，更好的做法是彻底换一个思路。

从最简单的开始——清空对话。累积的上下文可能正在干扰它。`/clear` 让你重新开始。

简化任务。如果 Claude 在处理一个复杂任务时遇到困难，就把它拆成更小的部分，逐一搞定再组合。但说实话，如果 Claude 在复杂任务上卡壳，说明你的计划模式做得不够充分。

示范胜于说教。如果 Claude 一直误解你的意图，自己写一个最简示例。"这是期望的输出结果，现在把这个模式应用到其余部分。"Claude 非常善于理解成功标准，也非常擅长跟着一个好例子走。

发挥创意，换个角度。有时候你组织问题的方式和 Claude 的思维方式对不上。换一种表述——"把它实现为状态机"而不是"处理这些状态转换"——往往能打开局面。

这里的元技能在于：尽早识别出自己陷入了循环。如果你把同一件事解释了三遍，Claude 还是没明白，继续解释也没用。换个方法。

## 构建系统

从 Claude 身上获益最多的人，不是把它用于一次性任务，而是在构建以 Claude 为组件的系统。但 Claude Code 远不止于此。它有一个 `-p` 标志，用于无头模式（headless mode）。它执行你的提示词并输出结果，无需进入交互界面。这意味着你可以用脚本驱动它，将输出通过管道传给其他工具，与 bash 命令链式组合，集成到自动化工作流中。

企业正在用它做：自动 PR 审查、自动支持工单回复、自动日志记录和文档更新。一切都有日志可查、可审计，并根据效果持续优化。

这就是飞轮效应：Claude 犯了个错，你查看日志，改进 CLAUDE.md 或工具配置，Claude 下次表现更好。这会不断复利叠加。我目前正在研究让 Claude 自主改进自己的 Claude.md 文件。经过数月迭代，这样构建的系统比刚上线时明显更强——模型还是同一个，只是配置得更好了。

如果你只是在交互式地使用 Claude，你正在白白浪费价值。想想你的工作流里，哪些地方 Claude 可以在无人值守的情况下独立运行。

## 内容摘要

先思考，再动笔。做好规划，效果会比直接开口说话好得多。

CLAUDE.md 是你的杠杆所在。保持内容简短、具体，说明原因，并持续更新。这一个文件会影响你的每一次交互。

上下文在 30% 时就开始衰减，而不是到 100% 才出问题。使用外部记忆、控制对话范围，并且不要害怕清空重来——善用复制粘贴重置技巧。

架构比任何事都重要。规划这一步不可跳过。如果你不先理清结构，输出结果就会很差。

输出质量取决于输入质量。如果你用着优质模型却得到糟糕结果，问题出在你的提示上。学会更好地表达你的需求。

多尝试工具和配置。MCP、钩子、斜杠命令——如果你已经订阅了 Pro Max，什么都值得试试。即使第一次不奏效，也保持好奇心。

卡住了就换思路。不要在原地打转。清空、化简、展示、换个角度重新表述。

构建系统，而非一次性输出。无头模式、自动化、随时间积累的有记录改进——这才是正道。

如果你正在用 Claude 搭建东西——无论是个人项目还是生产系统——以上这些，才是决定你究竟是在与工具对抗，还是与它共舞的关键所在。

当今的技术能力强大得令人咋舌。如果你想获得更多关于如何为自己或业务最大化利用 AI 的技巧，欢迎订阅我的免费每周 AI newsletter：https://varickagents.com/newsletter