CS146S 第三周阅读材料笔记总结

Stanford University · Fall 2025 · 讲师：Mihail Eric

阅读材料一览

#	材料	类型	获取状态	对应课堂内容
1	Specs Are the New Source Code	长文	✅ 完整获取	第一讲 Specs Doc 的理论基础
2	How Long Contexts Fail	长文	✅ 完整获取	IDE 为什么需要 RAG 而非塞入所有代码
3	Devin: Coding Agents 101	文档	⚠️ 概要	第二讲 Silas 演讲的产品文档
4	Getting AI to Work In Complex Codebases	GitHub	⚠️ 概要	第一讲"优化代码库"的深度展开
5	How FAANG Vibe Codes	Twitter	⚠️ 帖子	行业视角补充
6	Writing Effective Tools for Agents (Anthropic)	长文	✅ 完整获取	第二周 MCP + 第三周工具设计的进阶指南

📖 阅读 1：Specs Are the New Source Code

来源： Ravi Mehta (前 Reforge CPO) Substack，2025 年 7 月

🔗 课堂关联： 这是第一讲 Slides 9-10（Specs Doc 八要素）的理论基础和行业论证。课堂说"复杂任务中你要变成产品经理"，这篇文章深度解释了为什么。

核心论点：Spec 正在变成新的"源代码"

Sean Grove（OpenAI）的观点： 我们现在做 AI 开发的方式是倒过来的——我们精心编写 prompt 传达意图给模型，AI 生成代码，然后我们保留代码、丢弃 prompt。这就像"把源代码碎掉，然后精心版本控制二进制文件"。

传统软件开发中，源代码是神圣的——包含注释、结构、文档。二进制文件只是下游产物。但在 AI 时代，我们把关系搞反了。

关键引用： "一个足够健壮的 Spec 可以生成好的 TypeScript、好的 Rust、服务器、客户端、文档、教程、博客文章，甚至播客。"

更重要的是： Spec 做到了代码做不到的事——同时对齐人类和机器的共同目标。

工作流的变革

旧工作流： 模糊想法 → 线框图 → 设计 → 工程师构建 MVP → 用户反馈 → 痛苦的 Spec 修改 → 重建

新工作流： 模糊想法 → 快速原型（v0/Lovable/Replit）→ 用户反馈 → 清晰的 Spec → AI 辅助实现

关键变化： Spec 从输入变成了输出——先用 AI 快速验证想法，然后写 Spec。原型没有杀死 Spec，而是让 Spec 变得更好。

PM 的新角色

Andrew Ng 的观察："我第一次见到有人提议让 PM 数量是工程师的两倍。" 随着 AI 让工程师交付更快，公司需要更多 PM来支持这些高产的工程师。

对课堂的启示： 课堂要求掌握写 Spec 的技能，不是在教"产品管理"，而是在教未来软件工程师的核心技能——因为"在不久的将来，沟通最有效的人就是最有价值的程序员"。

🔗 课堂关联： 课堂 Slides 9-10 给出了 Spec 的八要素（Goal, Definitions, Plan, Source files, Test cases, Edge cases, Out-of-scope, Extensions）。这篇文章解释了为什么这些要素如此重要——它们不只是给 LLM 的指令，更是团队对齐的核心载体。

📖 阅读 2：How Long Contexts Fail

来源： Drew Breunig 博客，2025 年 6 月

🔗 课堂关联： 第一讲 Slide 8 解释了 IDE 的 Chat 模式使用语义索引（RAG）而非直接塞入所有代码。这篇文章解释了为什么必须这样做——长上下文并不等于更好的结果。

核心论点：更长的上下文窗口 ≠ 更好的结果

随着前沿模型支持百万级 token 上下文窗口，很多人兴奋地认为可以"把所有东西扔进 prompt"。但实际上，过载的上下文会导致 agent 以令人意外的方式失败。

四种上下文失败模式

① 上下文中毒（Context Poisoning）

当幻觉或其他错误进入上下文后，会被反复引用。

Gemini 2.5 技术报告中的案例：AI 玩 Pokémon 时，一次幻觉"毒化"了其目标列表，导致 agent 追求不可能达成的目标，需要很长时间才能修复。

🔗 课堂关联： 第二周 Claude Code 的"秘密武器"之一是在 tool results 中嵌入 <system-reminder> 来防止 drift——这正是对抗上下文中毒的策略。

② 上下文分心（Context Distraction）

当上下文过长时，模型过度关注上下文本身，忽略训练中学到的知识。

Gemini 研究发现：当上下文超过约 100K token 后，agent 倾向于重复历史中的动作而非合成新计划。Databricks 研究发现 Llama 3.1 405B 在约 32K token 时准确率开始下降。

🔗 课堂关联： 第一周讲到的"上下文窗口限制"和 "primacy/recency bias"（首位效应/近因效应）在这里得到了实证支持。

③ 上下文混淆（Context Confusion）

上下文中无关内容被模型用来生成低质量回复。

Berkeley 函数调用排行榜证明：每个模型在多工具场景中表现都比单工具差，且所有模型偶尔会调用不相关的工具。量化后的 Llama 3.1 8B 在 46 个工具时失败，但在 19 个工具时成功——尽管上下文远未超出限制。

🔗 课堂关联： 第二周课堂 Slide 12 提到"Agent 不擅长处理大量工具"和"Cursor 对工具数量有硬限制"——这篇文章给出了学术依据。

④ 上下文冲突（Context Clash）

上下文中积累的新信息与旧信息相互矛盾。

Microsoft/Salesforce 研究：将单一 prompt 拆分为多轮对话后，准确率平均下降 39%。o3 的分数从 98.1 降到 64.1。原因：早期轮次中模型的错误尝试留在上下文中，影响最终答案。

🔗 课堂关联： 这直接解释了第二周 Claude Code 为什么要使用子 Agent——每个子 Agent 有独立的上下文，避免主 Agent 的上下文被早期错误"污染"。

对 AI IDE 的启示

这四种失败模式共同解释了为什么 AI IDE 不能简单地"把所有代码塞进上下文"：

Tab Complete 只发送小上下文窗口
Chat 模式使用 RAG/语义索引选择性提供上下文
Agent 配置文件（CLAUDE.md 等）是精心策划的上下文，而非随机的代码堆积

📖 阅读 3：Devin — Coding Agents 101

来源： devin.ai/agents101

🔗 课堂关联： 这是第二讲 Silas Alberti 演讲的产品文档补充。Silas 讲的是高层工作流（Plan→Build→Review），这篇文档提供了 Devin 的技术架构细节。

核心概念

Devin 是一个完全异步的 AI 软件工程师，可以在云端独立工作数小时——包括计划、编码、测试、调试。它拥有自己的隔离工作空间（shell + editor + browser）。

与 Cursor/Windsurf 等同步工具的本质区别：Devin 不需要开发者持续在旁监督，而是接受委派后自主完成，最终交付一个干净的 PR。

📖 阅读 4：Getting AI to Work In Complex Codebases

来源： github.com/humanlayer/advanced-context-engineering-for-coding-agents

🔗 课堂关联： 第一讲 Slides 12-14（优化代码库、Agent 配置文件）的深度展开。课堂给出了高层建议，这篇文章提供了在真实复杂代码库中实施上下文工程的具体方法。

核心概念

"Advanced Context Engineering"——在复杂代码库中，上下文工程（而非简单的 prompt engineering）是让 AI 有效工作的关键。这包括：如何组织代码让 agent 可导航、如何策划上下文让 agent 获得恰好足够的信息、如何避免上下文过载。

与阅读 2（How Long Contexts Fail）互为补充：阅读 2 解释了为什么上下文管理重要，阅读 4 解释了怎么做。

📖 阅读 5：How FAANG Vibe Codes

来源： Twitter/X @rohanpaul_ai

🔗 课堂关联： 行业视角补充——大厂如何在实际产品开发中使用 AI 编程工具。

📖 阅读 6：Writing Effective Tools for Agents (Anthropic)

来源： Anthropic Engineering Blog，2025 年 9 月

🔗 课堂关联： 这篇文章横跨第二周（MCP 工具构建）和第三周（IDE 中使用工具），是从 Anthropic 内部视角总结的工具设计最佳实践。

核心论点：Tools 是确定性系统和非确定性 Agent 之间的新型"契约"

传统软件中，getWeather("NYC") 总是以完全相同的方式获取纽约天气。但当用户问"今天需要带伞吗？"，agent 可能调用天气工具、可能直接从知识回答、也可能先问你在哪个城市——这就是非确定性。

工具设计的五大原则

① 选择正确的工具（不是越多越好）

常见错误：把现有 API 端点一对一映射为 MCP 工具。Agent 的"可供性"（affordances）不同于传统软件。

💡 正确做法——合并功能：

❌ 分别实现 list_users + list_events + create_event
✅ 实现一个 schedule_event 工具，内部处理查找可用时间和创建事件
❌ 实现 read_logs 工具
✅ 实现 search_logs 工具，只返回相关日志行及周围上下文

🔗 课堂关联： 第二周 "APIs don't make good MCP tools"（阅读 6）从理论上论证了为什么不能简单转换 API。这篇文章从实践上给出了正确的替代方案。

② 命名空间化工具（Namespacing）

当 agent 接入数十个 MCP Server 和数百个工具时，命名空间帮助 agent 区分工具边界。例如：asana_search vs jira_search，asana_projects_search vs asana_users_search。

③ 返回有意义的上下文

优先返回高信号信息，避免低级技术标识符。

❌ 返回 uuid, 256px_image_url, mime_type
✅ 返回 name, image_url, file_type

将 UUID 解析为语义化的自然语言显著减少幻觉并提高检索精度。

支持 response_format 参数："concise"（72 token）vs "detailed"（206 token），让 agent 控制返回的详细程度。

④ 优化 Token 效率

实现分页、范围选择、过滤和截断，并设置合理的默认值。Claude Code 默认限制工具响应为 25,000 token。

在截断响应中引导 agent 采取更高效的策略：

Results truncated (showing 50 of 342 matches).
Tip: Use the 'filter' parameter to narrow results,
e.g., filter="status:open AND assignee:jane"

错误响应也要有帮助性——给出具体的修正建议而非不透明的错误码。

⑤ Prompt 工程化工具描述

把工具描述当作给新同事的说明来写——把你隐含的上下文（专用查询格式、术语定义、资源间关系）显式化。

Claude Sonnet 3.5 在 SWE-bench 上通过精确优化工具描述达到了 SOTA——即使是小的描述改进也能产生巨大的效果。

协作流程：用 Agent 优化 Agent 的工具

Anthropic 推荐一个迭代循环：

原型： 快速搭建工具，本地测试
评估： 生成大量评估任务（受真实场景启发），运行评估
协作： 把评估结果交给 Claude Code 分析，让它自动改进工具描述和实现
验证： 用留出的测试集确保没有过拟合

在内部实验中，Claude 优化后的工具超过了人类专家手写的工具的性能。

🔗 课堂关联： 第一周课堂 Best Practice "迭代你的 prompt"在这里扩展为"迭代你的工具"——用同样的评估-改进循环优化工具描述、返回格式、命名空间。

🔗 六篇阅读材料的核心交叉主题

1. Spec 驱动开发成为新范式

阅读 1 从产品角度论证 Spec = 新源代码，课堂 Slides 9-10 给出了八要素框架，Silas 在第二讲中展示了 Devin 的 Plan→Build→Review 工作流——Planning（写 Spec）是人类主导的阶段，也是价值最高的阶段。

完整理解链： 第一周 Prompt 技术 → 第三周 Specs Doc 八要素（课堂）→ 阅读 1 理论论证 → Silas 的 Plan→Build→Review 实践

2. 上下文管理是 AI IDE 的核心挑战

阅读 2 系统分类了四种上下文失败模式，阅读 4 提供了在复杂代码库中管理上下文的实践方案，阅读 6（Anthropic）从工具设计角度优化上下文质量。课堂展示了 IDE 的底层方案（RAG + Merkle Tree 增量更新）。

完整理解链： 第一周上下文窗口限制 → 第二周 MCP 工具消耗上下文 → 阅读 2 四种失败模式 → 课堂 IDE 底层方案 → 阅读 4/6 实践对策

3. 人类角色从编码者转变为管理者

Silas 的"三个时代"（10%→20%→6-12×）量化了这个转变。阅读 1 论证了 PM 的新价值。课堂的 Agent 配置文件（CLAUDE.md, AGENTS.md）是这个新角色的基础设施。

完整理解链： 第一周"你不会被 AI 取代，但会被善用 AI 的工程师取代" → 第二周 Agent 循环架构 → 第三周 Silas 的同步/异步框架 → 阅读 1 "沟通最有效的人 = 最有价值的程序员"

4. 工具设计需要"为 Agent 而非为人类"重新思考

阅读 6（Anthropic）系统化了工具设计原则，与第二周阅读 6（APIs don't make good MCP tools）形成完整的论证链：不要照搬传统 API，要从 agent 的视角重新设计工具。

🔗 课程脉络： 第 1 周学"prompt"，第 2 周学"tool"，第 3 周学"spec + context + workflow"。下一周（第 4 周）将深入"如何管理 agent 的自主性"——从工具层上升到协作模式层。