认知重建之后，步入Agentic Engineering的工程革命

认知重建之后，步入Agentic Engineering的工程革命

公众号: 腾讯技术工程

发布时间: 1970-01-01 08:33:46

原文链接: https://mp.weixin.qq.com/s?__biz=MjM5ODYwMjI2MA==&mid=2649801026&idx=1&sn=3e12f0888b3c232ed7218caf90df5f0a&chksm=bf4c0f3ab8ef6ca21c04e80f8bfce44dae41e5b6e72e1f523bbcf88da8f6d03e4f1056efb689&mpshare=1&scene=1&srcid=0331LA6BLBJmhKZPFBdhCoO4&sharer_shareinfo=91bd93888a0e7958e77c5a12d0cbd198&sharer_shareinfo_first=91bd93888a0e7958e77c5a12d0cbd198

作者：rickyshou

从 speckit 踩坑到认知重建，从推翻精密架构到一个 AGENTS.md 文件重新出发。这篇讲的是"我做了什么，以及它为什么有效"。一个 AGENTS.md 文件，两个月后长成了拥有 22 个 Agent、27 个 Skill、28 个命令的工程体系。它不是设计出来的，而是被真实需求一步步逼出来的——中间经历了场景路由的建设与推翻、方法论的沉淀、多 Agent 协同代码审查的实战、运营活动配置的端到端落地，以及从一个人用到一个团队用的完整过程。如果你正在思考"AI 辅助开发到底能走多远"，这篇文章给出的不是理论答案，而是一份带着所有弯路和修正的实践记录。

一、从 Vibe Coding 到 Agentic Engineering：一个概念的诞生

1.1 Karpathy 的一条推文

2025 年 2 月，Andrej Karpathy 随手发了一条推文，发明了一个词：Vibe Coding（氛围编程）。

"我发明了一种新的编程方式，我称之为'氛围编程'。你完全沉浸在氛围之中，拥抱指数级增长，甚至忘记代码的存在……我总是'全部接受'，不再看差异对比。遇到错误信息时，我直接复制粘贴进去，不加任何注释，通常这样就能解决问题。"

这条推文火了。不是因为它严谨，恰恰因为它说出了很多人心里的真实状态——AI 写代码已经"够用"了，你只需要看看、说说、跑跑、粘贴粘贴，大部分时候它就是能工作。

一年后，2026 年 2 月，Karpathy 回顾这条推文时，说了一段更值得注意的话：

"如今，通过 LLM 智能体进行编程正日益成为专业人士的默认工作流程，只不过监管和审查更加严格。其目标是在不牺牲软件质量的前提下，充分利用智能体的优势。许多人试图为这种方法想出一个更好的名称，以区别于 Vibe Coding，我个人目前最喜欢的是 Agentic Engineering。"

他给出了两个理由：

• Agentic——因为 99% 的时间你不再直接写代码，而是协调智能体并进行监督

• Engineering——因为这是一门有深度的学科，有其自身的艺术、科学和专业知识，可以学习和精进

看到这条推文的时候，我并不觉得这是一个新概念。

因为在 Karpathy 发这条推文的一个月前——2026 年 1 月 2 日凌晨——我已经提交了 AgenticMetaEngineering 项目的第一个 commit：feat: 初始化 AgenticMetaEngineering 项目结构和上下文管理规范。

名字里就有 Agentic Engineering。不同的是，我多加了一个 Meta。

为什么是 Meta？因为那时候我已经想清楚了一件事：Agentic Engineering 本身也需要被工程化。 让 AI Agent 真正进入业务研发，不是给它一个提示词就行的，有很多工程基础设施需要提前准备——这些基础设施的设计、构建和迭代，就是"元工程"（Meta Engineering）：

• 长时间跨会话执行任务——Agent 做到一半会话断了怎么办？状态怎么恢复？

• 工具调用能力的评估体系——Agent 调用工具的准确率、可靠性如何量化？

• 上下文的系统化管理——Agent 在正确的时刻能拿到正确的信息吗？

• 知识的持续沉淀机制——Agent 这次踩的坑，下次能自动避开吗？

这些不是"用 AI 写代码"的问题，而是"让 AI 可靠地写代码"之前必须解决的工程问题。

Karpathy 的推文真正的价值，不在于发明这个概念，而在于让它被广泛认识。当一个被大众熟知的人说出这个词，它就从少数实践者的内部术语变成了行业共识。这对所有在做同样事情的人来说是好事——你不再需要花 10 分钟解释"你到底在做什么"。

1.2 什么是"Agentic"？一个光谱而非二元定义

Karpathy 给了这个词一个名字，但"Agentic"到底意味什么？LangChain 创始人 Harrison Chase 在 _What is an AI Agent?_ 一文中给出了一个更具技术洞察力的视角。

他引用 Andrew Ng 的观点：与其争论哪些系统算"真正的 AI Agent"，不如承认系统的"Agentic 程度"是一个光谱。 就像自动驾驶有 L1 到 L5 的分级，AI 系统的自主程度也有不同层级：

Agentic 光谱（由低到高）：Router           → LLM 决定输入走哪条路径                    （少量自主性）State Machine    → 多步路由 + 循环决策，直到任务完成                    （中等自主性）Autonomous Agent → 自主构建工具、记忆经验、持续进化                    （高度自主性）

Chase 的核心观点是：一个系统越"Agentic"，就越需要新的工具和基础设施来支撑它——包括编排框架、持久化执行、运行时观测、评估体系，以及全新的监控方式。

这和我的实践体验完全吻合：当你从"一个 AGENTS.md 文件"演进到"22 个 Agent 协同工作"时，真正的挑战从"怎么写提示词"变成了怎么让这些 Agent 可靠地运行、有效地协作、持续地进化。

1.3 我的理解：Agentic Engineering 是什么

在构建工程体系的实践过程中，我自己也独立推演出了类似的认知。

2026 年 1 月初，我写了一篇内部文档 《Agentic 工程演进：从对话到自主》，从第一性原理出发，梳理了 AI 辅助编程从"简单对话"到"Agentic 工程"的五个阶段演进。核心框架是两个相互推动的维度：

• 横轴（工具能力）：LLM API → 聊天页面 → 简单 Agent → 编码 Agent → 团队定制化 Agent

• 纵轴（任务复杂度）：简单对话 → 代码补全 → Vibe Coding → SDD 脚手架 → Agentic 工程

两个维度的交汇构成了一张完整的演进地图：

每一层解决的是上一层的核心痛点：AGENTS.md 解决重复解释问题，但它会膨胀；context/ 分层解决膨胀问题，但跨会话会失忆；结构化记忆解决失忆问题，但知识不复利；复合工程让知识复利，最终形成完整的 Agentic 工程体系。工具能力的提升使更复杂的任务成为可能，而任务复杂度的增加又倒逼工具能力的进化——这两个维度相互推动，最终指向一个完整的工程体系。

这不是看了谁的文章之后的"学习笔记"，而是在实际构建过程中被一个个具体问题逼出来的认知：上下文膨胀了怎么办？跨会话丢失状态怎么办？同样的坑反复踩怎么办？每个问题的解法叠加起来，自然指向了一个工程化的方向。Chase 早在 2024 年 6 月就提出了"agentic"这个光谱概念，Karpathy 在 2026 年 2 月给了它一个更广为人知的名字——概念和命名各有先后，但对于实践者来说，这条路是被真实问题推着走出来的。

基于这些实践，我对 Agentic Engineering 的理解是：

Agentic Engineering 是一种工程范式：人从"代码编写者"转变为"Agent 协调者"，通过系统化的上下文管理、知识沉淀和流程设计，让 AI Agent 具备自主性、记忆力和成长性，在不牺牲质量的前提下实现工程效率的复利增长。

它不是 Vibe Coding 的对立面，而是 Vibe Coding 的工程化演进——保留"让 AI 做事"的杠杆效应，补上"质量保障"和"知识复利"两块拼图。

这篇文章要记录的，就是这个演进过程是如何在一个真实团队中，围绕活动业务的工程化改造一步步发生的。

1.4 同路人的印证：everything-claude-code 的十个月实践

在讲我自己的故事之前，先介绍一个外部案例——它说明 Agentic Engineering 不是某个人的发明，而是一种正在独立涌现的工程范式。

体系基本成型后，我在 2 月关注到了 @affaanmustafa（cogsec）的 everything-claude-code 仓库和他的长文分享。这个仓库来头不小——作者是 Anthropic 黑客马拉松的获胜者，从 2025 年 2 月 Claude Code 实验性发布起就开始深度使用，经过 10 个多月的密集日常使用，演化出了一套包含 13 个 Agent、43 个 Skill、31 个命令的生产级配置集合。

看到他们的实践时，我的第一反应不是"学到了新东西"，而是"原来有人在同一条路上走了十个月，而且到了类似的地方"。他们的体系覆盖了几个关键维度，和我独立演化出的方向高度吻合：

他们的原话精准地描述了共同的痛点：\*"你的皮质醇飙升，愤怒地对 Claude 大喊不要做某件事——而你已经在上一个会话中告诉过它了。"\* 这正是我在体系中用规范文档和经验沉淀机制要终结的循环——而他们用会话结束时的自动经验提取来解决同样的问题，路径不同，目标相同。

真正让我有共鸣的是他们对复利效应的理解：\*"Early on, I spent time building reusable workflows/patterns. Tedious to build, but this had a wild compounding effect as models and agent harnesses improved."\*（早期花时间构建可复用的工作流和模式，建设过程很枯燥，但随着模型和智能体框架的进步，这产生了疯狂的复利效应。）在第一篇文章中我详细介绍过，复利工程（Compounding Engineering）这个理念源自 Claude Code 团队与 Every 团队的实践交流，并在 Every 团队开源的 Compound Engineering Plugin 中得到了系统化实现——如今在一个完全独立的体系中看到同样的复利逻辑，进一步印证了这条路的可行性。今天投入的每一个 Skill、每一条规则、每一份经验文档，都在为明天的效率买单。

1.5 不是银弹：独立演化的必要性

但我想强调一点：everything-claude-code 不是我的体系的蓝图，我也没有参考他们的具体设计。AgenticMetaEngineering 的 22 个 Agent、27 个 Skill 是在解决活动业务问题的过程中独立"长"出来的，不是照着别人的配置搭建的。

他们自己在 README 的最后也明确说了：\*"These configs work for my workflow. You should start with what resonates, modify for your stack, remove what you don't use, add your own patterns."\*

这段话印证了第二篇文章的核心观点——没有一个"最佳配置"适合所有人。 AgenticMetaEngineering 中默认启用了 TAPD 的 MCP（对接内部项目管理）、企微的消息推送（Agent 完成任务后自动通知到个人）、内部的 QTA 单元测试插件——这些都是我们团队工作流中不可或缺的基础设施，但在 everything-claude-code 里你找不到任何一个，因为它们是企业内部工具，只有在你的真实业务场景中才有意义。反过来，他们体系中的一些配置（比如面向个人开发者的 GitHub MCP 替代方案），在我们的企业环境里也并不适用。工程体系必须从自己的土壤里长出来。

当然，独立演化不意味着闭门造车。他们体系中好的设计思路——比如 Hook 驱动的记忆持久化、会话结束时的自动经验提取——这些都值得后续融入进来，为 AgenticMetaEngineering 补充更多能力。

两个独立演化的体系在核心理念上高度趋同，这本身就说明了一件事：Agentic Engineering 不是某个人的发明，而是一种工程范式的自然涌现。 当你认真地让 AI Agent 进入真实的工程实践，你最终会被同样的问题逼到同样的方向上——记忆、学习、验证、复利。（第三章 3.6 节会结合 OpenAI Codex 团队等更多独立实践展开论证。）

接下来的章节，记录的就是我在自己项目中独立走出这条路的过程。

二、回顾：从认知到行动的断层

2.1 前两篇建立的认知基础

在第一篇文章里，我记录了从 speckit 踩坑到认知重建的过程，建立了三个核心认知：

• 上下文工程：AI 的能力上限取决于你给它的信息——完整性和信噪比决定一切

• 复利工程：让每次实践产生复利，边际成本递减，而非每次从零开始

• 极简主义：先跑起来，让具体问题驱动演进，而非预先设计完美架构

在第二篇文章里，我们推翻了精密架构，从一个 AGENTS.md 文件重新出发。那篇文章的结尾，我们有了一个能跑起来的最小工程——一个文件，几条规则，一个方向。

这三个认知是正确的。但正确的认知不等于可执行的方案。

2.2 第一个坑：用传统软件设计思维来设计 Agent 体系

第一篇文章发出时，我手里已经有了第一版 demo——基于第一篇的认知搭建的初始工程。接下来的迭代过程中，我本能地用了最熟悉的设计方法：领域驱动设计（DDD）。 第二篇文章正是在这段迭代中写的——它记录了我们如何从三层架构、九步工作流、多 Agent 编排的"精密设计"中清醒过来，受 NotebookLM 和 Claude Code 的极简理念启发，推翻全部架构，回归到"一个 AGENTS.md + 结构化知识"的起点。

这个思路很自然——DDD 是应对复杂业务系统的成熟方法论：划分限界上下文、定义聚合根、设计领域事件、通过接口契约解耦模块。既然 Agentic Engineering 也是一个复杂系统，为什么不能用 DDD 来设计它？

从 v0.1 到 v0.7，我反复尝试用 DDD 的方式划分 Agent 的职责边界、定义 Skill 之间的调用契约、设计知识的分层架构。每一版都比上一版"更完整"，但每一版在实际使用中都不对劲——Agent 不按你设计的边界行动。

最终才意识到根本性差异：传统代码写了就确定性运行，Agent 的行为取决于上下文。

用 DDD 设计微服务时，你可以精确定义一个接口：输入什么类型、输出什么类型、异常怎么处理。写完代码，部署上去，它就按你定义的方式运行。但 Agent 不是这样——同一个 Skill，给它完整的项目知识，它能一次做对；给它空的 context/，它就开始幻觉。同一个 Agent 定义，上下文窗口里塞了太多规则，它反而"走神"；精简到关键信息，它又表现正常。Agent 的"接口"不是函数签名，而是上下文窗口里的信息组合。这个"接口"是动态的、概率性的，没法用 DDD 的确定性边界去约束。

v0.7 之后我放弃了 DDD 路径，推翻之前的设计，建了当前这个全新的仓库。这个认知直接影响了后续所有的设计决策：不追求精确的模块划分和接口定义，而是围绕上下文的组织、流转和质量来构建体系——这就是第三章开始的故事。

这个认知断层还延伸出两个工程化问题，最终都指向了同一个答案。

问题一：体系怎么升级？

传统工具的升级路径是"发布新版本→用户更新插件"。但 Agentic Engineering 的核心资产是什么？Skill 定义、Agent 配置、context/ 里的知识、门禁规则——全是文本文件。升级一个 Skill 的行为，本质上是修改一个 Markdown 文件；调整一条门禁规则，本质上是编辑一个 JSON。

这意味着 git 就是天然的升级机制。git pull 完成升级，git diff 看到每一行变化，git merge 处理冲突。不需要版本号、不需要发布流程、不需要兼容性矩阵。当体系的核心资产是文本而非编译后的二进制时，版本控制工具本身就是最好的分发和升级系统。

问题二：最佳实践怎么推广？

传统的推广靠文档、培训、分享会——信息从"知道的人"单向传递到"不知道的人"。但在单仓库模式下，团队内其他项目的做法就在仓库里：context/project/A/ 是 A 项目的知识积累，context/project/B/ 是 B 项目的知识积累，requirements/ 里是每个需求的完整产出物。

Agent 可以直接读取其他项目的实践——"B 项目在做接口对接时是怎么处理鉴权的？搜一下 context/project/B/"。不需要找人问、不需要等分享会、不需要翻文档。项目间的经验差距，被 Agent 的检索能力直接抹平了。 一个项目踩过的坑沉淀到仓库里，其他项目的 Agent 下次就能直接引用。

两个问题，同一个答案：单仓库 + git + Agent 的检索能力，天然解决了升级和推广这两个传统工程化难题。 这不是刻意设计的——是当你把体系的核心资产从"代码"变成"知识文本"之后，自然获得的工程化优势。

2.3 "知道"之后的真实困境

从一个 AGENTS.md 开始，我手里有了方向。但认知和行动之间的鸿沟真实存在。

困境一：什么时候该加东西？

从一个 AGENTS.md 起步，"然后呢"是一个完全开放的问题。AI 第一天就开始犯错——没有记忆、没有经验、每个会话从零开始。你知道应该"让具体问题驱动演进"，但面前有十个方向可以走，每个方向都有合理的理由。

一个真实的例子：我让 Agent 用 Playwright 做页面验证，每次它都老老实实地打开浏览器、登录、操作、关闭浏览器。下一个任务又打开浏览器——又要重新登录。内部平台的登录流程涉及多步鉴权，每次重新走一遍既慢又脆弱。解法其实很简单：告诉 Agent "不要关闭浏览器，用新增 Tab 来切换任务"。但这条规则该写在哪里？写进 AGENTS.md？单独建一个 Playwright 使用规范？还是先忍着每次手动提醒？全都做是过度设计，只做一个可能选错。"极简主义"告诉你不要过度设计，但没告诉你最小可行的下一步是什么。

困境二：第一个复利的种子是什么？

复利工程的前提是"有东西可以复利"。但第一个需求做完，我手里的产出物不少——需求文档、概要设计、详细设计、笔记、进度日志、评审报告——问题是，这些都是为当前需求服务的。真正能跨需求复用的经验性知识，被锁在了这些一次性文档的字里行间。哪些该提取出来？提取到哪里？用什么粒度？

做完运营活动配置的第一个需求后，我列了一下过程中反复出现的信息：雅典娜平台的商品创建流程、Apollo 配置的 When-Then 规则格式、奖品库存锁定的先后顺序、活动模板和玩法模板的对应关系。这些信息虽然都在会话中出现过，但经过多次上下文压缩后早已丢失。

你知道应该沉淀，但立刻面对一个粒度选择：拿 Apollo 配置来说，是记一句"Apollo 有特殊的 When-Then 格式"？太粗了，下次 Agent 还是写错。还是把完整的语法规则、字段枚举、常见错误全部写下来？太细了，下次需求可能根本不涉及 When-Then。四类信息，每类都有这个粒度困境，而你没有任何经验判断"下次会用到哪些"。你知道"应该积累"，但不知道"积累什么、怎么积累、积累到什么粒度"。

困境三：一个人的效率提升不等于团队的效率提升。

自己用得顺手了，下一步是什么？让同事也来用？但团队里的人处在不同的起点上。

已经有过 Vibe Coding 经验的同事，上手后反馈不错——他们知道怎么和 AI 对话，缺的只是体系化的规范和工具，这套框架正好补上了。但对于连 Vibe Coding 都还没怎么接触的同事来说，问题根本不在"体系怎么用"，而在提示词不知道怎么写。你给他一个 /requirement:new 命令，Agent 问他"请描述你的需求"，他对着输入框发愣——不是不知道需求是什么，是不知道用什么粒度、什么结构、什么语气去"说"给 AI 听。这时候你才发现，你的体系预设了"用户至少会和 AI 对话"这个前提，而这个前提在团队里并不普遍成立。 从"我在用"到"我们在用"之间，隔的不只是工具使用的知识传递，还有一层更基础的——和 AI 协作的基本能力。

这三个困境不是理论问题，而是我在建设过程中真实面对的处境。它们也不是孤立的——困境一不解决，困境二就没有方向；困境二不解决，困境三就没有内容可传递。它们构成了一个环环相扣的链条：

困境一（何时加）→ 困境二（加什么）→ 困境三（怎么让别人也能用）       ↑                                    |       └────── 别人用不了，反馈你才知道该加什么 ──┘

于是我选了最可控的路径：自己边用、边体验、边优化——先把自己当作第一个用户，在迭代工程体系的过程中反复碰壁、反复修正。

接下来的章节，记录的就是我从 1 月到 2 月，把 AgenticMetaEngineering 从一个 AGENTS.md 文件"长"成一个拥有 22 个 Agent、27 个 Skill、28 个命令的工程体系的过程——每一步都是在回答上面的困境。

三、在我的项目中如何落地：一个体系的自然生长

好的工程体系不是设计出来的，是"长"出来的。每一个 Agent、每一个 Skill 都是在解决业务问题的过程中被逼出来的。

在讲演进故事之前，先说一个前提认知。

CodeBuddy、Claude Code 这类工具，本质上是擅长使用计算机的通用智能体。它们能读写文件、执行命令、调用 API、搜索代码——这些是"会用电脑"的能力。但"会用电脑"和"会做研发"是两件事。

一个新入职的工程师，即使电脑操作再熟练，也需要了解团队的分支策略、代码规范、评审流程、需求管理方式，才能真正融入协作。AI Agent 也一样。它缺的不是操作能力，而是研发团队约定俗成的规范和流程——代码怎么组织、需求怎么流转、方案怎么评审、质量怎么把控。

所以，从通用智能体到能真正承担研发工作的 Agentic Engineering，中间要补的就是这层团队研发知识。下面的演进过程，本质上就是我一步步把这些隐性的研发规范显性化、结构化，最终让 AI 能像一个"了解团队规矩的同事"一样工作的过程。

3.1 阶段一：一个文件的起步（1月初）

2026 年 1 月 2 日凌晨，第一个 commit 落地：feat: 初始化 AgenticMetaEngineering 项目结构和上下文管理规范。

那时候整个体系就是一个 AGENTS.md 文件——定义了 Agent 的角色、几条基本规则、目录约定。仅此而已。然后用它来做第一个自建需求：插件市场的开发。

从第一篇文章的认知出发，我知道上下文工程、记忆持久化、经验沉淀这些事迟早要做。但从第二篇文章的教训出发，我刻意控制了自己"一步到位"的冲动——不是不知道要做，而是不确定现在做是不是过度设计。 所以策略很明确：先让 AI 按照最简单的规则跑起来，等到真正"不得不做"的时候再做。

预期中的问题很快就出现了：

• AI 每次做需求都要从头问一遍业务背景——它没有记忆

• 上次踩的坑这次又踩了——经验没有沉淀

• 做到一半会话断了，恢复时完全不知道做到哪了——没有状态持久化

这些问题不意外，但它们在同一天之内集中爆发，明确了一件事：现在就是"不得不做"的时候了。 一个文件起步是对的，但一个文件不够用——不是设计失败，而是演化的信号到了。

3.2 阶段二：目录结构的自然涌现（1月上旬）

既然 AI 没有记忆，那就给它造一个。

第一个"涌现"的目录是 context/——最初就是一个放文档的地方。但很快它自然地分化出了两个层次：

• 团队级知识（context/team/）：所有项目通用的规范和流程——需求怎么写、方案怎么做、代码怎么审

• 项目级知识（context/project/）：特定项目的架构设计、业务知识、技术选型依据

这个分化不是我画了架构图然后实现的，是因为我发现有些规范每个项目都在重复写，有些则只对特定项目有意义。把它们放在不同的位置，AI 就能根据当前项目按需加载。

第二个"涌现"的目录是 requirements/。最初只是为了保存需求文档，但做了几个需求后发现它自然演化出了固定结构：

requirements/{id}/├── meta.yaml      ← 元信息：需求在哪个阶段、关联什么服务├── plan.md        ← 计划：这个需求要做什么、分几步├── process.txt    ← 进度：做到哪了、遇到了什么阻塞└── notes.md       ← 笔记：过程中发现的经验、待沉淀的知识

每个文件的出现都有对应的痛点：process.txt 是因为跨会话恢复时 AI 不知道之前做到哪了；notes.md 是因为过程中发现的好经验没地方记，等回头想整理时已经忘了。

这个阶段最重要的认知是"位置即语义"——不需要复杂的元数据系统，文件放在哪个目录，AI 就知道它是什么。这比任何数据库或索引机制都简单、都可靠。

3.3 文档即记忆：一个有意的设计选择

当 context/ 和 requirements/ 的结构逐渐稳定下来后，我发现它们已经构成了一个完整的记忆系统——这不是"无意中长出来的"，而是从一开始就有意参考了 Anthropic 在上下文工程中提出的 Agentic Search 思路。

Agentic Search 的核心理念是：维护轻量级的索引和标识符，让 Agent 在运行时根据当前任务动态检索，而不是把所有知识预加载到上下文里。 就像一个资深工程师不需要背手册，只需要知道"要查什么"和"去哪查"。这个理念直接影响了整个目录结构的设计决策——context/ 的分层、requirements/ 的固定结构、INDEX.md 索引文件的引入，都是在为 Agent 构建一套"知道去哪找"的记忆检索体系。

具体来说，这套记忆系统分为三层：

长期记忆（容量无限，按需检索）├── context/     ← 知识库：团队规范、项目知识、经验文档├── skills/      ← 能力封装：可复用的专业技能└── requirements/ ← 历史资产：已完成需求的全部产出物溢出区（会话中断时的"存档/读档"）├── process.txt  ← 做到哪了、遇到了什么阻塞├── notes.md     ← 过程中发现的经验、待沉淀的知识└── plan.md      ← 当前计划和决策记录工作记忆（容量有限，需要精细管理）└── 运行时的对话上下文

长期记忆持久化在文件系统中，工作记忆是运行时对话上下文，中间的"溢出区"解决的是一个具体问题——会话中断时关键状态溢出到文件中，下次恢复时读回来。本质上就是游戏的"存档/读档"。

但真正让这个记忆系统区别于"又一个知识库方案"的，是一个更深层的选择：为什么是文档，而不是数据库或向量存储？

第二篇文章中我提出过一个原则："文档即记忆"——同一份文档，人类和 AI 都能读懂、都能用。这不只是工程上的简化，而是关于知识一致性的选择。当团队的知识存在两套体系——人读人的、AI 读 AI 的——就不可避免地出现版本漂移：人更新了规范但忘了同步到 AI 的知识库，AI 的向量索引里还是旧的理解。文档形态天然避免了这个问题，因为人和 AI 读的是同一份文件。

更重要的是，文档形态有一个独特的优势：高频使用对抗腐化。传统文档最大的问题是写了没人看、看了不更新，最终变成僵尸文档。但当文档同时作为 AI 的记忆时，它在每一次 Agent 执行任务时都被"读取"和"使用"。文档过时了，AI 行为就会出错，开发者立刻发现并修正——这形成了一个天然的反馈环。文档不再是被动的参考资料，而是每天都在被消费的"活的记忆"。

这套记忆系统还解决了团队协作中一个根本性的问题：知识对齐。当整个团队共享同一套 context/ 目录时，所有人的 AI 都基于相同的记忆工作。新人 clone 仓库那一刻，就获得了团队积累的全部知识资产。这比任何 Wiki 或 Confluence 都高效——因为它不只是"可以看"，而是"必须用"。

3.4 阶段三：场景驱动的规范体系（1月中旬）

随着规范越来越多，一个新问题浮出水面：Agent 同时面对太多约束，行为开始不稳定。

Anthropic 在 _Building Effective AI Agents_ 一文中给出了一个关键指导原则："finding the simplest solution possible, and only increasing complexity when needed"（找到最简单的可行方案，只在必要时增加复杂度）。其中介绍的 Routing 工作流——"classifies an input and directs it to a specialized followup task"——给了我直接的启发。

这个思路的核心是：如果用户面向的是 Agent，那么应该给 Agent 最小的约束。 规范越少，Agent 越不容易"走神"；约束越精确，行为越可预期。当时场景还不多，规范也在可控范围内，用路由模式返回最小约束集合是一个合理的选择。

于是我做了一个决策：引入场景驱动架构，用路由机制实现最小约束。

核心思路——按场景隔离规则，只返回当前场景需要的最小约束集：

用户意图 → 场景识别 → 加载该场景的最小规则集 → 执行任务

我设计了一套完整的场景体系：普通场景（代码探索、需求定义、方案设计等）、流程场景（需求开发、规范维护等编排多步骤的流程）、辅助场景（阶段检查点、进度日志等被动引用的支撑能力），再加上横切规则（跨场景通用的行为约束）。

关键组件是 engineering-spec-retriever 路由 Agent——一个专门负责"搜索当下 Agent 应该遵循哪些规范"的子代理。主 Agent 识别到用户意图后，调用这个路由 Agent 检索对应场景的规范，只返回一份精简的可执行清单。这样主 Agent 的上下文中只有当前场景所需的最小约束，不会被无关规范干扰。

这套架构完全遵循了 Anthropic 的指导——在每个时刻，Agent 只看到它需要看到的规则。我为它写了完整的设计文档，包括场景分类、路由机制、流转规则、扩展指南。在场景较少的早期阶段，它运行得很好。

3.5 阶段四：推翻场景路由，转向工具设计（1月下旬）

转折点发生在一个具体的下午。我让 Agent 做一个常规的需求定义任务，它先是调用路由 Agent 检索到"需求定义"场景的规范，然后开始工作。做到一半我说"顺便看看相关代码的现有实现"，Agent 又调了一次路由，拿回"代码探索"场景的规范。两份规范加上横切规则，上下文已经占了大半。当我接着说"根据代码现状修改方案"时，第三次路由把"方案设计"场景的规范也拉了进来——Agent 开始"走神"了：它跳过了需求定义阶段的必填项，把方案设计的格式套到了需求文档上。三个场景的规范互相干扰，Agent 的行为完全不可预期了。

这不是个例，而是系统性问题的集中爆发。

先澄清一点：三层架构——团队智能体层、平台能力层、基础设施层——从项目初期就是这个基础结构，场景驱动阶段也是在这个骨架上做的。真正出问题的不是三层架构本身，而是场景路由这个核心机制。

场景驱动架构在早期运行良好——场景少、规范少、路由准确。但随着场景和上下文的持续增长，一个根本性问题浮出了水面：上下文腐烂（Context Rot）。

场景越来越多，每个场景的规范也在膨胀。路由 Agent 检索回来的"最小约束集"已经不再"最小"了——场景分类本身需要描述信息，路由规则需要上下文，检索结果需要格式化返回，再加上场景间的横切规则……所有这些元数据本身就在侵蚀上下文空间。

即使使用 Opus 4.5 模型（当时 Anthropic 最新最强的模型），Agent 的行为也开始出现明显的"走神"——指令遗忘、规范误读、步骤跳过。这不是偶发现象，而是随着场景复杂度增长的系统性退化。

Anthropic 那套"最小约束"的指导原则本身没有错，错在我选择的实现路径：用一个动态路由系统来实现最小约束，路由系统本身就成了新的上下文负担。场景驱动架构的讽刺之处在于——它为了减少上下文噪音而引入的机制，最终成了最大的噪音源。

除了核心的上下文腐烂问题，还有两个次要但真实的痛点：

• 场景边界模糊：真实的用户意图往往横跨多个场景。"我在做需求，顺便看看代码实现，然后修改方案"——这到底是需求定义场景、代码探索场景还是方案设计场景？

• 维护成本递增：场景路由表、场景识别信号、场景规则……维护这套元数据本身就变成了一个负担。我在"让 AI 更高效"的路上，造了一个需要大量人工维护的系统。

这和第二篇文章里 speckit 的教训本质相同——过度抽象反而增加了复杂度。但这次我学到了更深一层的教训：在 LLM 系统中，

... (内容已截断，完整文章请查看原文链接)