\documentclass[a4paper]{article}

% Basic packages
\usepackage[fontset=fandol]{ctex}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage[margin=2.5cm]{geometry}
\usepackage[most]{tcolorbox}
\usepackage{etoolbox}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{float}

% Highlight boxes
\newtcolorbox{knowledgebox}[1]{
    enhanced, colback=blue!5!white, colframe=blue!75!black, colbacktitle=blue!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, attach boxed title to top left={yshift=-2mm, xshift=2mm},
    boxrule=1pt, sharp corners
}

\newtcolorbox{importantbox}[1]{
    enhanced, colback=yellow!10!white, colframe=yellow!80!black, colbacktitle=yellow!80!black,
    coltitle=black, fonttitle=\bfseries, title=#1, sharp corners
}

\newtcolorbox{warningbox}[1]{
    enhanced, colback=red!5!white, colframe=red!75!black, colbacktitle=red!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, sharp corners
}

% Listings
\lstset{
    language=Python,
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    stringstyle=\color{red!60!black},
    commentstyle=\color{green!60!black},
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray},
    captionpos=b,
    extendedchars=false
}

% Front-page metadata
\newcommand{\notetitle}{CS146S Week 3: The AI IDE (Context Engineering)}
\newcommand{\noteauthors}{基于 Mihail Eric + Silas Alberti (Cognition/Devin) 授课内容整理}
\newcommand{\notedate}{2025年10月}
\newcommand{\videochannel}{Stanford CS146S}
\newcommand{\videopublishdate}{Fall 2025}
\newcommand{\videoduration}{2 lectures (Mon + Fri)}
\newcommand{\videourl}{https://themodernsoftware.dev}
\newcommand{\videocoverpath}{}
\newcommand{\repourl}{https://github.com/hqhq1025/ai-course-notes}


% Footer with repo info
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyfoot[C]{\thepage}
\fancyfoot[R]{\footnotesize\color{gray}\href{\repourl}{AI Course Notes}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

\begin{document}

\begin{titlepage}
\centering
{\Large 课程笔记\par}
\vspace{1.2cm}
{\huge\bfseries \notetitle\par}
\vspace{0.8cm}
{\large \noteauthors\par}
\vspace{0.3cm}
{\large \notedate\par}
\vspace{1.2cm}

\ifdefempty{\videocoverpath}{
\vspace{3cm}
}{
\includegraphics[width=0.82\textwidth,height=0.45\textheight,keepaspectratio]{\videocoverpath}\par
}

\vfill
\begin{tcolorbox}[width=0.9\textwidth, colback=black!2!white, colframe=black!60, sharp corners]
\textbf{课程}：\videochannel\par
\textbf{学期}：\videopublishdate\par
\textbf{讲次}：\videoduration\par
\textbf{网站}：\href{\videourl}{\nolinkurl{\videourl}}\par
\textbf{项目主页}：\href{\repourl}{\nolinkurl{\repourl}}\par
\end{tcolorbox}
\end{titlepage}

\tableofcontents
\newpage

%% --- 正文内容开始 --- %%

\section{AI IDE 的演进与核心能力}

\subsection{IDE 简史}

IDE（Integrated Development Environment）是软件开发的核心工作环境，集编辑器、编译器、调试器等于一体。其演进历程折射出开发效率的持续提升：

\begin{itemize}
    \item \textbf{1983}：Turbo Pascal——第一个真正的 IDE
    \item \textbf{1997}：Microsoft Visual Studio——高级调试能力（C++/Visual Basic）
    \item \textbf{2001}：IntelliJ IDEA——上下文代码导航、重构、代码补全
    \item \textbf{2015}：VSCode——轻量编辑器 + 高度可扩展的插件生态
    \item \textbf{2023}：Cursor——首批广泛使用的 AI 原生 IDE
\end{itemize}

\begin{knowledgebox}{IDE 演进中的``钟摆效应''}
IDE 的发展历程中，功能整合与开发者定制之间一直存在``钟摆效应''（see-saw）。AI IDE 的出现再次将钟摆推向功能整合——将 AI 能力深度嵌入开发环境。
\end{knowledgebox}

\subsection{AI IDE 的使用模式}

\subsubsection{基础模式（Bread-and-Butter）}

\begin{itemize}
    \item \textbf{Inline}：行内代码补全
    \item \textbf{Function}：函数级生成
    \item \textbf{Single-file}：单文件编辑
    \item \textbf{Multi-file}：跨文件修改
\end{itemize}

\subsubsection{AI 原生模式}

\begin{itemize}
    \item \textbf{Background Agents}：后台自主执行任务
    \item \textbf{MCP 集成}：通过 MCP 协议连接外部工具
    \item \textbf{Memories}：学习并记住用户偏好和项目上下文
    \item \textbf{Bugbot / PR Review}：自动化代码审查
\end{itemize}

\subsection{AI IDE 的底层原理}

\subsubsection{Tab-complete（代码补全）}

\begin{enumerate}
    \item 将当前代码周围的小 context window 加密发送到服务器
    \item 服务器运行 infilling LLM
    \item 建议返回并显示在编辑器中
\end{enumerate}

\subsubsection{Chat（对话模式）}

\begin{enumerate}
    \item 将代码块存储为 embedding，建立 semantic index（使用混淆的文件名 + 代码）
    \item 用户查询时检索最相关的代码块，作为 context 注入 LLM
    \item IDE 定期重新索引代码块并同步 embedding
    \item 通过 Merkle tree 计算代码块的 diff，实现高效更新
\end{enumerate}

\begin{importantbox}{Merkle Tree 在代码索引中的应用}
Merkle tree 是一种哈希树结构，常用于 Git 和区块链。在 AI IDE 中，Merkle tree 被用来高效检测代码变更：只有发生变化的代码块需要重新计算 embedding，避免了全量重建索引的开销。
\end{importantbox}

\subsection{本章小结}

AI IDE 通过 tab-complete 和 chat 两种模式将 LLM 深度嵌入开发工作流。其底层依赖代码的 semantic indexing 和高效的增量更新机制。理解这些原理有助于更有效地利用 AI IDE 的能力。

\section{Context Engineering：让 AI 理解你的代码}

\subsection{从简单提示到产品经理式规格书}

对于简单变更，随意的 prompt 即可。但对于复杂任务，开发者需要扮演产品经理（PM）的角色，撰写精心设计的规格文档（spec doc）。

\begin{importantbox}{完整的 Spec Doc 结构}
\begin{itemize}
    \item \textbf{Goal}：变更的目的是什么
    \item \textbf{Definitions}：LLM 需要了解的前置知识
    \item \textbf{Plan}：高层次的实现方案拆解
    \item \textbf{Source files}：涉及的代码文件及其相关性
    \item \textbf{Test cases}：如何进行测试
    \item \textbf{Edge cases}：需要处理的特殊情况
    \item \textbf{Out-of-scope}：哪些内容不应该被修改
    \item \textbf{Extensions}：未来可能的扩展方向（帮助 LLM 做出前瞻性设计，避免走捷径）
\end{itemize}
\end{importantbox}

\subsection{优化代码库以适应 AI}

\begin{warningbox}{LLM 困惑的根源往往是代码库本身}
很多时候 LLM 产生不好的结果，不是模型能力不够，而是代码库太混乱。如果一个新加入团队的人类工程师也会对你的代码库感到困惑，LLM 同样会。
\end{warningbox}

优化代码库的关键维度：
\begin{itemize}
    \item \textbf{Repo orientation}：仓库的总体介绍
    \item \textbf{File structure}：清晰的目录结构
    \item \textbf{Setup and environment}：环境配置说明
    \item \textbf{Code style}：代码风格约定
    \item \textbf{Access patterns}：数据访问模式
    \item \textbf{APIs and contracts}：API 接口和约定
\end{itemize}

提示：\textbf{Monorepo 设计}在 AI 编程场景下被强烈推荐，因为它使 Agent 更容易理解项目全貌。

\subsection{Agent 配置文件}

\begin{itemize}
    \item \textbf{CLAUDE.md}：Claude Code 自动加载的项目说明文件，适合放置常用 bash 命令、核心文件和工具函数、代码风格指南、测试指令等
    \item \textbf{.cursorrules}：Cursor 的项目规则文件
    \item \textbf{AGENTS.md}：开放格式的 Agent 指导文件
    \item \textbf{llms.txt}：为 LLM 网络爬虫提供导航指引
\end{itemize}

\begin{warningbox}{Agent 不会总是遵守配置文件}
这些描述和指令只是\textbf{指导}（guidance），Agent 并不总是严格遵守。不要依赖配置文件来实现关键的安全约束或不变量。
\end{warningbox}

\subsection{本章小结}

Context engineering 的核心是：为 LLM 提供最优的上下文信息。这包括撰写结构化的 spec doc、优化代码库组织、以及利用 Agent 配置文件。目标是让人类和 Agent 都能轻松理解项目。

\section{同步 vs 异步工具：AI 编程的三个时代}

\subsection{嘉宾讲座：Silas Alberti (Cognition/Devin)}

Cognition 研究负责人 Silas Alberti 分享了 AI 编程工具的演进路径和最佳使用策略。

\subsection{AI 编程工具的三个时代}

\begin{enumerate}
    \item \textbf{Code Completion}（$\sim$10\% 效率提升）：GitHub Copilot 加速编码
    \item \textbf{IDE Automation}（$\sim$20\% 效率提升）：AI IDE 实现单人任务完成
    \item \textbf{AI Software Engineer}（6--12$\times$ 效率提升）：云端 Agent 实现并行工作流
\end{enumerate}

\begin{importantbox}{从 10\% 到 6--12$\times$：量变到质变}
从 code completion 到 cloud agent，效率提升从百分比级跃升到倍数级。关键区别在于：cloud agent 实现了\textbf{并行}——一个开发者可以同时管理多个 Agent 执行不同任务。
\end{importantbox}

\subsection{同步 vs 异步工具}

\textbf{同步工具}（Sync）：
\begin{itemize}
    \item 单线程，人在环中（human-in-the-loop）
    \item 注意力聚焦于单一任务
    \item Agent 工作 20 秒到 1.5 分钟
    \item 代表：Cursor、Windsurf
\end{itemize}

\textbf{异步工具}（Async）：
\begin{itemize}
    \item 多线程，人类委派任务后切换注意力
    \item Agent 工作 10 分钟到数小时
    \item 代表：Devin
\end{itemize}

\begin{warningbox}{``Semi-Async'' 陷阱}
在 30 秒到 3 分钟的``半异步''区间要特别小心——它太慢以至于无法保持心流（flow），又太短以至于不值得切换到其他任务。正确策略是：要么让工具更快以保持心流，要么投入更多时间换取更高的智能水平。
\end{warningbox}

\subsection{2025年的最佳编程工作流}

Silas 提出的最佳实践将三个阶段分配给不同的工具：

\begin{itemize}
    \item \textbf{Planning}（规划）：同步工具——使用 DeepWiki、Codemaps 理解代码库
    \item \textbf{Coding}（编码）：异步工具——委派给 Devin 执行
    \item \textbf{Testing}（测试）：同步工具——在 Windsurf 中测试和微调 Agent 的结果
\end{itemize}

\subsection{未来展望}

\begin{enumerate}
    \item 人类工程师成为 Agent 管理者：同步工具解决最困难的问题，异步工具获取 10$\times$ 杠杆
    \item 未来的核心技能：\textbf{委派与多线程}、\textbf{代码阅读}、\textbf{规划、范围界定和架构设计}
    \item 长期趋势：规划、编码、测试三个阶段都将逐步实现异步化和自主化
\end{enumerate}

\subsection{团队采用 AI IDE 的评估框架}

如果把 Week 3 的内容转成组织层面的判断标准，可以用下面三个问题快速评估一套 AI IDE 是否值得推广：

\begin{itemize}
    \item \textbf{它是否真正减少上下文切换？} 如果开发者仍要在大量外部文档和 prompt 模板间来回跳转，工具并未带来本质改进。
    \item \textbf{它是否让代码库更透明？} 好的 AI IDE 会放大 repo 中已经存在的结构化信息，而不是掩盖混乱。
    \item \textbf{它是否有稳定的回退机制？} 当 Agent 给出错误修改时，团队能否依赖测试、review 和清晰的 diff 快速恢复？
\end{itemize}

\begin{knowledgebox}{真正可落地的 AI IDE 必须同时优化人和仓库}
AI IDE 从来不是单纯的模型问题。它同时要求更好的代码组织、更稳定的评测体系和更清晰的项目说明。也正因此，context engineering 最终会倒逼团队重构自己的知识管理方式。
\end{knowledgebox}

\subsection{本章小结}

AI 编程工具从 code completion 演进到 cloud agent，带来了从 10\% 到 6--12$\times$ 的效率飞跃。关键是掌握同步与异步工具的正确使用场景，避免``半异步''陷阱，将规划-编码-测试分配给最合适的工具类型。

\section{总结与延伸}

Week 3 从两个互补的视角探讨了 AI IDE 和编程工具的最佳使用方式：Mihail Eric 聚焦于 context engineering 的方法论（spec doc、代码库优化、Agent 配置文件），Silas Alberti 则从工具选择的角度给出了同步/异步的决策框架。

\subsection{关键要点}

\begin{itemize}
    \item AI IDE 底层依赖 semantic indexing（embedding + Merkle tree）和 infilling LLM
    \item 复杂任务需要 PM 式的 spec doc，包含 goal、plan、source files、edge cases 等
    \item 优化代码库本身比优化 prompt 更根本——monorepo 设计被推荐
    \item AI 编程工具三个时代：completion $\rightarrow$ IDE automation $\rightarrow$ cloud agent
    \item 同步工具保持心流，异步工具实现并行，避免``半异步''陷阱
    \item 未来核心技能：委派、代码阅读、架构规划
\end{itemize}

\subsection{实践顺序建议}

\begin{enumerate}
    \item 先为 repo 补齐 orientation 文档、测试命令和关键文件说明
    \item 再引入 AI IDE 做小范围高频任务，如问答、单文件修改和 spec 驱动改动
    \item 最后再把更长链路的编码与测试交给异步 Agent，形成同步与异步协作的闭环
\end{enumerate}

\subsection{拓展阅读}

\begin{itemize}
    \item Cursor 官网：\url{https://cursor.sh}
    \item Cognition / Devin：\url{https://devin.ai}
    \item Windsurf：\url{https://codeium.com/windsurf}
    \item CLAUDE.md 最佳实践：\url{https://docs.anthropic.com/en/docs/claude-code}
    \item AGENTS.md 规范：\url{https://github.com/anthropics/agents-md}
\end{itemize}

%% --- 正文内容结束 --- %%

\end{document}
