Skip to main content

第一周:真实 Claude Code 会话的追踪剖析

原文仓库:modern-software-dev-assignments/week1/assignment.md

作业概述​

本周你需要将一个真实的 Claude Code 会话放在代理后面运行,捕获它发出的实际 HTTP 请求,然后对它们进行剖析。你不是在构建新东西,而是在阅读别人家的生产系统——深入到足以看清其设计决策的层次。

学习目标​

  • 追踪一个来自生产级编码 Agent 的真实编码会话,理解其调用结构。
  • 识别提示词、工具 schema 和模型响应在一次非平凡编码任务中如何交互。
  • 反思哪些行为你会复制,哪些你会改变,在你自己的自定义 Agent 中。

参考资料​

环境搭建​

前置条件:Claude Code。斯坦福通过你的 SUNet ID 提供 Claude Code 访问权限。如果你还没有激活账户,请先申请访问,然后安装并登录。账户审批通过并完成安装后,用 claude --version 确认,并将版本号记录在你的报告中。

1. 安装 mitmproxy:

  • macOS:brew install --cask mitmproxy。
  • Windows:从 mitmproxy.org 运行安装程序,它会把 mitmweb 加入你的 PATH。
  • Linux 或任意平台:pip install mitmproxy,如果你创建了课程 conda 环境则在其中安装。

2. 作为反向代理启动:

mitmweb --listen-host 127.0.0.1 --listen-port 58888 \
--web-open-browser --mode reverse:https://api.anthropic.com \
-w session.flows

发送到 127.0.0.1:58888 的流量会被转发到真实 API;检查界面在 http://localhost:8081 打开。反向模式意味着你将 Claude Code 指向一个明文 HTTP 本地地址,因此不需要安装 CA 证书。-w session.flows 将每个流量保存到磁盘;请在非 git 仓库的目录下运行此命令,以免捕获文件被意外提交。

3. 将 Claude Code 指向代理:在你将用于第一部分的仓库中,创建一个项目级 .claude/settings.json:

{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:58888",
"ENABLE_TOOL_SEARCH": "true"
}
}

⚠️ 不要把它放在 ~/.claude/settings.json 里! 否则你机器上的任何 Claude Code 会话都会落入你的捕获中(而且一旦 mitmweb 停止,会话就无法工作)。

4. 验证:启动一个新的 claude 会话,发送任何内容,确认 mitmweb 中出现了一个 POST /v1/messages 流量。

5. 作业完成后:完成后,删除仓库的 .claude/settings.json(或其中的 env 块)并停止 mitmweb。

第一部分:捕获一个会话(15 分)​

在代理下运行一个会话,满足以下四个要求:

  1. 多文件:涉及至少两个文件。
  2. 至少失败一次:你需要一个错误恢复序列。故意破坏一个测试是最可靠的触发方式。
  3. 足够长以进行规划:Agent 应该制定一个明确的计划,而不是只发出一个工具调用:任务列表、计划模式或计划文件均可。
  4. 你自己的仓库:一个临时项目,不是本课程仓库。

任务建议,如果你不想自己发明:

  • 删除一个被其他模块导入的函数,然后让 Claude 恢复全部功能并使测试通过。
  • 给一个小型 Web 应用添加端点和测试,然后让它在某个你没装的依赖版本上通过测试套件。
  • 重命名一个模块并让它更新所有导入,然后运行 lint 和测试。
  • 提出一个需要用到不熟悉库的功能,这样 Agent 必须先查阅 API 才能写代码。

在 mitmweb 界面中,选择一个 POST /v1/messages 流量,下载请求体为 JSON。在本地保存好这些文件。你不需要提交它们,但后续每一部分的评分都依赖于从中提取的证据,所以请保存足够的量来支撑你的答案。

如果你的 mitmweb 会话终止了,你可以从保存的 session.flows 文件中继续工作:用 mitmweb -r session.flows 重新打开。

⚠️ 对引用内容进行脱敏​

你的捕获包含你自己的源代码、文件路径和凭据。除了你在 writeup.md 中有意引用的摘录外,任何内容都不应进入仓库。

  • 绝不要粘贴原始流量或 HTTP 头,因为 x-api-key / authorization 就在那里。
  • 请求体也可能包含密钥。 Agent 读取的任何内容(.env、配置文件、命令输出)都会在 messages 中重放。在引用工具结果前先检查。
  • 将 session.flows 排除在每个 git 仓库之外。
  • 在你的引用中用可见标记([已脱敏:内部主机名])遮盖私密内容,而不是静默删除。
  • 如果某个摘录无法在不破坏其含义的情况下脱敏,请在一次性仓库上重新捕获。

第二部分:标注系统提示词(25 分)​

将 system 块和任何 role: "system" 的消息拆分为各个章节。对每个章节回答:这个段落带来了什么行为,又在防范什么失败模式? 是标注,不是摘要。

至少覆盖:

  • 结构:主要章节、它们的顺序,以及为什么是这个顺序。
  • 语气与冗长度:控制响应长度和格式的具体语言,以及为什么值得花这些 token。
  • 何时不行动:破坏性操作的闸门、范围限制、拒绝条件。
  • 环境上下文:Agent 被告知了关于机器、仓库和会话的什么信息,以及这些信息位于请求的哪个位置。

然后,专门讨论 <system-reminder>:它们出现在哪里(system 块、messages 中、还是两者都有,引用一个示例),你能从证据中看出哪两种不同的用途,以及为什么在对话中间注入而不是在开头一次性说明?

第三部分:标注工具设计(25 分)​

清点:用数字,不用散文。 有多少个工具可用,按内置 vs MCP 提供的 vs 延迟/可搜索的进行分解。注意请求之间工具集是否有变化,以及是什么触发了变化。一个好的回答读起来是"第一个请求中 117 个工具:35 个内置,82 个来自三个 MCP 服务器",而不是"有很多工具可用。"

设计分析。 选择两个工具,将每个作为接口设计来分析:

  • 复现 schema 的相关部分。
  • 为什么是这个参数集?什么是必需的,什么是可选的,什么是故意不暴露的?
  • 描述在防范什么?成熟 Agent 中的工具描述很大程度上是积累的伤疤组织。找到一句只因模型反复做错才存在的话,并指出那个错误行为。
  • 工具故意不做什么,这暗示了周围系统的什么?

选两个有差异的工具。两个文件操作工具是弱选择;一个文件工具配一个编排工具,或者一个有异常失败契约的工具,是强选择。

第四部分:行为分析与证据(25 分**​

从你自己的追踪中回答每个问题。每个答案必须引用其证据(哪个请求、消息索引、工具调用)并标记自己为 [观察到的] 或 [推断的]:观察到的意味着你可以在捕获中指出它,推断的意味着你在没有看到它发生的情况下从定义推理而来。两者都可以接受;错误标记不可接受,未标记的答案不得分。

  • 错误恢复:完整走查一次失败。Agent 看到了什么,它接下来尝试了什么,恢复花了几轮?逐字引用。
  • 规划:是工具、提示词指令、涌现行为,还是三者的组合?什么证据能区分它们?
  • 计划与任务状态:一个是如何创建和推进的?模型每轮看到关于任务状态的什么信息,它位于请求的哪里?
  • 子 Agent:Agent 何时委派?子 Agent 被告知了什么,返回了什么?(如果你的会话从未触发过,一个诚实的 [推断的] 就可以。)
  • 上下文管理:随着会话增长,载荷中发生了什么变化?早期的轮次在后来是如何表示的?

第五部分:反思(10 分)​

最多一页:两个你会借鉴的决策以及各自解决的问题;一个你会用不同方式做的,认真讨论它可能存在的原因;以及这次追踪改变了你日常如何操控编码 Agent 的一件事。

交付物​

一份完成的 week1/writeup.md,每个 TODO 都已填写。你捕获的追踪文件保留在你自己的机器上。

评分标准(共 100 分)​

部分分值什么可以获得满分
一、捕获与可复现性15满足全部四个会话要求;设置和会话记录得足够详细,仅凭报告就能复现
二、系统提示词标注25各章节与行为和失败模式关联;<system-reminder> 有引用示例解释
三、工具清点与设计25具体数字及分解;两个真正不同的工具作为接口设计分析
四、行为分析25每个答案有引用且标记正确;错误恢复逐字引用
五、反思10有具体论点而非重述

对引用摘录中未脱敏的凭据,以及声称是观察但追踪不支持的论断会扣分。

提交说明​

  1. 确保所有更改已推送到你的远程仓库以供评分。
  2. 确保你已在作业仓库中添加 mihail911、isaackann 和 vdaita 为协作者。
  3. 通过 Gradescope 提交。
  4. 别忘了从你的仓库 .claude/settings.json 中移除 ANTHROPIC_BASE_URL!