做AI编码代理调优这一年多我踩过最大的坑不是它写错代码而是它干到一半突然失忆。上下文窗口看着有20万token听着大可真跑起来完全不够看——几十轮对话、几百次工具调用、一堆文件扫描结果很快就顶到天花板。一旦触发上下文压缩代理就像被拉去做了一场“脑叶切除术”它还认得最近几轮对话但你是谁、项目是什么架构、刚才改到第几行、你反复强调过哪些约束全被切得干干净净什么都不剩。为了从这种“术后失忆”里活下来我把两套老古董哲学请了出来一套是Unix init.d的启动顺序机制一套是电影《记忆碎片》里的外部化记忆思路。组合打完我的AI编码代理现在对上下文压缩基本免疫压缩之后还能无缝续上进度。这套方案不挑代理、不挑项目纯靠文件组织和一套启动习惯。这篇就把完整思路和实战配置拆开给你看。1. 先搞清楚AI编码代理是怎么“失忆”的1.1 上下文窗口的物理极限想解决失忆得先明白大模型的工作方式。一个编码代理本质上是个拿着工具箱的对话机器人它一边跟你聊一边调工具去读文件、搜代码、跑命令每做一步都会把新的内容追加进自己的上下文窗口。而大模型的“工作记忆”只有这个窗口——超出窗口范围的内容不参与注意力计算模型根本看不见。20万token听起来很大我们来算一笔账。一个普通代码文件一次性读进来少则两三千token多则上万一个目录扫描结果试试看轻轻松松上千token一次测试执行的输出更恐怖经常直接把几万token烧掉。我实际用下来代理干活干得稍微深入一点一次会话烧掉10万token是家常便饭跑到15万以上也很常见。也就是说上下文不是慢慢用光的是“几下就烧光”的。这不是夸张是数着token算出来的结果。更麻烦的是token消耗往往集中在你最需要它记住的时刻。你花大代价喂给它一堆代码和日志换来的理解、判断和决策恰恰是在上下文接近满溢、即将被压缩的时候才刚形成。这就像一台机器刚学会操作手册下一秒电源就被拔了。1.2 “脑叶切除术”到底切掉了什么窗口满了各家处理方式大同小异要么静默丢弃最早的内容要么把历史对话自动折叠成一段摘要。听起来很合理但真正丢掉的往往是最不该丢的东西。我自己复盘过几次典型的失忆现场总结了四个“高危丢点”。第一是核心目标。代理只记得自己“在改代码”却忘了这次大目标是“给支付模块增加幂等处理”。第二是硬性约束。用户明明白白交代过“不要动数据库层的表结构”压缩之后代理又开始顺手调整数据库你需要花好多轮才能把它拉回正轨。第三是当前进度。改到文件A第120行下一步正要给服务B补测试压缩后代理从头扫描项目重新猜了一遍当前在做什么。第四是历史决策。为什么选方案A不选方案B当时讨论半天才定下来压缩后它又绕回方案B重新分析白白烧掉大量token。“脑叶切除术”这个比喻一点都不夸张。压缩切掉的不是零散细节而是方向感、约束和进度——这三样恰恰是长时间编码任务里最不能缺的东西。方向丢了代理就乱逛约束丢了代理乱改进度丢了代理永远在原地打转。1.3 压缩免疫的核心命题既然压缩不可避免问题就不是“怎么不让它压缩”而是“压缩之后怎么让它快速恢复”。我在设计方案之前先把自己的目标拆成了三条硬标准。第一条关键信息必须外部化。所有需要跨会话记住的东西都要写进项目文件里而不是只存在对话里。对话里的内容压缩了就没了文件里的内容还在硬盘上谁也删不掉。第二条恢复路径必须自动化。代理开新会话之后要能自己找到并加载这些外部信息不能靠用户手把手喂。第三条信息之间必须可自洽。记忆文件可以有多份但它们的优先级、时序、范围要明确不能互相打架。这三条标准其实是逼着你想清楚“记忆存在哪、怎么找、怎么用”。想明白了下面的方案就是水到渠成的事。2. 两种记忆哲学的启发init.d 与《记忆碎片》2.1 为什么偏偏是Unix init.d用过Linux的人应该都记得低版本的SysV init在系统启动时会遍历 /etc/init.d 目录按文件名顺序依次执行里面的脚本01开头的先跑99开头的后跑。这套机制最精彩的地方在于它的哲学不管上一次关机时系统处于什么乱七八糟的状态每次开机所有脚本都从第一行重新执行一遍按确定的顺序把系统拉回一个确定的状态。这套“每次开机都重跑一遍”的逻辑和AI编码代理简直是绝配。代理每开一个新会话本质上就是一次“系统启动”——窗口里空空如也之前所有状态全没了。如果我能给每个项目准备一个类似init.d的启动目录让代理在会话一开始就按顺序把角色、项目背景、约定、当前任务全部加载进来那它就等于每次都从“开机脚本”走到正常状态不管上一次对话的结局多破碎。关键细节是文件命名要带数字前缀比如00、10、20。这不止是为了排序好看更重要的是给代理一个明确的执行顺序先读基础设定再读项目信息再读工作进度最后读禁区。顺序本身就是信息它让代理知道哪些内容是地基、哪些是当前焦点。2.2 《记忆碎片》教会我的外部化记忆电影《记忆碎片》讲的是一个失去长期记忆能力的人如何破案。因为记不住事他把所有关键线索写在纸条上、照片背面甚至把最重要的信息纹在身上。别人靠脑子记他靠外部载体记。每一次醒来脑子都是空的但只要顺着纸条和照片他就能重新接上因果链条继续追查真相。这给我的启发非常直接AI代理的上下文窗口就是“短期记忆”每次压缩就像一次短期记忆清空。我们没法阻止清空但可以学主角的做法——把所有关键状态写在“外部纸条”上。代理不需要在脑子里记住自己做过什么它只需要知道“该去哪里找到自己做过什么的记录”。具体落地就是一组记忆文件包括进度账本、决策日志、状态快照。代理每次开工前先翻这些文件就像主角醒来先翻口袋。上下文里只留一句轻量提示项目记忆放在.agent-memory/下面开工前必须全部过一遍。这比把几万字背景全塞进提示词要省token得多也更可靠。外部纸条不会因为对话折叠而消失。2.3 核心设计原则把init.d和《记忆碎片》合起来我总结出四条设计原则。这四条原则是后面所有实现的地基也是我调了好几月才稳定下来的条条框框。幂等启动。每次新会话代理都执行同一个启动流程不管上次对话结束在哪个奇怪的时间点不依赖任何记忆残留。这一步想明白了压缩就不可怕了因为启动流程会把代理重新带到轨道上。外部优先。凡是需要跨会话记住的信息一律落盘。对话里聊得再透彻只要没写进文件就当它不存在。顺序加载。记忆按编号优先级加载防止代理只读最新进度漏了基础规则和禁区。基础规则漏了代理就容易跑偏禁区漏了极可能就是灾难。可审计状态。状态文件要能让代理核对自己现在进行到哪一步、下一步动作是什么而不是靠它自己从头分析。可审计意味着代理能回答“我现在在哪”而不是“我觉得我在哪”。这四条原则说起来简单落地时我踩了不少坑。下面直接上一套完整目录结构和启动配置。3. 落地搭建一套“压缩免疫”的记忆骨架3.1 项目文件清单与目录规划我用的目录结构长这样project_root/ ├── .agent-memory/ │ ├── boot/ │ │ ├── 00-role.md │ │ ├── 10-project.md │ │ ├── 20-conventions.md │ │ ├── 30-current-task.md │ │ ├── 40-progress.md │ │ └── 90-freeze.md │ ├── state/ │ │ ├── ledger.json │ │ ├── decisions.log │ │ └── checkpoints/ │ └── RULES.md └── (项目正常代码目录)每个文件的用途我拆开解释一下。boot/ 是启动目录相当于代理世界的init.d里面每个文件都是一个“启动项”。RULES.md 是整个系统的中央规则文件只有一页写最不可违背的约定适合代理高频翻阅。state/ 存放动态记忆对应《记忆碎片》里的纸条和照片内容会随任务进展频繁更新。checkpoints/ 是每个阶段完工时的手动快照专门用来兜底。这套结构里最关键的纪律是boot/ 是只读的“宪法”目录原则上代理不得修改真正天天变的是 state/ 下的动态文件。静态规则和动态状态必须分开存放。如果不分开规则文件很快就会被代理改得面目全非等于宪法被天天修订一旦改错方向整个恢复体系就崩溃了。3.2 编写每次会话都会执行的启动脚本启动脚本不需要写成真正的bash代码AI代理直接读Markdown就够。关键在于内容要写成指令式的、命令式的而不是背景介绍式的。我来展示几个实际能用的模板。00-role.md 最简单通常一两段话你是本项目的编码代理。你的角色是资深工程师负责在本项目内完成用户下达的编码任务。 无论你上一段对话经历了什么现在你回到项目现场。开工前必须依次读取 boot/ 目录下所有文件再读取 state/ 目录下的动态记忆文件。 你不允许跳过上述流程否则视为违规。为什么用“必须”“不允许”这种强字眼因为我实测对比过LLM对祈使句的遵循率远高于陈述句。很多人写“你可以参考一下项目背景”代理读完就当参考压缩一出全忘换成“必须依次读取”代理执行的概率大幅提升。指令式的语气不只是风格问题它是启动流程能被真正执行的前提。10-project.md 记录项目静态背景。比如项目用什么语言、核心模块有哪些、目录怎么组织、构建和测试命令是什么。20-conventions.md 记录代码约定包括命名风格、错误处理习惯、测试要求、数据库限制等等。30-current-task.md 是最重要的文件它就是当前任务的“唯一真相”。里面明确写当前在推进什么目标、已完成到哪一步、下一步动作是什么。这个文件每次任务有进展都要更新是记忆碎片系统的主干。40-progress.md 是里程碑列表记录哪些子任务已关闭、哪些还开着。即使30丢了代理也能从40恢复大方向。90-freeze.md 是“禁区清单”放最后意思是让代理在决定行动前最后扫一眼。我通常列用户反复强调不能动的部分比如“不要改数据库迁移脚本”“不要动导入路径”“重构期间不允许改测试用例”。它排在末尾优先级最高一旦发现冲突以这里的约束为准。写这些文件时记住一个原则每个文件控制在几十到一两百行以内核心信息用列表不写长篇大论。文件越短代理越愿意完整读文件越长越容易读了一半就“视觉疲劳”漏掉底部关键约束。我看过有人把项目背景写了一千行代理光是读一个文件就烧掉两万token后面根本没法干活。3.3 设计状态文件与决策日志状态文件是动态记忆的落点。我用的 ledger.json 长这样{ project: order-service, updated_at: 2026-07-12T10:30:0008:00, current_task: 为支付模块增加幂等键检查, status: in_progress, last_file: src/payment/service.py, last_line: 120, next_action: 在 src/payment/test_service.py 中补充幂等场景测试, open_issues: [并发下重复请求的边界情况, 补偿事务的回滚日志], closed_issues: [幂等键生成规则], constraints_applied: [不要改数据库表结构, 不要动迁移脚本] }注意几个关键设计。时间戳字段不是摆设代理看到 updated_at 才知道这份状态是不是最新不会拿三天前的进度当现状。next_action 是核心道具压缩后代理不需要重新分析项目照着下一动继续干就行。open_issues 和 closed_issues 用来区分进展和未竟事项避免代理把已经完成的问题当成新问题再处理一遍。decisions.log 是面向文本的滚动记录每条都带时间戳和一句原因我习惯写成这样2026-07-11 14:02 - 选择方案A(内部重试)而非方案B(外部消息队列)原因团队暂未引入消息中间件重试成本更低。 2026-07-12 09:40 - 支付回调状态机从两态改为三态原因需要区分“接收”与“成功”。决策日志的价值在于压缩后代理如果重新冒出方案B日志会提醒它“这个问题已经讨论过了结论是A”。减少重复决策就是在省token、省时间、省用户的耐心。3.4 在代理工作流中接入恢复机制文件全摆好后最后一步是让代理真的去用。这一步被很多人忽略建了一堆记忆文件代理根本不读因为代理的默认指令里压根没有“读记忆文件”这个动作。文件写得再好不加载等于零。我强烈建议把启动流程写进代理工具的自定义指令入口让它在每次会话一开始自动执行。你可以把下面这段固定指令放到代理配置里在你开始任何工作之前先读取 project_root/.agent-memory/RULES.md然后按序号读取 boot/ 目录下所有文件再读取 state/ledger.json 和 state/decisions.log。 读取后先用一段话向我说明当前任务是什么、进行到哪一步、下一步是什么。如果发现文件内容缺失或冲突先向我确认不得自行假设。注意我加了一句“先用一段话向我说明”这个小动作很关键。它逼着代理真的去读文件因为要就输出内容代理人得真看读完以后你也能快速发现它有没有理解错。另一个必写项是“冲突先确认”记忆文件一旦冲突代理自行发挥反而更糟。接入之后还有一条日常纪律每完成一个重要动作就更新 ledger.json 和 decisions.log。建议在正常对话里明确告诉代理每完成一个文件修改、一个测试通过、一个方案敲定如果导致状态变化就同步更新状态文件。一开始代理会忘多提醒几次就变成习惯了。等它形成惯性你会发现项目里多了一位“自动写日志”的好队友整个记忆体系自己就能转起来。4. 实战演示一次完整的“术后苏醒”过程4.1 模拟场景设定空谈理论没用我拿一个虚构但很典型的小项目走一遍全流程。项目叫 order-service一个下单服务。用户让代理做一次中型改动给支付模块增加幂等处理包括新增幂等键、改造支付回调状态机、补测试。任务拆成三个子任务预计要跨两个会话完成。会话一里代理干活很顺利。它先按启动流程读了 boot 和 state确认了当前任务是“给支付模块增加幂等键”也记得约束是“不要改数据库表结构”。它花了大概6万token完成了第一部分改好了幂等键生成逻辑更新了 ledger记录了决策“选择内部重试方案团队还没引入消息中间件”。到这个时候上下文已经烧掉大约16万token离20万窗口上限很近了。4.2 会话一走到一半压缩来了就在代理准备开始第二部分、改造支付回调状态机的时候上下文触发了压缩。系统把早前的大量对话折叠成了一份几百字的摘要。代理的即时感受是它还隐约记得“最近几条工具结果”但项目整体目标、用户身份、根本约束都快在折叠摘要里变得模糊了。如果你没有记忆系统接下来大概率会发生这样的事代理重新读一遍整个项目目录重新猜测用户要什么它靠“支付模块”“幂等处理”这些关键词开始从头设计方案。更要命的是它可能自作主张去改数据库表结构——因为“不要改表结构”这条约束已经被折叠摘要挤到了记忆边缘。用户辛苦叮嘱的禁区就这么被“脑叶切除术”切掉了。但这个项目里代理醒来后的第一步是执行启动流程。它先读 RULES.md然后按序号读 boot 下五个文件。00-role 告诉它“你是本项目编码代理”10-project 告诉它项目结构和模块关系20-conventions 告诉它代码风格和测试要求30-current-task 直接指出“当前任务为支付模块增加幂等键检查状态 in_progress”40-progress 列出已关闭子任务“幂等键生成规则”和未关闭子任务“并发下重复请求的边界情况”。最后 90-freeze 再次提醒不要改数据库表结构不要动迁移脚本。4.3 压扁之后代理如何无缝续上再配合 state/ledger.json代理得到了完整坐标上次改到了 src/payment/service.py 第120行下一动是去 test_service.py 补幂等场景测试。它不需要重新分析直接打开测试文件照着 ledger 写的方向干活。这就像电影主角醒来后翻到一张纸条上面写着“下午三点去码头找那个人”他不需要记得为什么直接执行就行。decisions.log 也在这个阶段派上了用场。如果代理写测试时突然想“也许应该换成外部消息队列方案”它翻开日志就能看到 7月11日 已经决定用内部重试原因写得很清楚。于是它不会推翻旧决策继续保持方向一致不会在同一个坑里反复横跳。整个“苏醒”过程大约只花了一两分钟和几千token。如果没做记忆系统重新分析加上重新决策可能要烧掉几万token还得用户一遍遍地纠正。这才是“幸存”的真正含义不是项目不塌而是塌完之后恢复成本足够低低到你可以当压缩没发生过。5. 常见问题与排查技巧实录5.1 记忆文件互相矛盾怎么办这套方案跑久了最常见的坑就是文件内容打架。典型场景30-current-task 说“正在改B模块”但 ledger.json 的 next_action 还指向A模块的老任务90-freeze 说“不要动A文件”20-conventions 却又写着“所有公共接口都可以改”。代理遇到这种冲突要么随机挑一个执行要么停下来反复问用户直接把工作流卡死。我的解决办法很直接在 RULES.md 里写死一条冲突处理规则——按 boot 目录序号从大到小为准序号越大的文件优先级越高。我把 90-freeze 放最后就是因为它优先于一切。动态记忆里ledger 的新条目优先于 decisions.log 里的旧条目。有了这条规则代理遇到冲突不再纠结按优先级处理最多在 decisions.log 里留一句“检测到冲突已按优先级选择XX”。这一条规则救了我不下十次。5.2 代理不爱读记忆文件怎么办“代理就是不读记忆文件”这是新手最容易吐槽的问题。有些代理工具对自定义指令的遵循度确实不高写了“必须读boot目录”它读了个开头就跑去扫描代码了。我的排查流程分几步走。第一步确认指令放对了地方。很多工具支持项目级指令文件但有些只认固定文件名你改个名字它根本不加载。第二步把启动指令从“建议”改成“强制动作”。“建议阅读”改成“必须依次读取”并且加一句“读取后向我输出摘要”这招非常有效因为代理为了输出摘要必须真的读过才有内容可写。第三步加惩罚性描述“如果未读取记忆文件就修改代码视为违规。”LLM对高代价描述更敏感这句话能显著提高遵循率。最后个别顽固的代理我会把启动流程封装成一个 shell 脚本比如 .agent-memory/boot.sh让它先跑脚本拿输出再汇总结果。脚本输出比纯文本指令更“硬”。5.3 记忆膨胀与token浪费随着项目越滚越大ledger.json 和 decisions.log 会长得飞快。decisions.log 尤其容易变成几千行的大文档每轮启动都要全部读一遍token开销蹭蹭涨这就违背了“低成本恢复”的初衷——记忆系统自己变成新的上下文炸弹。我给了两个实操办法。第一定期封存归档。把旧决策按月份移到 state/archive/ledger 只保留最近30天或最近20条活跃决策。第二给 ledger 做瘦身每条记录压到一行以内只留结论和一句原因不写分析过程。checkpoints 也一样旧快照只留最近两三个就可以其余删掉。我大概每两周手动做一次记忆GC一次只要十分钟省下的token远超成本。5.4 实用避坑清单最后整理一个速查清单全部来自我实操里反复踩过的坑。boot 目录文件不要超过7个。超过之后代理的读取顺序容易被截断反而漏读关键文件。文件命名不要用中文和空格。部分工具对路径解析有坑统一用数字前缀加英文最稳。状态文件更新必须带时间戳否则多会话协作时代理无法判断新旧。记忆文件里只写确定性结论不写大段分析过程。分析是对话里的临时内容结论才是要持久化的。更新记忆的时机是“完成一个可验证动作之后”而不是“对话开始前”。只读不写记忆就会腐烂。一旦发现代理输出开始偏离约束优先检查 90-freeze 是不是被改动了。被改了就直接恢复原样。6. 进阶让记忆系统自我维护6.1 给记忆加版本控制记忆文件既然是项目的“宪法”和“纸条”就该有版本痕迹。我建议直接把 .agent-memory/ 放进项目仓库统一管理每次修改都会留到git记录里。想更细一点还可以设置每天自动提交一次记忆文件提交信息里写“记忆文件同步”。版本控制的价值在出事的时候特别明显。某天代理把记忆改坏了或者某份状态文件被写成了半截内容一个 git diff 就能看到到底改了什么快速回滚到前几天可用版本。查问题的时候还可以顺着记忆文件的演变历史还原当时的决策上下文排查效率高很多。没有版本控制的记忆系统是裸奔。6.2 自动检查点与滚动摘要还有一个更进阶的做法我强烈推荐让代理在完成一个阶段目标后自动生成一个检查点快照。快照内容包括当前任务完整描述、已完成事项、未完成事项、关键代码文件路径、下一步计划。把快照放到 state/checkpoints/checkpoint-20260712.md 这种带日期的文件里。这样就算整个 ledger.json 因为误操作丢了你还有其他快照可以重建方向。再配合滚动摘要每隔一段时间把 decisions.log 里过期的内容压缩成一份月度摘要把旧条目归档。两个机制配合起来记忆系统就能自动维持在一个健康体积既不膨胀到烧token也不丢关键上下文。6.3 从编码代理推广到其他长对话场景说实话这套方案不止适用于编码代理。我用同样的思路处理过文档写作、数据分析、教学问答等一切需要长对话的任务。核心思想永远一样关键状态不断落盘让每个新上下文都从外部记忆重新引导。只要记住“init.d每次开机重跑一遍、记忆碎片主角靠纸条续命”这两句话你就掌握了一种通用于任何大模型应用的状态恢复模式。我个人实践下来最深的一条体会是别指望厂商把上下文压缩做到完美也别指望代理永不出错真正可靠的办法是把项目的记忆从易失的对话里搬出来放到代理可以反复触碰的外部世界里。这个思路最大的门槛不是技术而是你能不能坚持“每完成一步就写一笔状态”这个笨功夫。笨功夫做到位了再猛的“脑叶切除术”也只是帮你清一清缓存而不是真的要你的命。