“AI 天然倾向于生成快速交差的缝合代码。但在复杂系统面前，急着堆功能只会带来系统死锁。”
记一次个人工作台 Portal 从单页缝合膨胀到白屏死锁的惨痛踩坑。反思为什么在系统变复杂时，绝不能急着让 AI 堆功能，而必须由人类工程师充当架构裁判，先把目录规划与底层布局彻底做扎实。
前些天，我经历了一次非常狼狈、但也极具启发性的技术重构。
事情的起因其实很朴素：我为自己搭建了一个托管在 Cloudflare 上的个人工作台（Portal），用来沉淀日常的技术复盘、工作手记以及读书思考。
最初它很干净，就是一个轻巧的单页应用（SPA）。但随着时间推移，我想给它不断叠加新特性：iPad 上的手写笔注支持、长文与双栏对照排版、本地持久化缓存、甚至复杂的访问权限分流。
每次我有新想法，都会直接让 AI 帮我写代码落地。AI 确实极其高效，几分钟就能给出一个能跑的方案。
然而就在前两天，这个看似功能丰富的系统彻底崩掉了：独立文章页点进去全是白屏，排版错乱；更要命的是，当让 AI 去排查修复时，它在几千行混杂的代码里陷入了疯狂的“工具调用死循环”——一遍又一遍地用关键词搜索旧代码、修补局部变量，不仅什么都没修好，甚至直接被系统的无进展检测判定为阻断。
看着终端里陷入停滞的光标，我突然意识到：问题根本不在于具体的某个语法 Bug，而是系统的底层架构从一开始就埋下了病根。
01 偷懒的代价：AI 喜欢“快速成型”，但代价是架构债
回溯整个系统的腐化过程，我发现了一个非常深刻的规律：
AI 有一个天然的本能倾向——追求局部最优与“快速交差”。
当你对它说“帮我加一个文章阅读页”时，它的第一反应绝不是帮你重新规划目录结构、拆分状态机、设计清晰的数据总线。最省力、最快让你看到效果的做法是什么？
是“缝合”：
- 它直接把主页大厅里的那套臃肿控制器（几千行的 DOM 操作、模态框逻辑、搜索索引）全盘拷贝一份，硬塞进新建的文章 HTML 里；
- 看到缺少某个变量，就在局部打个补丁；看到某个样式冲突，就加一个高权重的 inline style 强行覆盖。
在功能简单时，这种“快速方案”给人一种开发极快、生产力暴增的虚假繁荣。
但当系统逐渐膨胀，这种偷懒就变成了致命的毒药：独立阅读页在后台疯了一样寻找主页大厅才有的 DOM 节点，找不到就直接抛出未捕获异常中断执行，导致整页死锁白屏。
这时候你再让 AI 去“修 Bug”，它自己也彻底迷失了。因为代码库已经变成了一团毛线球，牵一发而动全身，局部无论怎么 patch，都只是在给坏死的组织打绷带。
02 深刻的教训：在堆功能之前，必须逼着 AI 先定架构
这次惨痛的踩坑，给我最大的认知升级是关于人机协作的分工边界：
最初的架构设计，权重远在具体的功能实现之上。
AI 有一个天然的生成倾向：优先给出一个比较简单的、快速见效的方案。在项目刚起步时，这种倾向极具诱惑力，几句话就能把原型跑起来。但问题恰恰出在这里：当一个系统开始变得复杂时，如果你不主动踩刹车，AI 就会顺着“简单快速”的惯性，把一个个新功能像打补丁一样硬塞进旧代码里。
这时候，最致命的做法就是“边走边看，直接让它接着加功能”。
正确的做法恰恰相反：在系统面临复杂化拐点时，先不要急着让 AI 去加具体的功能，而是一定要停下来，让 AI 先把整个底层架构做好、把整个系统目录和模块布局彻底做扎实。
必须由人类工程师充当架构裁判，明确要求并监督它梳理清楚：
- 哪些是核心索引，哪些是独立实体？
- 它们之间的物理文件怎么组织，目录层级如何划分？
- 统一的公共底座（Single Source of Truth）放在哪里？
- 各个页面与组件之间，绝不允许存在哪些隐式依赖？
只要底层框架与职责边界清晰，AI 随后写出的代码就是一块块规整的积木，拼装自如；如果架构本身是混沌的，任由 AI 用“简单快速”的短视逻辑堆砌功能，它输出的代码就只能是加速坍塌的危房。
03 动手手术：制造业“定置管理”在软件工程上的投射
想通了这一层，我果断叫停了 AI 无休止的局部修补，按下了重构的暂停键。
曾经在工厂做工程与制造管理时，有一条铁律叫“定置管理”：物料绝不能乱堆乱放，工器具必须各就其位，否则产线必然频繁堵塞。软件目录与系统架构，道理完全相通。
我和 AI 重新梳理并执行了一次彻底的物理切断手术：
1. 彻底切断耦合：大厅归大厅，内容归内容
- 主页大厅（index.html）坚决做减法：剥离所有几万字的正文内容，让它回归本质——只负责卡片索引、全局搜索与轻量分流；所有卡片改用标准的 HTML 物理超链接，右键可新开标签页，链接永不失效；
- 内容单页轻装上阵：彻底剔除所有残存的大厅冗余代码，体积从近 200KB 骤降为几十 KB，只保留纯粹的阅读与排版。
2. 沉淀唯一信任源（Single Source of Truth）
- 将原本散落在各个文件里的阅读器逻辑与样式，抽离为全站统一的公共底座：
- /assets/css/portal-reader.css：统一管理全站排版标准；
- /assets/js/portal-reader.js：提供轻量独立的阅读引擎；
- 这样一来，任何样式的迭代或功能的微调，全站所有页面立刻同步受益，彻底告别了“修了这篇、坏了那篇”的噩梦。
04 结语：朴素的力量
在工程机械行业经历智能化转型时，我见过太多“应采尽采”的教训——采集了海量没有统一标准的数据，看似高大上，最后全成了无法利用的数字垃圾。真正运转良好的，往往是那些朴素、边界清晰、克制的小系统。
这次重构也是一次当头棒喝。
我们很容易迷恋现代前端的各种复杂概念，以为把所有东西揉在一个单页里才叫“高级”，遇到问题就指望 AI 能变戏法一样帮我们抹平复杂度。
但计算机体系最伟大的发明之一，其实是超链接与物理文件系统。尊重物理分层、尊重最基础的工程规范，往往比任何精巧的内存模拟都要稳固得多。
让 AI 帮你干活前，请先把图纸画对。 认清架构的重量，守住边界的底线，这才是我们在这个代码生成门槛被抹平的时代，最不可替代的工程本分。