说实话，第一次接触 Claude Code 的时候，我心里其实是有点犯嘀咕的。这玩意儿真的Neng像宣传的那样，帮我们把那些繁琐的代码工作全包圆了吗？但当你真正沉下心来去研究它的底层逻辑，去尝试写第一个 Agent 的时候，那种感觉——怎么说呢，就像是你第一次学会了骑自行车，或者是第一次成功编译了一个复杂的内核，那种掌控感和成就感是会上瘾的。

hen多朋友问我，想深入学习 Claude Code 的代码，到底该从哪儿下手？确实这需要一个从“会用”到“kan懂”再到“Neng改”的过程。别急，我帮你梳理了一份“三步走”学习路线，里面包含了大量可直接操作的示例，甚至还有我踩过的一些坑，希望Neng帮你加速这个过程，少走弯路。

第一阶段：环境搭建与“Hello World”式的试探

在开始跑马拉松之前，咱们得先系好鞋带。对于 Claude Code 来说环境配置就是那双鞋。虽然官方文档写得挺详细，但实际操作起来总有些琐碎的细节容易让人抓狂。

你得把 SDK 请进门。打开你的终端，别犹豫，直接执行下面的命令。这里我建议使用 npm 或者 yarn，毕竟大家现在dou习惯了 Node.js 的生态。

# 安装核心 SDK 包
npm install @anthropic-ai/claude-agent-sdk
# 接下来非常关键的一步：设置 API Key
# 在你的 .bashrc 或者 .zshrc 里加上这一行，或者直接在当前 shell 导出
export ANTHROPIC_API_KEY="你的-api-key-放这里-别搞丢了"

配置好了之后咱们得写个Zui简单的脚本来验证一下。这就好比新买的电脑，先开机kankan亮不亮屏。创建一个叫 `test-setup.js` 的文件，把下面这段代码贴进去。这段代码的逻辑hen简单，就是让 Claude 说句话，确认我们的网络和权限dou是通的。

// test-setup.js
import { query } from "@anthropic-ai/claude-agent-sdk";
async function initialTest {
  // 这里我们发起一个Zui简单的查询
  for await (const msg of query({
    prompt: "Say 'Hello, I am ready to work'",
    options: { maxTurns: 5 }
  })) {
    // 当收到Zui终结果时打印出来
    if  {
      console.log;
    }
  }
}
// 执行测试函数
initialTest;

保存文件，然后在命令行敲 `node test-setup.js`。Ru果你kan到了那句 "Hello, I am ready to work"，恭喜你，你的环境Yi经就位了Ke以开始下一步的折腾了。Ru果报错了别慌，多半是 API Key 没配对，或者是网络代理的问题，回头检查一下就行。

第二阶段：理解 Agent 的“心跳”——流式响应与工具系统

hen多初学者容易把 Claude Code 当成一个单纯的聊天机器人，其实大错特错。它真正的威力在于“Agent”这个概念。什么是 Agent？简单来说就是一个Neng自主思考、调用工具、观察结果并循环往复直到达成目标的智Neng体。

而支撑这个智Neng体运转的“心脏”，就是流式响应机制。你发出的每一个指令，Claude dou不是瞬间给你一个Zui终答案，而是像挤牙膏一样，一点一点地把它的思考过程、工具调用结果吐出来。这对于我们开发者来说至关重要，因为我们Ke以实时监控它在干什么甚至随时打断它。

咱们来kan一段代码，kankan如何捕捉这些细碎的中间状态。这段代码会展示 Agent 是如何一步步思考的，而不是只给你一个冷冰冰的结果。

import { query } from "@anthropic-ai/claude-agent-sdk";
async function streamingAgent {
  const response = await query({
    prompt: "列出当前目录下所有 .js 文件，并统计总行数",
    options: { maxTurns: 10 }
  });
  // 使用 for await...of 循环来处理异步生成器
  for await  {
    switch  {
      case "system":
        // 系统层面的初始化信息
        console.log;
        break;
      case "assistant":
        // AI 正在思考或者准备说话
        console.log;
        break;
      case "user":
        // 这里其实是工具返回的结果，在 SDK 里被标记为 user 消息类型
        console.log;
        break;
      case "result":
        // Zui终大功告成的时刻
        console.log;
        break;
    }
  }
}
streamingAgent;

你kan，通过这种细粒度的监听，我们仿佛Nengkan见 Agent 的“脑电波”。它先想“我要列出文件”，然后调用文件系统工具，拿到结果后又想“我要数行数”，Zui后才给你答案。这种透明度是构建复杂应用的基础。

给 Agent 装上“双手”：自定义工具

光有脑子不行，还得有手。在 Claude Code 的世界里工具就是 Agent 的手。默认情况下Agent 只Neng聊聊天但Ru果你给它装上了自定义工具，它就Neng读写文件、执行 Shell 命令，甚至调用你公司的内部 API。

咱们来定义一个简单的工具：读取文件内容。注意kan `inputSchema` 部分，这就像是给 Agent 写的说明书，告诉它这个工具需要什么参数。

import { query } from "@anthropic-ai/claude-agent-sdk";
import fs from 'fs/promises';
// 定义我们的工具箱
const myToolBox = 
  },
  // 这是工具的执行逻辑，也就是 Agent 调用时真正跑的代码
  handler: async  => {
    try {
      const content = await fs.readFile;
      return { content };
    } catch  {
      return { error: `读取失败: ${err.message}` };
    }
  }
}];
async function agentWithHands {
  const response = await query({
    prompt: `请读取 package.json 文件，然后告诉我项目的名称和版本号`,
    options: {
      maxTurns: 5,
      tools: myToolBox,             // 把工具箱交给 Agent
      permissionMode: "acceptEdits" // 自动批准操作，开发环境Ke以这么干
    }
  });
  for await  {
    if  {
      console.log;
    }
    if  {
      console.log;
    }
  }
}
agentWithHands;

当你运行这段代码，你会发现 Agent 不再是瞎猜了它真的去读了文件，然后基于文件内容回答你。这就是从“聊天”到“干活”的跨越。

第三阶段：连接外部世界——MCP 服务器集成

自己写工具虽然爽，但要是每个人dou从头造轮子，那也太累了。这时候，MCP 就派上用场了。你Ke以把它理解为 Agent 界面的 USB 接口，只要符合这个标准的外部服务，douNeng即插即用。

比如我们想给 Agent 增加文件系统的操作Neng力，完全不用自己写代码，直接用现成的 MCP 服务器就行。kan下面这段代码，我们通过 `StdioClientTransport` 连接到一个本地的文件系统服务。

import { query } from "@anthropic-ai/claude-agent-sdk";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
async function mcpAgentDemo {
  // 1. 创建传输层，这里我们启动一个文件系统服务器，指向 /tmp 目录
  const transport = new StdioClientTransport({
    command: "npx",
    args: 
  });
  // 2. 初始化 MCP 客户端
  const mcpClient = new Client({
    name: "my-file-agent",
    version: "1.0.0"
  });
  // 3. 建立连接
  await mcpClient.connect;
  // 4. 获取服务器提供了哪些工具
  const { tools: remoteTools } = await mcpClient.listTools;
  console.log);
  // 5. 发起查询，把 mcpClient 传进去
  const response = await query({
    prompt: "请在 /tmp 目录下创建一个名为 hello_claude.txt 的文件，并写入 'Hello MCP'",
    options: {
      mcpClients: ,  // 关键点：传入 MCP 客户端
      maxTurns: 10
    }
  });
  for await  {
    if  console.log;
  }
}
mcpAgentDemo;

除了文件系统，MCP 生态里还有好多好玩的东西。比如 Composio，它提供了 100+ 应用的集成。你想让 Agent 帮你操作 GitHub、Jira 甚至 Slack？不用自己写 API 封装，直接接 Composio 就行。

配置方法也hen简单，在项目根目录搞个 `CLAUDE.md`，Claude Code 每次启动dou会自动读取。或者通过命令行添加：

# 通过 Rubex添加 Composio 的 MCP 服务器
claude mcp add composio --transport http \
  "https://mcp.composio.dev/sse?apiKey=你的Composio密钥"

一旦配置完成，你在代码里直接用就行，就像下面这样，让 Agent 去你的 GitHub 仓库里找东西：

import { query } from "@anthropic-ai/claude-agent-sdk";
async function githubAgent {
  const response = await query({
    prompt: "从我的 GitHub 仓库列表中找到Zui近geng新的项目，并列出它的 Stars 数",
    options: {
      // MCP 服务器Yi在配置中注册，会自动作为工具加载
      maxTurns: 5
    }
  });
  for await  {
    if  console.log;
  }
}

第四阶段：安全带系好——权限与安全机制

把 Agent 放飞之前，咱们得先谈谈安全。你肯定不希望 Agent 一不小心把你的 `node_modules` 给删了或者geng糟糕，执行了 `rm -rf /`。在生产环境里权限控制是生命线。

Claude Code 提供了非常细粒度的权限控制。Zui简单的就是 `permissionMode`。比如我们Ke以设置成 "ask" 模式，让 Agent 每次执行危险操作前dou得先问问你。

import { query } from "@anthropic-ai/claude-agent-sdk";
async function paranoidAgent {
  const response = await query({
    prompt: "删除 node_modules 文件夹以清理空间",
    options: {
      permissionMode: "ask",  // 每次操作dou需要人工确认
      maxTurns: 5
    }
  });
  for await  {
    if  {
      console.log;
      // 这里你Ke以弹窗给用户，或者记录日志
      // 实际场景中，你需要调用某种 approve/reject 逻辑
    }
    if  console.log;
  }
}

但这还不够。有时候我们需要geng精细的控制，比如“只Neng读 `src` 目录，不Neng写 `config` 目录”。这时候，我们Ke以通过回调函数来实现自定义的权限检查逻辑。

import { query } from "@anthropic-ai/claude-agent-sdk";
// 定义我们的安全规则
const securityRules = {
  // 文件读取：只允许 src 目录
  canRead:  => path.startsWith,
  // 文件写入：只允许 src 目录
  canWrite:  => path.startsWith,
  // 命令执行：黑名单机制
  canRun:  => {
    const forbiddenCommands = ;
    // Ru果命令包含黑名单里的词，直接拒绝
    return !forbiddenCommands.some);
  },
  // 网络请求：白名单机制
  canFetch:  => url.includes || url.includes
};
async function fineGrainedAgent {
  const response = await query({
    prompt: "读取 src/index.js 并统计代码行数，然后尝试读取 /etc/passwd",
    options: {
      canUseTool: async  => {
        // 拦截 Read 工具
        if ) {
          console.log;
          return false;
        }
        // 拦截 Bash 工具
        if ) {
          console.log;
          return false;
        }
        return true; // 其他情况放行
      },
      permissionMode: "acceptEdits"
    }
  });
  for await  {
    if  console.log;
  }
}
fineGrainedAgent;

有了这层机制，你就Ke以放心地把 Agent 交给你的团队成员，或者部署到半可信的环境中了。毕竟安全这事儿，怎么小心dou不为过。

第五阶段：进阶玩法——多 Agent 协作与持久化

当你只有一个 Agent 时它是个勤奋的实习生。但当你有一群 Agent 时它就变成了一个高效的公司。Claude Code 支持多 Agent 协作，让不同的 Agent 专注于不同的领域。

比如我们Ke以让一个 Agent 负责写代码，另一个负责写测试，还有一个负责写文档。它们之间Ke以通过 `sub-agents` 机制并行工作。

import { query } from "@anthropic-ai/claude-agent-sdk";
async function teamLeaderAgent {
  // 主 Agent 充当项目经理的角色
  const response = await query({
    prompt: `
      请启动多个子 Agent 来完成以下任务：
      1. Agent A: 分析 package.json 了解项目依赖
      2. Agent B: 阅读 README.md 了解项目背景
      3. Agent C: 检查 src/index.js 的代码风格
      Zui后汇总所有子 Agent 的报告，生成一份项目健康度简报。
    `,
    options: {
      maxTurns: 15,
      // 启用子 Agent 模式，允许它分裂出新的实例
      settingSources: 
    }
  });
  for await  {
    if  {
      console.log;
    }
    if  {
      console.log;
    }
    if  {
      console.log;
    }
  }
}
teamLeaderAgent;

除了多 Agent，会话持久化也是个hen实用的功Neng。有时候对话太长，Token 不够用了或者你想分批次处理任务，这时候就需要保存和恢复 Session。

import { query } from "@anthropic-ai/claude-agent-sdk";
async function persistentSessionDemo {
  let currentSessionId = null;
  // 第一阶段：初始化分析
  console.log;
  const response1 = await query({
    prompt: "分析当前项目的代码结构，找出主要的模块",
    options: { maxTurns: 5 }
  });
  for await  {
    if  {
      currentSessionId = msg.session_id; // 抓住这个 ID，这就是你的存档档位
    }
    if  {
      console.log;
    }
  }
  if  return;
  // 第二阶段：基于之前的分析继续
  console.log;
  const response2 = await query({
    prompt: "基于刚才的分析，针对核心模块提出重构建议",
    options: {
      resumeSessionId: currentSessionId, // 读档！
      maxTurns: 5
    }
  });
  for await  {
    if  console.log;
  }
}
persistentSessionDemo;

终极实战：打造一个生产级代码审查 Agent

讲了这么多，Zui后咱们来个大的。把上面学到的知识点——工具调用、流式响应、权限控制——全部整合起来Zuo一个Neng真正干活的代码审查 Agent。

这个 Agent 的任务是：运行 Linter 检查规范，跑单元测试，然后生成一份报告。

import { query } from "@anthropic-ai/claude-agent-sdk";
import { exec } from 'child_process';
import { promisify } from 'util';
import fs from 'fs/promises';
const execAsync = promisify;
// 定义审查专用的工具集
const reviewToolKit =  },
  handler: async  => {
    try {
      // 这里假设你的项目配置了 eslint
      const { stdout } = await execAsync;
      return JSON.parse;
    } catch  {
      // eslint 有报错时会抛异常，但我们需要具体的错误信息
      return { errors: error.stdout ? JSON.parse :  };
    }
  }
}, {
  name: "run_unit_tests",
  description: "执行 Jest 或 Mocha 测试套件",
  inputSchema: { type: "object", properties: {}, required:  },
  handler: async  => {
    try {
      // 假设使用 jest 并输出 json 格式
      await execAsync;
      const results = JSON.parse);
      return { 
        success: true, 
        passed: results.numPassedTests, 
        failed: results.numFailedTests 
      };
    } catch  {
      return { success: false, error: e.message };
    }
  }
}];
async function codeReviewManager {
  console.log;
  const response = await query({
    prompt: `
      请作为资深代码审查员，对当前项目进行全面体检：
      1. 运行 Linter 检查代码风格问题
      2. 运行测试套件确保功Neng正常
      3. 重点关注 src/ 目录下的代码质量
      4. 生成一份 Markdown 格式的审查报告，包含：
         - 风格问题汇总
         - 测试覆盖率情况
         - 潜在的 Bug 风险
         - 具体的改进建议
    `,
    options: {
      tools: reviewToolKit,
      maxTurns: 20, // 复杂任务可Neng需要geng多轮次
      permissionMode: "acceptEdits" // 允许它读取文件和运行脚本
    }
  });
  for await  {
    switch  {
      case "assistant":
        console.log + "...");
        break;
      case "tool_call":
        console.log;
        break;
      case "result":
        // 把报告存到文件里
        const timestamp = new Date.toISOString.slice;
        const filename = `review-report-${timestamp}.md`;
        await fs.writeFile;
        console.log;
        console.log;
        console.log + "...");
        break;
    }
  }
}
codeReviewManager;

给你的学习路线图

这一路走来咱们从Zui简单的环境配置，聊到了复杂的多 Agent 协作。为了让你geng清晰地把握进度，我画了个简单的表格，你Ke以对照着kankan自己到了哪个阶段。

阶段	核心目标	预估代码量	建议耗时
1. 入门	跑通 Hello World，环境没问题	~10 行	30 分钟
2. 理解	搞懂流式响应和工具调用原理	~50 行	2 小时
3. 实践	Neng自己写自定义工具	~100 行	半天
4.	集成 MCP 服务器，连接外部服务	~150 行	1 天
5. 大师	构建多 Agent 协作系统	300+ 行	3 天+

学习新技术Zui怕的就是“眼高手低”。kan懂了不代表会了一定要亲手敲一遍代码。Ru果遇到报错，别急着去 Stack Overflow 复制粘贴，先试着kankan日志，分析一下是网络问题、权限问题还是逻辑问题。这种排查问题的过程，才是你真正成长的时刻。

Claude Code 的世界hen大，咱们今天聊的也只是冰山一角。Ru果你在实践的过程中有什么新奇的想法，或者遇到了什么棘手的 Bug，欢迎随时回来交流。毕竟代码这东西，大家一起写，才geng有意思，不是吗？

---