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