Claude Code实践2：《The complete claude code tutoria》阅读心得

作者是前亚马逊、迪士尼资深工程师使用claude code的经验，干货满满，推荐阅读原文

原文地址：

https://x.com/eyad_khrais/status/2010076957938188661

https://x.com/eyad_khrais/status/2010810802023141688

以下是自己的一个阅读心得，分享给大家

核心原则：思维先行，规划为王

从两篇教程中，给我非常有启发的、也是最重要的原则是：先思考，后输入。我们习惯于直接向AI工具抛出问题，期待它能神奇地解决一切。但这恰恰是最高效使用Claude Code的最大误区。

作者强调，在使用“规划模式”（Plan Mode）下得到的输出质量，远胜于直接对话。这背后的逻辑是，高质量的输入决定了高质量的输出。在动手编码或向Claude提问前，我们应该像一个经验丰富的软件工程师一样进行思考：

• 目标是什么？ 我要构建的功能最终应该是什么样子？

• 架构如何设计？ 有哪些技术选型？数据如何流转？

• 已知信息有哪些？ 如果是调试，我已经掌握了哪些线索？

这个“先思考”的步骤，为AI提供了一个清晰、结构化的蓝图，而不是一堆模糊、零散的想法。即使对于没有深厚工程背景的使用者，也可以通过与AI进行深入的“设计对话”来共同完成规划，明确系统设计的各种选项，最终敲定一个解决方案。

实践建议：在开始任何复杂任务前，按下 Shift + Tab 两次进入规划模式。花五分钟时间梳理你的思路，这会为你节省数小时的调试和返工时间。

“架构，尤其是在软件工程中，有点像只给人一个输出结果，除此之外别无其他。这在如何达成该结果上留下了很大的灵活空间，而这本质上正是 AI 生成代码的问题所在。如果你说一些非常宽泛的话，比如‘给我建一个认证系统’，而不是‘使用现有的 User 模型构建邮箱/密码认证，将会话存储在 Redis 中并设置 24 小时过期，并添加中间件来保护所有位于/api/protected 下的路由’，你就能看出其中的区别”

作者在这里也想的很周到，如果一些使用者没有多年的软件工程经验，无法独立进行这样的思考，蓝图设计不出来，作者给出的方法是1. 现在开始学习这方面；2.和AI互动深度交流，咨询在系统设计方面可以采取的各种方案。

作者在文章提了一嘴，但我个人感觉很重要，即要让AI来给你提问题、提需求，其实我认为这种思维方式的转变会强迫我们先进行思考设计，再去和AI互动。

项目的“第二大脑”：精通 CLAUDE.md

CLAUDE.md 文件是项目级配置的核心，它就像是Claude在处理你项目前必读的“入职培训材料”。大多数人要么忽略它，要么塞满无关紧要的信息，反而降低了模型表现。一份优秀的 CLAUDE.md 应遵循以下原则：

1. 保持简洁：Claude的注意力是有限的。将指令控制在关键范围内（教程建议总指令数不超过150-200条），冗长的文件会导致Claude随机忽略某些内容。

2. 说明项目特性：不要告诉Claude它已经知道的通用知识（如“什么是组件”）。而是要告诉它项目的“怪癖”和特殊规则，比如特定的bash命令、代码库的非标准结构等。

3. 解释“为什么”：提供指令背后的原因能极大地提升执行效果。例如，不说“使用TypeScript严格模式”，而说“使用TypeScript严格模式，因为我们曾因隐式any类型导致生产环境bug”。“为什么”能赋予Claude在面对意外情况时做出正确判断的上下文。

4. 持续更新：CLAUDE.md 是一个动态文档。每当你发现自己重复纠正Claude同一个问题时，就应该将这个规则添加到文件中（可使用 # 键快捷添加）。

   “每当你发现自己就同一件事纠正 Claude 两次时，这就是一个信号——这件事应该写进文件。随着时间的推移，你的 CLAUDE.md 会成为记录代码库实际工作方式的动态文档”。

核心比喻：糟糕的 CLAUDE.md 像写给新员工的文档；优秀的 CLAUDE.md 像你写给明天将会失忆的自己的笔记——直击要点，充满关键上下文。

上下文管理：保持对话清晰高效

模型的性能在上下文窗口远未填满时（约20%-40%）就开始下降。一旦上下文质量开始衰退，继续增加信息只会让情况更糟。有几个实用的上下文管理技巧：

• 限定对话范围：一个对话只专注于一个功能或任务。不要在同一个对话中既构建认证系统又重构数据库，这会导致上下文混淆。

• 利用外部记忆：对于复杂任务，让Claude将计划和进展写入外部文件（如 PLAN.MD 或 SCRATCHPAD.MD）。这样，即使开启新的会话，Claude也能通过读取文件快速接续之前的工作。

• “复制粘贴重置法”：当对话变得臃肿时，复制关键信息，运行 /compact 获取摘要，然后运行 /clear 彻底清空上下文，最后只粘贴回最重要的信息。这能让你在保留核心上下文的同时，获得一个全新的、干净的运行环境。

• 果断清空 (/clear)：如果对话已经偏离轨道，不要犹豫，直接清空重来。这远比在混乱中挣扎要高效。由于 CLAUDE.md 依然存在，你并不会丢失项目的核心背景。

---

前面我们知道了由于模型厂家考虑到成本和性能等问题，不可避免地出现长上下文问题，就像是给我们限定了边界，在此边界内发挥模型的最大效用，进而就出现了如何优化的问题。

而Claude Code中的Skills、Subagents、MCP组合起来可以解决问题，从一个聊天机器人提升为一个可扩展的开发系统。

Skills（技能）：封装你的专业知识

技能（Skill）是一个Markdown文件，用于教会Claude如何执行你工作中的特定任务。它的核心是“渐进式披露”：Claude启动时只加载技能的名称和描述，仅在识别到任务与某个技能相关时，才会加载其完整指令。

如何创建和使用：

• 在 ~/.claude/skills/ 或项目的 .claude/skills/ 目录下创建技能文件夹。

• 核心是 SKILL.md 文件，包含YAML元数据（name和description）和具体的Markdown指令。

• description 至关重要，它是Claude决定何时触发该技能的依据。要写得具体，明确触发条件。

例如，你可以创建一个commit-messages技能，用于规范团队的Git提交信息格式。这样，每当需要生成提交信息时，Claude会自动应用这个规范，无需你反复说明。

Skill.md 要简洁，保持描述在 50 字以内。如需更多上下文，先空一行再写正文。这种格式起初写起来会有些别扭（因为你通常习惯写听起来自然的句子），但质量差异是显而易见的。如果技能中有参考资料，将参考资料另建一个文件夹，在Skill中引用。

Subagents（子代理）：隔离上下文，处理复杂任务

子代理（Subagent）是拥有独立上下文窗口、系统提示和工具权限的Claude实例。这是解决复杂任务中上下文污染问题的终极方案。主对话将任务委托给子代理，子代理在全新的环境中独立执行，然后仅将结果摘要返回给主对话。

架构优势：

• 保持主对话清洁：复杂的研究、重构或测试任务被外包出去，主对话只保留关键决策和结果。

• 专业分工：可以创建不同角色的子代理，如“安全审查员”、“测试生成器”、“代码重构师”等，每个代理都有自己专属的指令和工具集。

• 任务链式调用：主代理可以编排多个子代理，形成一个工作流。例如，先调用“探索”代理分析代码，再调用“实现”代理编写功能，最后调用“测试”代理验证结果。作者还强调，可以主代理编排多个子代理，但避免子代理中嵌套子代理，这么做是为了保持架构的可预测性，虽然我不知道原理，前人踩过的坑直接拿来用吧。

MCP（模型上下文协议）：解决长上下文问题

MCP (Model Context Protocol) 是一个统一的接口，让Claude能够与外部服务（如GitHub、Jira、Slack、数据库）进行“对话”。这意味着你可以直接在Claude界面中完成过去需要频繁切换应用才能完成的工作。

实际应用场景：

• “根据JIRA问题ENG-4521的描述添加该功能”

• “从我们的PostgreSQL数据库中查找上周注册的用户”

• “总结一下#engineering频道关于API重新设计的讨论结果”

通过连接MCP服务器，开发者可以将整个工作流程——从需求理解、信息检索到代码实现和工单更新——整合在一个连续的会话中，极大地提升了专注度和效率。

真正的力量不在于任何单一集成

构建高效工作流：从工具到系统

两篇教程最核心的升华在于，促使我们将Claude Code的认知从一个“一次性任务处理器”转变为一个“可倍增工作能力的系统”。

作者原话是这样说的“这一切在此汇聚融合：掌握代码库模式的技能 + 处理测试的子代理 + 连接问题追踪系统的 MCP = 构建出无可匹敌的协同体系。”

真正的力量不在于任何单一功能，而在于将它们组合起来：

• Skills 编码了团队的规范和最佳实践。

• Subagents 在隔离环境中高效处理复杂的子任务，防止上下文污染。

• MCP 连接了外部信息源，消除了应用切换带来的心智负担。

一个高效的工程师会投入时间去配置这个系统：创建符合团队规范的技能，定义针对特定任务的子代理，连接日常工作流中依赖的服务。这种前期的“投资”，会在后续的每一个开发任务中以数倍的效率作为“红利”回报。

“我观察到的那些从 Claude Code 中获益最多的工程师，并不是用它来处理一次性任务，而是将其视为一个能倍增工作能力的系统。他们投入时间配置技能、定义子代理、连接服务。这种投入会在后续的每项任务中带来应有的回报。

如果你对从何开始感到迷茫，不妨先从一个你反复解释的事情入手，创建一项技能。或者先创建一个单独的代理。然后进行测试，并在此基础上逐步推进。不必试图一次性尝试所有功能而让自己不堪重负。”

常见陷阱与反思：问题出在人而非模型

当输出结果不佳时，我们的第一反应往往是“模型不够好”。但作者尖锐地指出：如果你用的是像Opus 4.5这样的顶级模型，问题几乎总是出在人类这边。

• 陷阱：输入模糊，期望AI能读懂你的心。

• 反思：提供具体的、带约束的指令，并附上示例。

• 陷阱：将所有任务堆在同一个无限长的对话中。

• 反思：为每个任务开启新的对话，并善用/clear和子代理。

• 陷阱：责怪模型过度工程化或产生技术债务。

• 反思：在提示中明确告知“不要做什么”（如“保持简单，不要添加我未要求的抽象”），并始终交叉核对AI的输出。

只需要记住

通读这两份教程后，我最大的收获是思维模式的转变。高效使用AI开发工具，不仅仅是学会如何提问，更是学会如何设计和构建一个与AI协作的系统。这需要我们投入时间去理解其工作原理，配置其行为，定义其能力。

从最初的“先思考，后输入”，到利用CLAUDE.md建立项目共识，再到通过Skills、Subagents和MCP构建自动化工作流，每一步都是在减少沟通摩擦，提升协作效率。最终，开发者得以从繁琐的上下文切换和重复性工作中解放出来，长时间保持在高效、专注的“心流”状态。这，或许就是AI时代赋予开发者的最大红利。

1. 磨刀不误砍柴功，先思考再提问；先规划再执行

2. 让AI提需求、提问题

3. 构建Skill和agent：简洁、精要

4. 构建系统而非工具

Claude Code实践2：《The complete claude code tutoria》阅读心得