企业官网建设流程全解析

这段时间我把团队项目的AI辅助开发流程重新捋了一遍，起因是一次特别典型的“失忆”事故。上午我用AI助手分析认证模块，把调用链和数据模型都梳理清楚，下午换会话让它写重构方案，它完全忘了上午的上下文，重新问了一遍项目结构，还给出矛盾的答案。这个场景暴露了AI编程里一个核心矛盾：模型本身是无状态的，而真实项目偏偏是由大量隐含上下文组成的。要解决这问题，光靠单次对话的记忆是不够的，必须引入Memory工程和像AGENTS.md这样的声明式配置。

后来我沿着这个方向把AI编程的上下文管理彻底研究了一遍，最后落到一套可落地的组合方案：项目级的AGENTS.md声明式配置，配合分层检索式的Memory工程。这套组合帮我们解决了一直以来“AI永远记不住项目规矩”的痛点。这篇文章不打算写成正式文档，就把我从无状态模型一路走到声明式配置的真实过程、原理拆解和踩坑记录整理出来，给同样在做AI提效的朋友做个参考。

1. 无状态模型的“失忆症”：为什么AI编程绕不开上下文管理

1.1 无状态到底是什么意思：每次对话都像是第一次见面

AI大模型在处理请求时，模型本身不保存跨请求的内部状态。换句话说，每一次对你问题的回答，模型都只基于当前收到的文字序列，上一次会话里聊了什么，它没有记忆。我们在聊天界面里看到的“多轮对话”，其实不是模型记住了，而是应用层把前面的历史消息又拼在一起重新发了一遍。这个差异很多人第一次听到会觉得意外，但它恰好解释了AI编程里大量奇怪现象的根源。

可以把它类比成一个每天都是第一天上班的实习生：你说过的背景、你纠正过的错误、你强调过的偏好，只要不在眼前这份对话材料里，它一概不知道。而真实项目恰恰相反，代码库里到处是“几个月前约定的规矩”——某个模块为什么要这么划分、哪段代码为什么不能动、测试为什么要用这种写法。这些隐含上下文，恰恰是最难每次都用对话文字完整描述的东西。于是AI编程体验就变成了一个反复拉扯的过程：你拼命把背景塞进对话，它转头就忘。

1.2 在真实项目里，失忆是怎么吃掉开发效率的

我自己的实际感受是，无状态带来的效率损失分三个层面。

第一个层面是重复解释。一个稍微上规模的仓库，目录结构、技术栈、命名规范、常用命令，少说也要200字才能交代清楚。每次开新会话都要重新打一遍，一天开十个会话就是两千字的纯重复劳动。更烦的是，如果你忘了交代某一项，AI就会按它自以为是的方式去做，然后产生一个风格完全不一致的结果。

第二个层面是长任务断裂。改一个跨模块功能，经常要把十几个文件的内容带进上下文。当前主流的上下文窗口虽然已经很宽，但一旦任务链条过长，早期信息还是会被挤掉。模型只能“记得”最近的几轮内容，前面的分析结论、已经确认的约束条件，全被挤出了窗口。你往往会看到它后半段开始自相矛盾，或者把之前确定好的方案悄悄换掉了。

第三个层面是团队之间无法共享记忆。每个人都有自己开过的会话，AI在你这儿学过的东西，在别人那儿完全不生效。两个人问同一个AI助手为什么同一个模块会有两种不同的结论，不是AI双重人格，而是两边喂给它的背景材料不一样。这种记忆孤岛在团队协作里会放大很多倍。

1.3 为什么这个问题在AI编程里比在普通对话里更致命

如果只是闲聊，无状态顶多算个小毛病。但写代码是一种对“状态一致性”要求极高的工作。代码本质上是一个巨大的状态机，业务规则、架构约束、模块边界、历史包袱，全部隐藏在文件和目录的排列里。AI如果不知道这些约定，生成出来的代码在语法上可能是完美的，在架构上却可能是灾难级的——比如在路由层塞了一堆业务逻辑，把工具函数写成了一个类，或者给已经废弃的模块又加了个接口。

更隐性的问题是，无状态导致AI的判断没有“连续标准”。同样的一个代码问题，今天回答A方案，明天回答B方案，都说得通。但项目需要的是持续一致的演进方向，今天A明天B，最后项目会被改成四不像。这就是为什么要引入Memory工程：把一个项目的上下文、规则、历史决策，变成可以被AI读取和持久化使用的“记忆资产”，而不是每次从零开始解释。

2. Memory工程拆解：给AI Agent装上“能带走的记忆”

2.1 先分清两层记忆：工作记忆和长期记忆

要谈记忆，先把层次分清楚。工作记忆，对应的是当前上下文窗口里装着的内容：正在改的代码文件、刚才的对话、临时读进来的文档摘要。它相当于你手头铺开的那张草稿纸，随时能用，但有空间限制，翻页之后就会忘。

长期记忆，则是跨会话、跨任务保留的知识：项目规范、架构决策、个人代码偏好、过往踩坑经验。长期记忆是AI编程能不能从一个“聪明但没经验的临时工”转变成“熟悉项目的老员工”的关键。

真正落地的时候，长期记忆又分两层实现。一层放在模型外部，比如项目文件、文档、数据库里的向量索引；另一层是通过每次请求时把相关内容重新拉进来，转成工作记忆。所以长期记忆本质上是“存储在外，用的时候加载进来”。这个设计和人很像——长期记忆写在笔记本上，要用的时候翻到那一页。

2.2 长期记忆的三种落地方式：注入式、检索式、固化式

我研究了不少项目和团队的做法，发现长期记忆无外乎三种实现路径，而且通常是组合使用。

注入式最简单粗暴：把需要AI知道的背景信息，统一塞进系统提示词或每次请求的开头。优点是确定性强，AI一定会看到；缺点是token成本随着信息量直线上升，而且上下文窗口是有限的，注入太多会把“干活的空间”占掉。

检索式更聪明：先把知识库切块、建索引，收到任务后，根据任务内容实时检索出最相关的几段，然后只把这几段拼进上下文。优点是按需加载、成本可控；缺点是检索的质量决定了上限，索引建得不好，关键信息召不回来，AI照样瞎猜。

固化式是我认为最被低估的一种：把规则和决策写进项目自身的文件体系，比如AGENTS.md、设计文档、决策记录，让AI在每次会话开始时像读说明书一样自动加载。这种方式的妙处在于，它和代码一起版本管理、一起演进，天然和项目保持同步，而且人能参与review。

三种方式不是非此即彼。成熟的Memory工程一般是以“固化式”为骨架，把项目里最重要的规则沉淀成文档；以“注入式”为入口，每次会话自动读取骨架文件；以“检索式”为扩展，当任务涉及某个很深的领域时，再按需拉取更细的资料。

2.3 Memory工程的核心指标：成本、命中率、保鲜度

判断一套Memory工程做得好不好，我一般只看三个指标。

第一个是成本，具体是token成本。每次会话要带多少资料才能既提供足够上下文，又不把预算打爆。这需要根据项目体量反复调整。第二个是命中率，即“AI需要某项关键信息时，能不能恰好拿到”。命中率低，Memory工程形同虚设。第三个是保鲜度，文档和代码库是否同步。过期的规则比没有规则还危险，因为它会让AI非常自信地按错误方式办事。

这里要特别强调保鲜度。很多团队一开始兴致勃勃写了一大堆AGENTS.md，三个月后代码库大改，文档却没人更新，AI照着旧规则给建议，成员反而更烦。记忆工程不是一个“写一次一劳永逸”的东西，它需要被当作项目的一部分持续维护。

3. AGENTS.md声明式配置：把一个项目的“规矩”变成AI可读的文件

3.1 AGENTS.md的本质：给AI Agent做的入职培训手册

先说说AGENTS.md是什么。它本质上是一份放在项目根目录（或子目录）下的说明文档，文件名叫AGENTS.md。现在主流的一些AI编程工具，在打开项目或启动会话时，会自动扫描并读取这个文件，把里面的内容当作“关于这个项目的基础上下文”注入给模型。换句话说，它就是一份给AI Agent看的入职培训手册。

既然是“入职手册”，里面写什么就很有讲究。最基础的内容包括：项目是干什么的、技术栈是什么、怎么跑起来、项目结构如何组织、有哪些编码规范。高级一点的内容包括：关键的架构决策、历史坑位、禁止事项、常见任务的推荐做法。写得好不好，直接决定AI在这个项目里的表现，完全可以把它理解成一套“约束AI行为的项目级配置文件”。

有一点想特别说明：AGENTS.md不是给人看的替代品。README是给人看的，讲的是“这个项目是什么、怎么用”；AGENTS.md是给AI看的，讲的是“在这个项目里工作和思考时，要遵守什么、要知道什么”。两者可以互相引用，但定位不同。人不需要记住AI要遵守的每条规则，AI也不需要用README那套面向用户的语气来生成代码。不同工具对这个配置文件的命名可能略有差异，但本质上都是同一套思路——项目级AI上下文的声明文件，谁在项目文件夹里干活，谁就要先读这一份地图。

3.2 声明式配置为什么比“每次手动交代”靠谱

“声明式配置”这几个字，重点在“声明”。它不是写一段代码去“执行”，而是把事实和规则描述出来，让AI自己理解并遵守。这个设计哲学跟基础设施领域的声明式配置一脉相承：你声明“这个服务应该有三个实例”，系统自己负责收敛状态；同理，你声明“本项目禁止在路由层写业务逻辑”，AI自己负责在生成代码时遵守。

相比手动交代，声明式配置有几个实打实的好处。

第一，可版本控制。AGENTS.md跟着代码库一起放仓库里，每一次修改都有历史记录，可以diff、可以回滚、可以审查。谁改了什么规则，为什么改，全部可追溯。

第二，可审查。给AI定的规矩，不应该是一个人拍脑袋决定的，而应该让团队成员像review代码一样review规则。AI生成的代码如果不符合规范，责任在谁，也可以从规则这边找依据。

第三，可演进。项目不是静态的，规则自然也不是。借助版本控制，规则可以随技术栈、架构、团队偏好的变化平滑演进，而不需要靠某个人的大脑来记忆。

第四，减少重复。一条规则写一次，所有新会话自动生效。这不仅省token，更关键的是省掉了每个人重复交代的成本，让团队的上限从“谁会写更好的提示词”变成“谁能把项目规则定义得更好”。

3.3 一份高可用AGENTS.md的构成与示例

说了这么多，放一份我认为比较实用的示例。以一个内部运营后台为例（我们内部叫模拟项目X），它的AGENTS.md大体长这样：

# AGENTS.md — 模拟项目X ## 项目概述 内部运营后台，用于订单管理和用户画像分析。 技术栈：FastAPI + PostgreSQL + Redis，后台前端为 React + TypeScript。 ## 常用命令 - 安装依赖：`make install` - 启动后端：`make dev` - 运行测试：`make test` - 代码格式化：`make format` ## 项目结构 - server/api/ —— 路由层，只做参数校验和路由分发 - server/services/ —— 业务逻辑层，核心业务都放这里 - server/models/ —— 数据模型层，ORM映射 - web/src/ —— 前端React代码 - tests/ —— 后端测试，按模块命名 ## 编码规范 - 后端使用black格式化，行宽88，类型标注必须完整 - 禁止使用print调试，统一用logging模块 - 异常处理必须捕获具体异常类型，禁止裸except - 新增数据库字段必须同时提供Alembic迁移文件 - 前端组件使用函数式组件和hooks，禁止class组件 ## 关键架构决策 - 三层架构是硬约束：路由层禁止写业务逻辑，services之间允许互相调用 - 所有外部API调用必须经过统一的http_client服务封装 - 缓存key规范：{module}:{resource}:{id} - 用户敏感信息禁止出现在日志中

这份文件控制在20行左右，核心信息都在。我特意没把它写成“毕业论文”，因为AGENTS.md的价值在于精炼和可执行，而不是把所有细节都堆进去。像“为什么三层架构是硬约束”这种背景，可以放到docs/architecture.md里，由AGENTS.md一句话引用即可。

实际使用中，我还会根据目录做分层：根目录放全局规则，某个子目录如果规则特别不一样，就在子目录里放一个局部AGENTS.md，优先于全局规则。这个机制在monorepo里尤其好用。

4. 我在真实项目里的Memory工程落地过程与踩坑记录

4.1 落地路线图：从最小闭环到分层记忆体系

讲完了概念，说点实在的。我落地这套体系大概分了四步。

第一步，先跑通最小闭环。我没有急着把AGENTS.md写得全而全，而是先在里面放三样东西：项目概述、常用命令、目录结构。然后验证AI是否真的自动读取了它。验证方法很简单：在同一项目的两个新会话里，分别让AI回答“这个项目怎么跑测试”，如果两个会话给出的答案一致并且是基于AGENTS.md的内容，说明自动加载已经生效。

第二步，加入编码规范和禁止事项。这步会在最短时间内体现价值。因为大多数风格不一致的AI代码，都是因为没人告诉它项目里有哪些硬性约定。把“禁止print调试”“路由层禁止业务逻辑”这种规则写进去之后，AI生成的代码肉眼可见地“懂规矩”了。

第三步，加入架构决策和历史坑位。也就是把那些“为什么这么设计”“哪块代码不能乱动”的信息沉淀下来。这一层带来的收益最慢，但最持久。AI知道历史坑位之后，就不会反复提出已经被推翻的方案。

第四步，拆分到子目录做分层。项目大了以后，全局规则会变得臃肿。这时候把局部规则挪到对应子目录的AGENTS.md里，全局只保留公共约束。这个步骤是Memory工程的“容量管理”，能保证全局规则始终保持精简。

4.2 踩坑实录一：过度注入让token成本失控

第一个坑是过度注入。刚开始我觉得规则写得越详细越好，于是一口气写了900多行，涵盖各种边界情况、示例代码、背景说明。结果AI确实“记得”了，但每次请求都要把这900行带进去，token消耗直线上升，响应速度也肉眼可见地变慢，甚至有时候它会过度谨慎，因为信息太多，反而不知道该以哪条为准。

后来我的解决思路是“总纲+按需检索”：AGENTS.md只保留最高优先级的硬规则，每条尽量一句话说清楚；更细的背景说明放到单独文档里，AGENTS.md里用链接或者路径引用。当任务确实涉及某个方向时，再通过命令让AI去读对应文档，而不是默认全量注入。

这里面有个判断标准：如果一条规则90%的会话都用不上，那它多半不应该放在AGENTS.md里，而应该放到按需加载的二级文档里。

4.3 踩坑实录二：规则冲突与指令歧义

第二个坑来自规则内部的冲突。我一开始在全局AGENTS.md里写了“统一使用Markdown写文档”，结果某个子目录的AGENTS.md里又写了“本目录使用JSON格式记录数据”，AI在两个会话里给出了两种不同行为，我们被坑了好几次才看出端倪。现在的约定是：就近优先。子目录规则可以对全局规则做局部覆盖，但必须在子目录AGENTS.md里明确声明“本目录覆盖全局的xx规则”。这样AI在冲突时有明确的裁决依据，不会自己瞎猜。

另一个常见问题是规则写得太抽象。像“代码要整洁”“保持高质量”“遵循最佳实践”这种话，AI听了等于没听，因为它不知道怎么检查。正确的做法是把规则改成可检查的、可操作的描述：“所有公共函数必须有docstring，函数体不超过80行”“新增依赖必须使用Poetry而非pip install”。规则能被机器检查，AI才能真正遵守。

4.4 踩坑实录三：文档漂移让AI按过期规则办事

第三个坑最隐蔽，是文档漂移。项目进行到第三个月时，我们把技术栈里的ORM从A框架换成了B框架，但AGENTS.md里还留着“数据库操作统一使用A框架”的旧条目。结果那段时间AI生成的数据库代码几乎全是错的，团队成员一度以为模型变笨了。排查之后才发现，是AGENTS.md在指导AI使用已经废弃的框架。

从那次之后，我把AGENTS.md纳入了代码评审的必备环节：凡是涉及技术栈、目录结构、架构决策的变更，PR描述里必须同步更新相关AGENTS.md规则。宁可多花五分钟维护规则，也不让AI带着过期地图干活。系统改造时，第一件事往往就是先改AGENTS.md，让AI跟着地图走，然后再动代码。

4.5 优化后的前后对比

整理了我们的数据，放在表格里更直观（样本是模拟项目X里一个为期两周的迭代周期）：

当然，这些数字不可能非常精确，但趋势是明确的。最大收获不是省了多少时间，而是“AI的表现从一个随机变量，变得稳定可预期了”。这个稳定性，在工程上比单纯的速度更快更有价值。

5. 范式转换背后的工程流程变化与我的真实体会

5.1 代码评审、文档维护、新人上手：三个最直观的变化

Memory工程真正带来的是编程范式的转换——从“每次对话临时组织上下文”变成“先沉淀记忆，再藉此工作”。这个转换在实际项目里最直观体现在三件事上。

第一，代码评审的维度变了。以前review代码是看逻辑对不对、语法好不好；现在还要看“AI有没有遵守AGENTS.md里声明的规则”。甚至一些团队已经开始了“规则先评审、代码后生成”的流程：先稳定规则，再用规则约束生成。评审的对象，从一行行代码扩展到了项目自身的“规范性定义”。

第二，文档维护的定位变了。以前写文档，脑子里想的读者是“未来的人”；现在写文档，脑子里想的读者多了一个“未来的AI Agent”。AGENTS.md、架构决策记录这些文档，从可有可无的附属品，变成直接影响AI产出的基础设施。文档写得好不好，直接体现在AI生成的代码质量上。

第三，新人上手的方式变了。我以前带新人的时候，先让他读README，再跑通项目，再讲一堆业务背景。现在有了记忆资产之后，AI Agent本身就是一个“熟悉项目的老员工”，新人可以拿它当活字典，上午问项目结构，下午问历史决策，它都能答。有个很有意思的现象：我们组的新人上手周期，因为这套记忆体系明显缩短了。

5.2 什么时候不该用AGENTS.md：边界与取舍

并不是所有项目都适合一上来就搞AGENTS.md。我自己的判断标准很简单：看项目是不是长期维护、多人协作的“资产型”项目。

一次性脚本、临时demo、几天的探索性实验，确实没必要维护AGENTS.md。投入产出比不值得——你花时间写规则，项目生命周期还不够回本。这种项目直接靠对话式临时交代反而更快。

但反过来，凡是三个月以上、团队超过两个人、代码会持续演进的资产型项目，我建议从第一天就放一个最简版本的AGENTS.md，哪怕只有10行。后面补的成本永远是使用前写的十倍。这句话听着像老生常谈，但真踩过坑的都知道，等文档漂移已经发生了再回头补规则，AI已经被带着跑偏好几轮了，改错的成本早就超出了写规则的那点时间。

5.3 我的工作流重构：先定义“AI能理解的项目”，再谈AI提效

最后说一点更个人的体会。这一套折腾下来，我最大的转变是：我开始把“AI能不能理解我的项目”当作一个核心设计目标，而不只是把AI当作一个自动补全工具。

以前我对待AI编程的态度是“提问—拿结果—不行再修”，代码项目本身的定义方式是给人看的。现在我的工作流变成了：拿到一个任务，先检查项目记忆资产是否到位——AGENTS.md是否描述了最新技术栈和目录结构？架构决策记录是否更新？如果答案是否定的，我宁愿先花十分钟整理记忆，再让AI开工，也不想让它带着一个过期的地图去“猜”项目。

有一个很实用的小技巧，分享给看到这里的朋友：不一定要等到AGENTS.md完美了才开始用。你可以先放一个只有技术栈和常用命令的10行版本，然后用一个迭代周期去观察AI在哪些问题上反复踩坑，把踩坑点转成一条条规则，补进去。规则不是想出来的，是踩出来的。这套“AI踩坑—规则沉淀—再踩坑—再沉淀”的循环，其实就是把传统开发的总结复盘机制，迁移到了AI协作场景里。

我个人现在的习惯是：任何项目，无论大小，新建仓库的第一天就建AGENTS.md，哪怕只有三行。这个动作的成本几乎为零，但它会在未来省下无数轮“重新解释”的对话。真正的范式转换，从来不是某个工具带来的，而是这种一点点把“上下文”变成“基础设施”的日常习惯带来的。