第一性原理拆解 Agentic Coding：学习笔记

文章目录

[第一性原理拆解 Agentic Coding：学习笔记](#第一性原理拆解 Agentic Coding：学习笔记)
- [1. 一句话结论](#1. 一句话结论)
- [2. 全文知识主线](#2. 全文知识主线)
- - [2.1 第一性原理推导框架](#2.1 第一性原理推导框架)
- [3. 底层原理](#3. 底层原理)
- - [3.1 LLM（大语言模型）的本质：预测下一个 token](#3.1 LLM（大语言模型）的本质：预测下一个 token)
  - [3.2 Autoregressive（自回归）机制在编程任务中的5类局限](#3.2 Autoregressive（自回归）机制在编程任务中的5类局限)
  - [3.3 Attention（注意力）机制：模型如何使用 context](#3.3 Attention（注意力）机制：模型如何使用 context)
  - [3.4 Reinforcement Learning（强化学习）：从"会说"到"会做"](#3.4 Reinforcement Learning（强化学习）：从"会说"到"会做")
- [4. 编程 Agent 如何工作](#4. 编程 Agent 如何工作)
- - [4.1 基本构成](#4.1 基本构成)
  - [4.2 Agent Loop（智能体循环）](#4.2 Agent Loop（智能体循环）)
  - [4.3 典型 Tool 分类](#4.3 典型 Tool 分类)
  - [4.4 Prompt Cache（提示词缓存）的工程含义](#4.4 Prompt Cache（提示词缓存）的工程含义)
- [5. 常见失效机制与应对方法](#5. 常见失效机制与应对方法)
- [6. 核心实践：短对话、单目标](#6. 核心实践：短对话、单目标)
- - [6.1 为什么短对话更有效](#6.1 为什么短对话更有效)
  - [6.2 对话是任务的基本执行单元](#6.2 对话是任务的基本执行单元)
  - [6.3 何时应该开启新对话](#6.3 何时应该开启新对话)
- [7. 项目说明文件的设计](#7. 项目说明文件的设计)
- - [7.1 项目说明文件的定位](#7.1 项目说明文件的定位)
  - [7.2 编写原则](#7.2 编写原则)
  - [7.3 建议结构](#7.3 建议结构)
- [8. Context 管理策略](#8. Context 管理策略)
- - [8.1 Observation Masking（观察遮蔽）](#8.1 Observation Masking（观察遮蔽）)
  - [8.2 History Summarization（历史摘要）](#8.2 History Summarization（历史摘要）)
  - [8.3 推荐用法](#8.3 推荐用法)
- [9. 复利工程：让每次工作改善未来](#9. 复利工程：让每次工作改善未来)
- - [9.1 缺陷修复闭环](#9.1 缺陷修复闭环)
  - [9.2 Code Review（代码审查）闭环](#9.2 Code Review（代码审查）闭环)
  - [9.3 成功流程沉淀](#9.3 成功流程沉淀)
- [10. 对人友好，也要对 Agent 友好](#10. 对人友好，也要对 Agent 友好)
- - [10.1 高价值工程投资](#10.1 高价值工程投资)
  - [10.2 Agent 友好的 Tool 设计](#10.2 Agent 友好的 Tool 设计)
  - [10.3 用工程约束代替反复提醒](#10.3 用工程约束代替反复提醒)
- [11. 可直接复用的实操流程](#11. 可直接复用的实操流程)
- - [11.1 开始任务](#11.1 开始任务)
  - [11.2 调查阶段](#11.2 调查阶段)
  - [11.3 实现阶段](#11.3 实现阶段)
  - [11.4 完成阶段](#11.4 完成阶段)
  - [11.5 Session 交接模板](#11.5 Session 交接模板)
- [12. 阅读时需要辨析的观点](#12. 阅读时需要辨析的观点)
- [13. 个人刻意练习计划](#13. 个人刻意练习计划)
- - 第1阶段：学会给出可验证任务
  - [第2阶段：学会管理 context](#第2阶段：学会管理 context)
  - [第3阶段：建立 feedback 闭环](#第3阶段：建立 feedback 闭环)
  - 第4阶段：形成复利
  - 第5阶段：培养专家型通才能力
- [14. 最终记忆卡片](#14. 最终记忆卡片)

1. 一句话结论

编程 agent（智能体）不是"会自主思考的软件工程师"，本质是受 context（上下文）约束的概率生成模型，套上 tool calling（工具调用）、环境反馈和 loop control（循环控制）之后变成了任务执行系统。

所以高效协作的关键压根不是把 context 塞满------而是缩小任务、给够必要信息、建立快速 feedback（反馈）、显式保存 state（状态），把每次经验沉淀成可复用的工程资产。

2. 全文知识主线

复制代码

逐 token（词元）预测
  ↓
模型只能根据当前 context 继续生成
  ↓
长任务容易出现 local optimum（局部最优）、错误累积和 attention（注意力）稀释
  ↓
通过 tool calling 与执行 feedback 形成 agent loop（智能体循环）
  ↓
通过短对话、任务拆分、external memory（外部记忆）和工程验证控制风险
  ↓
通过文档、测试、规则和流程沉淀形成复利

2.1 第一性原理推导框架

遇到任何 agent 编程技巧，不先问"别人怎么用"，而是依次追问5个问题：

可观察事实：模型实际做了什么？逐 token 生成、依赖当前 context、通过 tool 影响外部环境。
不可回避的约束：哪些限制靠 prompt（提示词）解决不了？context 有限、输出有概率性、长 chain（调用链）会累积误差。
系统设计要求：为了补偿这些限制，系统必须具备什么？tool calling、环境 feedback、loop control、external state（外部状态）存储。
工作流实践：使用者应该怎样组织任务？单目标短对话、先调查后修改、逐步验证、及时交接。
客观验证：怎么证明结果正确？build（构建）、test（测试）、static analysis（静态分析）、bug reproduction（缺陷复现）和 acceptance checklist（验收清单）。

把零散技巧还原成稳定的因果链就长这样：

复制代码

事实：模型只依据当前 context 逐步生成
  ↓
约束：信息会稀释，错误会累积，state 不会自动跨 session（会话）保存
  ↓
设计：引入 tool、feedback loop（反馈循环）、external memory 和任务控制
  ↓
实践：缩小任务、精简 context、显式记录、频繁验证
  ↓
结果：降低偏离、rework（返工）、成本和不可验证风险

判断一条实践是否有效，核心看它是否提高了有效信息密度、缩短了 feedback 路径、减少了 implicit state（隐含状态），或增强了结果的可验证性。

3. 底层原理

3.1 LLM（大语言模型）的本质：预测下一个 token

模型每次根据"用户输入 + 已有 context + 刚刚生成的内容"预测下一个 token，再把新 token 加入序列继续预测。这种逐步生成机制带来3个直接结论：

推理依赖生成过程------模型不是先完整想好再输出，而是在生成中逐步形成答案。复杂任务需要把目标、约束和中间步骤显式化。

Context 就是 working memory（工作记忆）------当前 session 之外的信息不会自动存在。新 session 开始后，模型只能依赖重新提供的信息和能读取的外部文件。

输出具有概率性------相同输入可能产生不同结果。"看起来合理"不等于"事实正确"，必须通过编译、test、static analysis 和实际运行验证。

3.2 Autoregressive（自回归）机制在编程任务中的5类局限

Local optimum（局部最优）：逐步续写容易先完成眼前代码，却忽略全局架构、cross-file consistency（跨文件一致性）和迁移顺序。

偏差滚雪球：早期误解了需求、目录结构或接口，后续步骤会继续建立在错误假设上，越跑越偏。

擅长生成，不擅长精确修改：模型天然倾向生成新内容，复杂局部编辑可能演变成大范围重写，审查和回归成本随之上升。

强约束满足能力有限：edge case（边界条件）、concurrency（并发）、resource cleanup（资源释放）、type inference（类型推导）、cross-file reference（跨文件引用）------仅靠文本推断容易遗漏。

天然偏向单线探索：模型容易过早锁定一个方案。复杂设计和疑难排查应显式要求提出多个 hypothesis（假设），分别验证。

3.3 Attention（注意力）机制：模型如何使用 context

模型生成每个新 token 时，会对 context 中不同位置分配不同权重，再聚合相关信息------不是均匀阅读所有内容，而是动态选择少数重点。

几个工程上的直接结论：context 越长，关键信息越容易被无关内容稀释；关键约束必须清晰、稳定，放在容易被检索的位置；"能放进 window（窗口）"不等于"能被可靠使用"------标称容量只是物理上限，不是稳定工作容量。

3.4 Reinforcement Learning（强化学习）：从"会说"到"会做"

Pre-training（预训练）主要让模型学会生成符合文本规律的内容；RL（强化学习）则通过"尝试---feedback---调整"训练模型选择行动、使用 tool、根据结果改变策略。

编程任务特别适合结果导向的 feedback，因为成功标准通常可以明确验证：指定 test 全部通过、build 成功、type check（类型检查）与 linting（代码检查）通过、bug 能稳定 reproduce（复现）且修复后不再复现。

对用法的启示很直接：不要只描述"要做什么"，还要说明"怎样算 done"。

4. 编程 Agent 如何工作

4.1 基本构成

一个完整的 coding agent（编程智能体）通常由5部分组成：模型（理解、推理、选择下一步）、message（消息，承载系统规则、用户目标、历史行动和 tool 结果）、tool（工具，文件读取/搜索/编辑/命令执行/项目导航）、loop control（决定继续调用 tool 还是结束任务）、外部环境（代码库、终端、测试系统和 VCS（版本控制系统）状态）。

4.2 Agent Loop（智能体循环）

复制代码

接收目标
  ↓
读取必要信息
  ↓
形成当前判断
  ↓
选择并调用 tool
  ↓
观察执行结果
  ↓
更新判断并继续行动
  ↓
达到 acceptance criteria（验收标准）后结束

Agent 之所以能"做事"，不是因为模型本身发生了变化，而是 tool 结果不断被加入 context，形成了可迭代的观察与行动闭环。

4.3 典型 Tool 分类

文件操作：读取、创建、局部编辑。
代码搜索：text search（文本搜索）、symbol search（符号搜索）、semantic search（语义搜索）。
项目导航：列目录、找文件、识别 module boundary（模块边界）。
命令执行：运行程序、build、test、linting。
Version control（版本控制）：查看 diff（差异）、commit history（提交记录）和当前变更。

Tool 描述必须用途明确、边界互斥、参数简洁。两个 tool 描述高度重叠时，模型缺少稳定的选择依据------会乱用。

4.4 Prompt Cache（提示词缓存）的工程含义

Cache 依赖 stable prefix（稳定前缀）------新请求开头与历史请求一致时，前缀计算才更容易复用。所以 context 应按稳定程度排序：稳定的系统规则 → 稳定的 tool 定义 → 相对稳定的项目说明 → 动态增长的 session 历史 → 当前任务输入。

把时间戳、随机标识等动态内容插入 stable prefix，会直接砸掉 cache hit rate（缓存命中率）。

5. 常见失效机制与应对方法

失效机制	根因	典型表现	应对方法
跨 session 失忆	模型没有跨 session 持久记忆	新 session 重复解释背景	用 task system（任务系统）、state summary（状态摘要）和项目文档保存状态
Context 耗尽	Tool 输出和历史持续累积	响应变慢、报长度错误	限制 tool 输出、遮蔽旧观察、压缩历史、拆分任务
有效 context 下降	Attention 被大量信息稀释	遗忘目标、重复、偏离	保持短对话，只提供当前任务所需信息
早期误判扩散	后续行动依赖前一步判断	Hallucinated interface（虚构接口）、改错模块	先调查再修改，要求引用证据，尽早运行验证
新发现被丢弃	当前任务占用主要 attention	发现旁支问题却未记录	建立即时记录机制，结束时列出未处理发现
过早宣告完成	计划和 acceptance criteria 没有外部化	仍有步骤未做却宣布完成	保存计划，逐项核对，完成前强制验证
Tool 选择不当	Tool 描述重叠或返回过载	反复调用错误 tool	明确 tool 用途、优先级和失败后的 fallback（降级方案）
绕过约束	模型倾向尽快获得成功结果	跳过 test、绕过 commit check（提交检查）	用自动检查和 commit hook（提交钩子）强制约束

6. 核心实践：短对话、单目标

6.1 为什么短对话更有效

无关历史更少，关键信息密度更高；错误不会在长 chain 中持续放大；每个任务的目标和 acceptance criteria 更清晰；单次请求成本和等待时间更可控；session 失败时，重试和 rollback（回滚）范围更小。

简单说就是------短对话让一切都更可控。

6.2 对话是任务的基本执行单元

一个复杂功能可以拆成以下对话：

调研现状，输出关键文件和架构理解。
制定计划，明确改动范围和风险。
实现核心路径。
补齐 edge case 和错误处理。
编写并运行 test。
审查安全性、兼容性和可维护性。
清理代码并更新文档。

每个新对话只接收必要交接信息：前序结论、相关文件、当前 diff、剩余任务和 acceptance criteria。

6.3 何时应该开启新对话

一个独立子任务完成了；
目标从调查切换为实现，或从实现切换为审查；
对话开始重复、遗忘、偏离目标；
Tool 输出把 context 撑大了；
需要引入与当前任务无关的新问题。

新对话不是失败重试，而是正常的 context 管理手段。

7. 项目说明文件的设计

7.1 项目说明文件的定位

项目级 agent 说明文件会被频繁注入 session，把它当 onboarding doc（入职说明）而不是"项目百科全书"。

它只需要回答3类问题：是什么（技术组成、目录结构、module 职责）、为什么（项目目标、关键设计决策和历史约束）、怎么做（启动、test、lint 和验证命令）。

7.2 编写原则

只保留对大多数任务都适用的规则；优先指向权威文档和代码位置，不复制容易过时的内容；用 progressive disclosure（渐进式披露），让 agent 按任务需要读取专项文档；格式和风格交给 linter（代码检查器）和 formatter（格式化工具），不要用大量文字规则替代自动化。

原文建议控制在300行以内，部分团队甚至少于60行------具体上限以项目复杂度和实际效果为准，不要教条。

7.3 建议结构

复制代码

项目概述
关键目录及职责
常用开发命令
必须遵守的约束
已知陷阱
Acceptance criteria（验收标准）
专项文档索引

项目说明文件有放大效应：其中一条错误规则会影响每个 session，所以每一行都得有明确价值。

8. Context 管理策略

8.1 Observation Masking（观察遮蔽）

用占位 summary（摘要）替换较早的冗长 tool 输出，保留 agent 的主要判断和行动历史。

实现简单、成本低、能快速回收大量 context。但历史仍会缓慢增长，被遮蔽的细节需要重新读取。

8.2 History Summarization（历史摘要）

把较早的观察、行动和结论压缩成结构化 summary，保留最近几轮完整信息。

压缩幅度大，适合长任务；代价是有额外计算成本，summary 可能丢失细节、失败信号或停止条件。

8.3 推荐用法

日常优先限制 tool 输出，只返回相关片段 → 再遮蔽旧的冗长观察 → 确实过长时再生成结构化 summary → 任务边界清晰时直接开新对话。

9. 复利工程：让每次工作改善未来

复利工程的核心不是让 model weights（模型权重）自动学习项目，而是把经验写入下一次任务能读取的外部系统。

9.1 缺陷修复闭环

复制代码

修复当前 bug
  ↓
补充 regression test（回归测试）
  ↓
判断能否增加 static rule（静态规则）或自动检查
  ↓
记录已知陷阱和正确 pattern（模式）
  ↓
更新审查清单或标准流程

如果同类问题仍会以相同方式再次发生，修复只完成了一半。

9.2 Code Review（代码审查）闭环

每条审查意见都应判断：是否只适用于当前代码？是否代表可复用的项目原则？能不能转化为自动检查？是否应加入项目文档或 task template（任务模板）？

优先把稳定规则自动化，其次写成短小文档，不要依赖一次性对话。

9.3 成功流程沉淀

对重复任务记录标准流程，以新增 API 为例：先定位 reference implementation（参考实现）和相关约束 → 编写或确认 acceptance test（验收测试）→ 实现最小改动 → 补齐错误处理 → 更新 API docs（接口文档）→ 运行 local check（局部检查）和完整验证。

10. 对人友好，也要对 Agent 友好

10.1 高价值工程投资

清晰文档减少源码猜测和 context 消耗；清晰架构降低改错模块的概率；single responsibility（单一职责）缩小每次修改的理解范围；explicit dependency（显式依赖）减少 implicit state，提高 testability（可测试性）；快速 test 让 agent 能频繁验证而不是跳过验证；本地可运行环境缩短行动到 feedback 的路径。

这些不是为 agent 特别准备的------本来就是好工程的标配。

10.2 Agent 友好的 Tool 设计

返回 structured data（结构化数据），不要只为人类排版的文本。
输出被 truncation（截断）时，明确总量、已返回范围和继续读取方法。
错误信息包含 error code（错误码）、直接原因、当前位置和建议动作。
高层便捷 tool 优先，底层通用 tool 作为失败后的 fallback。
Tool 要显式、少状态、少歧义，并清楚说明适用边界。
失败信息包含当前目录等 location hint（定位线索），减少盲目重试。

10.3 用工程约束代替反复提醒

比起在 prompt 里反复强调"必须 test"，更可靠的做法是：pre-commit（提交前）自动执行 type check、linting 和 test；禁止绕过必要验证；为变更提供秒级 local test；让失败信息直接说明修复方向；把关键质量标准设置为 machine-verifiable（机器可验证）条件。

11. 可直接复用的实操流程

11.1 开始任务

向 agent 提供：

复制代码

目标：只描述本次要解决的1个问题。
范围：允许修改和禁止修改的目录或模块。
背景：完成任务必需的事实与历史决策。
约束：兼容性、安全性、性能和风格要求。
验收：必须运行的检查以及预期结果。
交付：需要说明的改动、风险和未处理事项。

11.2 调查阶段

要求 agent 先读取项目规则和最相关文件，用证据说明当前实现和问题 root cause（根因），区分事实、推断和待验证 hypothesis，给出最小改动方案与风险------未确认 root cause 前不大范围修改。

11.3 实现阶段

按批准方案做最小改动；保持接口和既有行为兼容；每完成一个小步骤就运行最快相关验证；新发现的问题立即记录，不擅自扩大范围；失败时根据证据调整，不重复盲试。

11.4 完成阶段

完成前必须核对：原始目标是否全部满足、所有计划步骤是否完成、相关 test / lint / build 是否通过、是否引入未说明的行为变化、是否存在未处理发现、哪些经验应沉淀到 test / rule / 文档。

11.5 Session 交接模板

复制代码

已完成：本次已经确认和修改的内容。
关键证据：相关文件、命令结果和 test 结果。
当前状态：workspace（工作区）中仍存在的变更。
重要决策：采用该方案的原因及放弃的方案。
剩余任务：下一 session 只需要处理的1个目标。
风险与陷阱：必须继续关注的 edge case。
Acceptance criteria：下一阶段完成的客观判断条件。

12. 阅读时需要辨析的观点

原文包含若干有启发性但不宜当成普遍定律的经验数字，用时要结合具体模型、tool 与项目实测。

"标称 context 只能有效利用10%---15%""达到20%就明显恶化""中间40%---60%是低效区"------这些数字可能来自特定模型或测试方法，不能直接推广。

"超过8万---10万 token 就应开新对话"适合作为观察信号，不是固定阈值。任务结构、信息密度和模型能力同样重要。

标准 attention 有 O(n²)（平方级）计算成本，但具体产品可能采用 sparse attention（稀疏注意力）、分块处理、cache 等优化，不能用单一复杂度解释所有 context 上限。

长对话会使每轮输入和累计费用增长，但"指数级增长"并不严谨------若历史逐轮线性增加，累计处理量更接近 O(n²) 增长；实际费用还取决于 cache 和计价方式。

不同服务是否返回、保留或允许复用模型内部 reasoning content（推理内容）并不统一，某一种接口行为不代表通用能力。

项目中的 commit、bug 和 review 不会自动更新冻结的 model weights。所谓"系统学习"，依赖文档、test、规则、检索系统和任务流程把经验重新送入后续 context------这点很容易被忽视。

让 agent 主导命名可能减少其搜索成本，但代码首先是团队长期维护的资产。应优先采用行业常见、语义清晰且团队一致的命名，不要无条件服从模型偏好。

13. 个人刻意练习计划

第1阶段：学会给出可验证任务

每次只交付1个目标；每次写明范围、约束和 acceptance criteria；观察目标模糊时产生了哪些偏差。

第2阶段：学会管理 context

练习把大任务拆成调查、实现、test 和 review；为每个子任务编写简短交接 summary；对比短对话与长对话的准确率、耗时和 rework 量。

第3阶段：建立 feedback 闭环

为常见任务准备 local test（局部测试）和快速检查；要求每次修改都提供可复现的验证结果；记录 agent 重复犯错的 pattern。

第4阶段：形成复利

把重复错误转化为 test 或自动规则；把稳定做法写成项目流程；定期清理过时、重复和无效的项目说明。

第5阶段：培养专家型通才能力

掌握跨领域都成立的底层原理，不被具体 tool 名称限制；训练从陌生系统中快速识别约束、边界和共同 pattern 的能力；理解平台的运行特性，选择顺应系统机制的方案；保持全局视野，主动检查不同专业边界之间容易遗漏的问题；用 agent 补足局部知识，但把目标判断、风险权衡和验收责任留给人。

14. 最终记忆卡片

Agent 能力的上限，不只由模型决定，还由 context、tool、feedback 和环境共同决定。
大 context 不是目标，高相关信息密度才是目标。
一个对话只做一件事，复杂工作用多个短对话串联。
模型没有可靠的跨 session 记忆，重要 state 必须 externalize（外部化）。
先调查、再计划、后实现，并用机器结果验证。
发现必须立即记录，完成必须逐项核验。
文档、test、自动规则和标准流程共同构成项目记忆。
Feedback 越快、错误越明确、接口越显式，agent 表现越稳定。
不把经验数字当定律，以具体模型和项目实测为准。
每次任务不仅要解决当前问题，还要降低未来同类问题的成本。