80AJ / 大模型编程白皮书
Model Tool Result while True: resp = call_model(ctx) context.append(result) get_user_by_email L0: always_apply L1: file_match
2026 Edition 8 Chapters

大模型编程白皮书

从原理到工程实践——一份写给工程师的 LLM 编程指南。
不讲概念堆砌，只讲你明天写代码就能用上的东西。

编撰：toy @ 80AJ 来源：25 篇技术文章蒸馏 日期：2026-05-13

CHAPTER 01 LLM 的工作本质

不理解发动机的人没资格谈驾驶技术。用 LLM 写代码之前，先搞明白它到底在干什么。

自回归：边说边想

大模型生成文本的方式是一个 token 一个 token 往外蹦。没有"先想好再说"这回事——它预测下一个词的时候，唯一的依据就是前面所有的词。

这个机制的直接后果：模型写代码跟人类完全不一样。人会先在脑子里构思一个大致方案，然后落笔实现。模型做不到。它写第 50 行的时候，看到的只有前 49 行和你给它的提示，没有"全局规划"这个概念。

Chain-of-Thought（思维链）为什么有效？它给了模型更多的中间 token 来铺垫推理过程，跟"教会模型思考"没什么关系。多写几步中间推导，下一个 token 的预测就更准。拿输出空间换计算深度，仅此而已。

注意力的物理极限

Attention 机制决定了模型能"同时看到"多少信息。计算复杂度是 O(n²)，上下文长度翻倍，计算量翻四倍。上下文窗口有物理上限，这不是工程能解决的事，是数学决定的。

更关键的一点：标称窗口大小跟有效窗口大小是两回事。

实测数据
一个标称 200K token 的模型，在 80-100K 之后性能开始明显退化。上下文中间 40-60% 的区域存在"注意力盲区"（Lost in the Middle），模型对这个区域的信息处理质量显著下降。

实际工程含义：别想着把所有文档一股脑塞进去。200K 的窗口，你有效利用的大概只有开头和结尾的 40%。

Coding Agent 的五个先天缺陷

这些不是 bug，是架构层面的固有限制：

  1. 局部最优：一步步续写不等于全局规划。模型容易写到一半发现路走偏了，然后打补丁而不是重新设计。
  2. 偏差滚雪球：前面做了一个错误假设，后面整段代码在错误的世界观里自圆其说。越写越远，而且自己不知道错了。
  3. 改不回去：模型倾向于重写而不是精确局部编辑。你让它改一行，它可能给你重写半个文件。
  4. 并发约束力弱：边界条件、并发控制、错误处理——这些需要"同时想多件事"的场景，模型天然吃力。
  5. 单线程决策：方案选择容易一条路走到黑，缺少系统性对比多个候选方案的能力。

后面所有章节讲的"最佳实践"，都是在想办法绕开这五条限制。知道为什么要这么做，比知道怎么做更有用。

CHAPTER 02 Agent Loop：智能体的心跳

大模型本身只会说话。加上工具调用的循环，它才能做事。

核心循环

一个 Coding Agent 的运行机制其实很朴素：

while True:
    response = call_model(context)
    if response.stop_reason == "end_turn":
        break                      # 任务完成
    if response.stop_reason == "tool_use":
        result = execute_tool(response.tool_call)
        context.append(result)     # 把工具结果塞回上下文
        continue                   # 继续循环
    if response.stop_reason == "max_tokens":
        raise Error("上下文爆了")  # 截断，需要处理

就这么一个循环。模型说"我要用工具"，系统就去执行工具，把结果喂回来；模型说"我说完了"，循环结束。所谓的"智能"，全部发生在每次 call_model 的推理过程中。

上下文的生命周期

每次循环迭代，上下文都在膨胀。工具返回的结果、模型的中间推理、历史对话——全都堆在同一个窗口里。一旦超过有效上下文范围，模型的表现会急剧劣化。

常用的缓解策略：

一个反直觉的数字
有效上下文中真正对当前任务有用的信息大约只占 10-15%。换算成工作时长，一个 Agent 在单次对话中的有效工作时间大约 5-10 分钟。超过这个时间，要么开新对话，要么接受质量下降。

短对话 + 多轮迭代远好于一个超长对话。开新对话 = 干净上下文 = Agent 回到最佳状态。道理就这么简单。

CHAPTER 03 上下文工程

窗口里放什么，模型就"知道"什么。放错了比不放更糟。

短对话策略

一个功能不应该在一个对话里从头做到尾。正确的节奏是：

  1. 一个对话做调研：读代码、理解现状、列方案
  2. 一个对话做实现：只带必要上下文，写核心代码
  3. 一个对话做错误处理和边界情况
  4. 一个对话写测试
  5. 一个对话做代码审查和清理

对话之间怎么传递上下文？不靠模型记忆——靠 Git 状态、项目文档、文件引用。每次新对话打开时，Agent 通过读取这些外部状态来恢复进度。

判断该不该开新对话的信号：

渐进式索引

代码仓库里有两种知识：代码能表达的（函数签名、类型定义、测试用例）和代码表达不了的（为什么选了这个方案而不是那个、配置背后的业务规则、团队的隐性约定）。

后者才是 Agent 真正缺的。把所有文档一次性塞进上下文？最直觉的做法，也是最蠢的。token 超限不说，一堆不相关的信息反而干扰判断。

渐进式索引换了个思路，分两层：

层级内容加载时机token 开销
第一层：元数据文件名 + 一句话描述（YAML frontmatter）Agent 启动时全量加载每个文档约 30-50 tokens
第二层：正文完整业务逻辑（Markdown body）Agent 判断相关时按需读取按需，无上限

Agent 启动时扫一遍所有文档的标题和描述，心里有个目录。接到任务后，根据关键词匹配，只去读相关的那几篇全文。

你写代码也是这么干的——先翻目录，觉得哪个相关再点进去看，不会每次把所有文档从头到尾读一遍。

CHAPTER 04 Rules：规则即接口

Rules 写得差，Agent 就乱来。写得好，它比人类同事更守规矩。区别在于你怎么组织这些规则。

四种生效方式

把所有规则写在一个大文件里，早晚出问题。文件越长越难维护，不同场景的规则揉在一起互相打架，该生效的时候不生效、不该生效的时候到处乱入。拆开，分场景控制。

方式什么时候用典型场景
始终生效任何任务都不应违背的底线输出用中文、不删文件、代码风格
指定文件生效只在特定文件类型或目录下触发**/*.sql 迁移规范、apps/web/** 前端规范
智能生效偶尔需要、但出现时很重要问题排查 checklist、性能优化规则
手动触发高风险操作，误触会造成麻烦发布/回滚 SOP、数据库迁移流程

L0–L3 分层模型

按规则的职责域分四层，每层对应不同的生效策略：

检验标准
一条 Rule 能不能用一句话说清它约束什么？不能就继续拆。
持续把对话带偏的规则降级为智能/手动触发，或者直接删掉。
配置文件是最高杠杆点——一行写错的规则会影响你的每一次对话。

CHAPTER 05 Skills：能力封装

Rules 告诉 Agent 什么该做什么不该做。Skills 告诉它怎么做一件具体的事。

设计方法论

Skill 就是一段结构化的指令，教 Agent 怎么做一件具体的事。写多少字不重要，写没写清楚这几个问题才重要：

  1. 什么时候触发？——触发条件要明确，不能让 Agent 猜。
  2. 输入是什么、输出是什么？——边界清晰，不留模糊地带。
  3. 什么时候停？——完成标准必须可验证，不能是"差不多就行了"。

Skills 采用三层披露机制控制 token 消耗：

跟前面讲的渐进式索引一个道理：先给个目录，按需加载详情，别一上来就把所有东西都塞进去。

需求工程 Skill：一个完整范例

这个 Skill 解决的问题很具体：工程师给了一句话需求（"对话流头像加个时间戳"），Agent 直接开写，结果时间戳位置乱放、hover 行为缺失、国际化遗漏、样式跟现有组件不统一。

Agent 跳过了需求工程环节，拿到一句话就直接写。这个 Skill 补上了这一步，用传统软件工程的方法走一遍：

  1. 需求启发：从 7 个维度挖掘——意图、涉众、引入什么、不引入什么、系统集成点、完整性、质量要求。跟用户反复对齐信息差。
  2. 需求分析：分类（功能/非功能/接口/转换需求），检测冲突。
  3. 需求定义：产出结构化的需求规格说明书（Spec），10 个维度全覆盖。
  4. 技术设计：产出 RFC——现状分析、目标状态、设计选项对比、详细设计。每个决策可追溯到需求编号。
  5. 验证：9 项质量 checklist——完整性、一致性、正确性、可行性、必要性、优先级、可追溯性、清晰性、可验证性。
关键设计决策
开发前必须人类确认：Spec 和 RFC 产出后，Agent 停下来等用户签字。不允许自己决定开干。
开发后禁止中断：一旦确认开始实现，就不再停下来问"这样行不行"。减少上下文切换。

Session-Learning：即时经验捕获

另一个值得借鉴的机制。开发过程中解决了一个棘手问题之后，跟 Agent 说一句："这个问题解决了，帮我总结一下经验，看看要不要加新 skill。"

Agent 就会自动按项目规范写一个新的 Skill 文件，沉淀这次的经验。下次遇到同类问题，这个经验就能被自动加载。

不用等复盘会，不用手动写文档。问题解决的那个瞬间，顺手就把经验沉淀了。

CHAPTER 06 MCP 工具设计

给人设计 API，跟给 AI 设计工具，是两件完全不同的事。

Agent 怎么"看"工具

当你给 Agent 注册一个 MCP 工具时，它能看到三样东西：名称、描述、参数 Schema。就这些。没有文档链接，没有示例代码，没有 Postman 集合。

REST API 的使用者是程序员——看完文档，试几次，debug 几轮，搞定。Agent 的"试错"成本高得多：每次失败消耗 token，污染上下文历史，而且没有跨会话记忆。今天踩的坑，明天开新对话照踩。

所以设计 MCP 工具只有一条标准：Agent 看到名字和描述，第一次就能用对。做不到就回去改。

六维设计法

1. 输入设计：降低出错概率

2. 输出设计：给可操作的信息

3. 错误处理：帮 Agent 自救

4. 工具粒度

5. 命名规范

6. 描述四要素

每个工具的描述需要回答：What（做什么）、When（什么时候用）、Constraints（有什么限制）、Output（返回什么）。参数描述必须带示例："owner/repo format, e.g. 'facebook/react'"。

CHAPTER 07 复利工程

修一个 bug 不算什么。修一个 bug 的同时让系统以后不再出同类 bug，这才叫工程。

复利工程（Compounding Engineering）说白了就一件事：每次跟 AI 的交互都应该让下一次更顺。

修了一个 bug？想想这类问题的根因，更新规则或者加个 Skill，让它下次不犯。做了一次代码审查？把教训提炼出来写进项目配置。跑通了一个工作流？记下来做模板。

你不是在解决问题。你在训练一个系统。

项目配置文件

不管你用的是 CLAUDE.md、AGENTS.md 还是 TRAE 的 Rules，好的配置文件都在回答三个问题：

  1. WHAT——技术栈、目录结构、关键依赖
  2. WHY——核心设计决策及其理由
  3. HOW——怎么跑、怎么测、怎么部署
硬指标
配置文件控制在 300 行以内。模型能可靠遵循的指令上限大约 150-200 条。超过这个数，它会开始选择性忽略——而你不知道它忽略了哪些。

配置文件不是文档库，是路由器。告诉 Agent 有什么可读的，它自己去读。把什么都往里塞，跟把整个图书馆搬到门卫室一个效果。

AI-Friendly DX

对人难的事，对 AI 也难。这点可能违反直觉，但想想就能理解。

好文档、清晰架构、快反馈、明确的错误信息，这些对 AI 和人一样重要。所谓 "AI-Friendly DX" 就是好的软件工程实践，没什么新东西。

几条具体的：

CHAPTER 08 实战数据

方法论说得再好听，不如一组控制变量实验。

Loop 修复率实验

这是这批资料中唯一一个有严格对照的实验。在一个大型 IDE 项目（iCube-Mono）中，用 32 个真实业务 Bug 做测试集：

59%
无 Skills 时的 Loop 自动修复率（19/32）
100%
有 Skills 后的 Loop 自动修复率（32/32）

失败的 13 个 case 都是同一个原因：Agent 看不到做决策需要的业务上下文。LLM 的推理能力够了，信息不够。

几个典型案例：

Bug无 Skill 结果有 Skill 结果关键差异
Solo 模式快捷键不生效失败修复需要知道 Solo/Duo 模式的切换逻辑
智能体 Panel 保存无反应失败修复需要知道 Panel 状态管理的架构
文件引用唤不起对话框失败修复VSCode DI 规范：禁止异步方法后取 service
模型选中后光标定位问题失败修复Radix UI Select 组件的焦点处理细节

一句话：喂对信息比换更强的模型管用。

效率度量

另一组数据来自"用 Trae 开发 Trae"的实践——用 AI IDE 给自己加功能（AWS Bedrock 供应商支持）：

7 → 3.5
人日。同等功能开发时间减半。
50%
人类编写代码占比。另外 50% 由 AI 生成。

别简单理解成"AI 写了一半代码所以快一倍"。实际省时间的地方不在写代码本身：

  1. 调研阶段：Agent 快速扫描代码库定位相关文件，省去了人肉翻代码的时间。
  2. 样板代码：配置文件、类型定义、测试桩这些重复性工作交给 Agent。
  3. 跨上下文知识：Agent 可以同时"记住"多个文件的内容，人在这方面靠短期记忆，效率低得多。

Design-to-Code 三方案对比

Figma 设计稿转代码，目前有三条路：

方案精度上手成本适用场景
Figma Local MCP + Code Connect最高高组件库成熟的团队
TRAE Figma 集成中低快速原型、小团队
自定义 IR 脚本可控高有特殊需求的团队

团队有成熟组件库的，方案一精度碾压。快速验证想法，方案二门槛最低。方案三维护成本太高，除非你有很具体的定制需求，别碰。

APPENDIX LLM 语言污染警示

用 LLM 写代码的你，可能已经在不知不觉中被 LLM 改变了说话方式。

Flask 框架的作者 Armin Ronacher 做了一个实验：从自己 90 天的编程对话记录中提取中频词，跟英语词频数据库做对比。

结果发现一批词的使用频率出现了显著偏移：nuanced、substrate、streamline、leverage、delve、comprehensive。这些词在 Google Trends 上也呈现一致的上升趋势。

问题不只是 LLM 生成的文本充斥了网上。更隐蔽的是，你跟 AI 对话越多，你自己说话写字就越像 AI。这个渗透是双向的。

更深层的问题：信任

当你分不清一段文字是人写的还是 AI 生成的时候，会发生什么？

批量发 AI 内容已经是付费服务了。速度优势让垃圾在算法层面胜出，人写的东西反而没人看到。

我们能做什么

写给这篇白皮书本身
这份白皮书用了 LLM 辅助整理。原始资料里的判断和数据我们尽量保留了，但读着要是觉得哪段话特别"顺"，那八成就是 LLM 的痕迹。保持警觉。

SOURCES 资料来源

本白皮书的内容蒸馏自以下 25 篇技术文章，按主题归类：

LLM 原理与 Agent 架构

MCP 工具设计

Rules 与 Skills

上下文工程与工程实践

其他参考