Claude Code 教程第二篇

Claude 代码教程Lever2

第一部分非常火爆，如果你错过了，请先阅读它 ，我从事软件工程师（SWE）已有 7 年，曾在亚马逊、迪士尼和第一资本工作。我发布的代码触及数百万用户。第一部分涵盖了大多数人常犯的基础知识，但这篇文章更深入地探讨了 Claude 代码底层系统，这些系统区分了熟练使用和卓越使用。

大多数人仍然不知道如何有效利用 3 个主要功能，即：技能（skills）、子代理（subagents）和 MCP 连接器（connectors）。所有这些功能都在文档中，唯一的问题是文档没有告诉你这些部分在实践中是如何组合在一起的，或者哪些配置对于实际工作真正重要。

接下来是我在每天使用这些系统构建生产软件后所学到的一切。其中一些我花了几周时间才弄清楚，还有一些是通过反复试验。希望这能为你节省一些时间。

上下文窗口问题（The Context Window Problem）

在我们深入研究高级功能之前，有一些基本的东西会影响其他一切。如果你正在使用多个 AI 编码工具，你可能认为它们都以相同的方式处理上下文（剧透警告：它们不一样）。根据 Qodo 工程团队的详细比较，Claude 代码提供了“更可靠和明确的 20 万 token 的上下文窗口”，而 Cursor 由于“内部为了性能或成本管理而进行的截断”，实际使用“通常达不到理论上的 20 万限制”。该系统应用了内部安全措施，会默默地减少你的有效上下文。我在第一部分中介绍了为什么上下文如此重要。

虽然你可能会因为 Cursor 有这些限制而感到恼火，但你必须明白，不同的工具针对不同的工作流程进行了优化。如果你正在处理大型、互连的代码库，你需要模型理解你的身份验证系统如何连接到你的 API 路由，以及这如何连接到你的数据库模式，那么这种上下文很重要。因此，对于较大的项目，我建议直接使用 Claude 代码。Claude 代码始终如一地提供完整的 20 万 token。

这也是我接下来要介绍的功能在 Claude 代码中特别有效的原因。技能、子代理和 MCP 连接都受益于拥有可预测的上下文。

技能（Skills）：教 Claude 你的特定工作流程

技能是一个 Markdown 文件，它教 Claude 如何做一些特定于你工作的事情。当你问 Claude 一些符合技能目的的问题时，它会自动应用该技能。结构非常简单。

1. 创建一个包含 SKILL.md 文件的文件夹：~/.claude/skills/your-skill-name/ SKILL.md
2. 或者，对于你想要与你的团队分享的特定于项目的技能：.claude/skills/your-skill-name/SKILL.md

每个 SKILL.md 都以 YAML frontmatter 开头：

name: code-review-standards

description: Apply our team's code review standards when reviewing PRs or suggesting improvements. Use when reviewing code, discussing best practices, or when the user asks for feedback on implementation.

描述 至关重要。Claude 使用它来决定何时应用该技能。具体说明触发条件。你也可以明确地告诉 Claude “利用 x 技能”，它就会这样做。但目标是让 Claude 识别何时需要自行利用该技能。

在 frontmatter 下面，用 Markdown 编写实际的指令。这是一个最小的示例：

---
name: commit-messages
description: Generate commit messages following our team's conventions. Use when creating commits or when the user asks for help with commit messages.
---

## Commit Message Format

All commits follow conventional commits:
- feat: new feature
- fix: bug fix
- refactor: code change that neither fixes nor adds
- docs: documentation only
- test: adding or updating tests

Format: `type(scope): description`

Example: `feat(auth): add password reset flow`

将描述保持在 50 个字符以下。如果需要更多上下文，添加一个空行，然后添加正文。起初以这种格式编写会有些尴尬（因为编写听起来正常的英语句子是你通常的做法），但质量上的差异是显而易见的。

关键的架构原则是渐进式披露（progressive disclosure）。Claude 在启动时仅预加载每个已安装技能的名称和描述（大约每个 100 个 token）。只有当 Claude 确定相关技能时，才会加载完整的指令，这意味着你可以拥有数十个可用技能而不会使你的上下文膨胀。

你可以将支持文件添加到你的技能文件夹中。如果你有大量的参考资料，将其放在一个单独的文件中，并在 SKILL.md 中引用它。Claude 只会在需要时读取它。

还要注意，技能不仅限于代码。我见过工程师为以下内容构建技能：

• 特定于其模式的数据库查询模式

• 其公司使用的 API 文档格式

• 会议记录模板

• 甚至个人工作流程，如膳食计划或旅行预订

这种模式适用于任何你发现自己反复向 Claude 解释相同的上下文或偏好的情况。

要查看当前加载了哪些技能，直接问 Claude：“What skills do you have available?”它会列出它们（或者转到设置 → 功能 → 向下滚动，你就会看到技能）

子代理（Subagents）：具有隔离上下文的并行处理

子代理是一个独立的 Claude 实例，具有其自己的上下文窗口（context window）、系统提示（system prompt）和工具权限（tool permissions）。这是 Claude 代码的架构真正与众不同的地方。当 Claude 委托给一个子代理时，该子代理独立运行，并将摘要返回给主对话。

重要的是要记住，上下文降级发生在你的上下文窗口的 45% 左右。子代理让你能够将复杂的研究或实现任务卸载到一个新的上下文中，然后只带回相关的结果，这意味着你的主对话保持清晰。

Claude 代码包括三个内置的子代理：

Explore（探索）：一个快速、只读的代理，用于搜索和分析代码库。当 Claude 需要理解你的代码而无需进行更改时，它会委托给这里。当正确使用时，Claude 会指定彻底性：快速、中等或非常彻底。

Plan（计划）：一个研究代理，在计划模式期间使用，以在提出计划之前收集上下文。它调查你的代码库并返回发现，以便 Claude 可以做出明智的架构决策。

General-purpose（通用）：一个有能力的代理，用于需要探索和行动的复杂、多步骤任务。当任务需要多个依赖步骤或复杂的推理时，Claude 会委托给这里。

创建自定义子代理

就像你需要一个自定义技能一样，我强烈建议你创建自己的自定义子代理。在 Claude 代码中运行 /agents 以查看所有可用的子代理并创建新的子代理。

要手动创建一个，将一个 Markdown 文件添加到 ~/.claude/agents/（用户级别，在所有项目中可用）或 .claude/agents/（项目级别，与你的团队共享）。

一个示例结构：

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Invoke when checking for auth issues, injection risks, or data exposure.
tools: Read, Grep, Glob
---

You are a security-focused code reviewer. When analyzing code:

1. Check for authentication and authorization gaps
2. Look for injection vulnerabilities (SQL, command, XSS)
3. Identify sensitive data exposure risks
4. Flag insecure dependencies

Provide specific file and line references for each finding. Categorize by severity: critical, high, medium, low.

tools 字段控制子代理可以做什么。对于只读审阅者，限制为 read、grep 和 glob 命令。对于实现代理，包括 write、edit 和 bash 命令。

子代理如何沟通

这是大多数人错过的地方。子代理不直接相互共享上下文，因为它们在隔离状态下运行。通信通过委托和返回模式发生：

1. 主代理识别适合委托的任务

2. 主代理使用描述任务的特定提示调用子代理

3. 子代理在其自己的上下文窗口中执行

4. 子代理向主代理返回发现/行动的摘要

5. 主代理合并摘要并继续

摘要是关键。一个设计良好的子代理不会将其整个上下文转储回来。这就是为什么子代理描述和系统提示需要明确输出格式。

对于复杂的工作流程，你可以链接子代理。主代理协调：

主代理

|── 将研究委托给 Explore 子代理 │ └── 返回："找到 3 个相关文件：auth.py、middleware.py、routes.py" |── 将实现委托给自定义实现者子代理 │ └── 返回："添加了密码重置端点，更新了 2 个文件" └── 将测试委托给自定义测试运行器子代理 └── 返回："所有 12 个测试都通过，覆盖率达到 94%"

每个子代理都为其特定任务获取新的上下文。主代理只保存摘要，而不是完整的探索历史。这可以防止上下文污染，而上下文污染会扼杀长时间的编码会话。

一个重要的约束：子代理不能生成其他子代理。这可以防止无限嵌套，并保持架构的可预测性。

实用的子代理模式

大型重构：让主代理识别所有需要更改的文件，然后为每个逻辑组启动一个子代理。每个子代理处理其范围并返回一个摘要。主代理永远不需要同时保存每个文件的完整上下文。

代码审查管道：创建三个子代理：style-checker（样式检查器）、security-scanner（安全扫描器）、test-coverage（测试覆盖率），并针对 PR 并行运行它们。每个子代理以一致的格式返回发现 → 主代理将结果综合成一个单一的审查。

研究任务：当你需要理解代码库中不熟悉的部分时，委托给 Explore 并提出具体问题。它会返回相关文件和模式的精简地图，使你的主上下文专注于实际的实现工作。

MCP 连接器（Connectors）：永远不要离开 Claude

MCP（模型上下文协议）是一种标准化的方式，允许 AI 模型通过统一的界面调用外部工具和数据源，而不是为每个工具和数据源进行自定义集成。你无需进入 GitHub，无需进入 Slack、Gmail、Drive 等。你可以通过 Claude 界面，经由 MCP 服务器让 AI 与所有这些“对话”。

添加连接器的命令：

## HTTP transport (recommended for remote servers)
# HTTP 传输（推荐用于远程服务器）
claude mcp add --transport http <name> <url>

## Example: Connect to Notion
# 示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp
# With authentication
# 使用身份验证
claude mcp add --transport http github https://api.github.com/mcp \
--header "Authorization: Bearer your-token"

或者，如果你想要在 Web 应用程序中使用超级简单的路由，你可以转到设置 → 连接器 → 找到你的服务器 → 配置 → 授予权限，然后就完成了。

以下是一些 MCP 服务器在过去 6 个月内为我完成的示例：

• 从问题跟踪器中实现功能：“添加 JIRA 问题 ENG-4521 中描述的功能”

• 查询数据库：“查找过去一周从我们的 PostgreSQL 数据库注册的用户”

• 集成设计：“根据新的 Figma 设计更新我们的电子邮件模板”

• 自动化工作流程：“创建 Gmail 草稿，邀请这些用户参加反馈会议”

• 总结 Slack 线程：“团队在 #engineering 频道中关于 API 重新设计决定了什么？”

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

一个曾经需要五个上下文切换的工作流程（检查问题跟踪器、查看设计、查看 Slack 讨论、实现代码、更新工单），现在在一个连续的会话中完成。你始终处于心流状态。

我建议连接以下 MCP 服务器：

• GitHub：存储库管理、问题、PR、代码搜索

• Slack：频道历史记录、主题摘要、消息搜索

• Google Drive：在实现期间访问文档以供参考

• PostgreSQL/数据库：直接查询，无需离开 Claude

• Linear/Jira：问题跟踪集成

要查看你当前的 MCP 连接，请在 Claude 代码中运行 /mcp。

第三方 MCP 服务器未经 Anthropic 验证，因此请小心。对于敏感的集成，请查看服务器的源代码或使用来自服务提供商的官方连接器。

复合效应（The Compound Effect）

这就是所有这些结合在一起的地方。一个了解你的代码库模式的技能 + 一个处理测试的子代理 + 到你的问题跟踪器的 MCP 连接 = 一个无与伦比的系统。

该技能编码了你的团队的约定。你无需担心上下文。子代理保持你的主对话清晰，同时处理复杂的子任务。MCP 连接消除了碎片化你注意力的上下文切换。

我观察到的从 Claude 代码中获得最多收益的工程师不是将其用于一次性任务，而是将其视为一个可以倍增其工作能力的系统。他们投入时间配置技能、定义子代理、连接服务。然后，这种投资理所当然地在每一个后续任务中获得回报。

如果你害怕从哪里开始，只需从你反复解释的事情的一个技能开始。或者只创建一个单一的代理。然后进行测试并从那里开始。无需一次尝试所有内容而让自己不知所措。

TLDR（太长不看）

上下文窗口并不相等。Claude 代码提供一致的 20 万 token。Cursor 在实践中经常截断为 7 万到 12 万 token，因为有内部安全措施。这对于大型代码库很重要。

技能教会 Claude 你的特定工作流程。创建 ~/.claude/skills/skill-name/SKILL.md，其中包含 YAML frontmatter（名称、描述）和 Markdown 指令。Claude 会在相关时自动应用它们。

子代理为复杂的任务提供隔离的上下文。每个子代理都有其自己的 20 万 token 窗口。内置：Explore（探索）、Plan（计划）、通用。在 ~/.claude/agents/ 中创建自定义的子代理。它们通过委托和摘要进行通信，而不是共享上下文。

MCP 连接器消除了上下文切换。连接到 GitHub、Slack、数据库、问题跟踪器。将通常需要五个选项卡的链式工作流程整合到一个连续的会话中。命令：claude mcp add --transport http <name> <url>

这些会复合。技能编码模式，子代理处理子任务，MCP 连接服务。总之，它们构建了一个随着使用而改进的系统。

• 原文链接： x.com/eyad_khrais/status...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～