企业官网建设流程全解析

6周，5.8万行代码，一个能跑通全流程的仿真任务管理平台。

第7周，客户提了个小需求：调度队列加一个超时重试。

改完当天，结构求解器连续三次把两个工况的任务串在了一起，现场评审会直接翻车。

更尴尬的是，没人说得清为什么。写代码的、审代码的、接手的，三个工程师面面相觑。

这不是段子。这是我们过去一年在多个研发类软件项目里反复看到的一幕。

01 你欠的不是技术债，是认知债

Vibe Coding这个词，Andrej Karpathy在2025年2月提出来的原话是：完全交给感觉，忘记代码的存在。

前半句是效率，后半句是陷阱。因为"忘记代码存在"的前提，是你这辈子不用再见它。而研发类软件的生命周期，通常是五到十年。

这里要分清两种债。

• 技术债：代码写得糙，将来要还，但你知道欠在哪、欠多少，账单是清楚的。

• 认知债：代码能跑，但你不知道它在干什么。连"还哪儿"都无从下手

Simon Willison把后者叫cognitive debt。我们自己的体感更直白：技术债是本金加利息，认知债是本金加利息，外加你连账单都看不懂。

五个信号，工程师可以对号入座。

第一，类型和错误处理形同虚设。any满天飞，裸except吞异常，日志里只有一行NoneType，现场排查全靠猜。

第二，God File。单个文件一两千行，AI只会往里追加，不会主动拆。

第三，复制式复用。四个几乎一样的后处理模块，改一处要改四处，漏一个就是bug。

第四，零测试或者假测试。测试跑通了，测的全是正常路径，边界一条没有。

第五，依赖成环。画出来是一碗意面，动了A必崩B。

中三条以上，恭喜，是屎山。

02 为什么研发类项目踩下去更

通用互联网团队踩的坑，在工业软件和研发系统里会被成倍放大，原因有五个。

第一，错一次的代价不是页面白屏，是算错的工况。仿真求解器里的单位量纲、边界条件、收敛判据，错一位小数点，下游结构设计跟着错一整轮。

第二，边界条件是主战场，不是边角料。AI的默认思维是"正常场景跑通"，而工程软件的输入永远是脏的：空值、超大网格、非收敛返回、中文路径、跨平台编码差异。

第三，交付周期长，人员流动大。一个平台交付后维护五年，写代码的人和接手的人往往不是同一个。认知债在没有交接的项目里是复利

第四，国产化适配叠加不确定性。从x86迁到国产CPU，从Windows 迁到麒麟、统信，AI生成代码里那些"看起来能跑"的动态库调用和硬编码路径，会在迁移时集中爆炸。

第五，合规与可追溯。B端客户要评审、要审计、要交付文档。一句"这是AI写的，我也不太清楚"，在评审会上没有说服力。

一句话总结：互联网产品可以先跑再补，工程软件必须算得对、说得清、改得动。

03 一个项目的三周复盘

项目概况：某装备制造企业的仿真数据管理与任务调度平台，5.8万行Python 加 TypeScript，前后端分离，对接两套商业求解器和一套自研求解器。团队4人，其中3人用AI编程工具辅助开发。6周完成主体功能，第7周进入不敢改的状态。

蜜月期，第一到第三周

一天推进三四个功能，任务提交、结果解析、参数面板、图表后处理，全部跑得通。commit记录漂亮，演示效果好，甲方满意。

失控期，第四到第七周

加一个超时重试，调度队列开始串工况，根因是任务上下文用了模块级全局变量，AI在三次不同的对话里各写了一份状态管理，彼此打架。结果解析在网格超过800万单元时静默失败，裸except吞掉了内存溢出，日志里只有一行"解析完成"。后处理绘图有四份几乎相同的实现，改一处颜色要改四处。单元测试覆盖率6%，且集中在工具函数，核心调度和解析路径一条没有。依赖扫描发现三处循环依赖、两处硬编码的许可证路径。

最要命的不是这些bug，是团队里没有一个人能完整讲清楚"一个任务从提交到返回结果"的数据流。这就是认知债的兑现时刻。

治理期，第八到第十周，三周救回来。

四步，顺序不能反

第一步，体检，不急着动刀

用静态扫描加安全扫描加覆盖率统计，输出一份分级报告：红色是循环依赖、未处理异常、硬编码凭据；黄色是God File、重复实现、any与裸 except；绿色是命名和注释。只修红黄，绿的先不动。原则是先有地图，再动手术。

第二步，补网，先测试后重构

不给全项目补测试，那是另一个月的活。只给接下来要动刀的模块补：调度器、求解器适配层、结果解析。每个函数至少一条正常路径加一条边界路径，边界包括空值、超大网格、非收敛返回、跨平台路径。测试先红后绿，重构才有安全网。

第三步，拆与收敛

按业务域拆God File，调度、求解器适配、结果解析、权限、日志各自独立。消灭any和裸except，用类型守卫加显式异常链替代。四份后处理收敛成一份，列定义改成配置化。

第四步，立规矩，把流程固定下来

仓库根目录写架构约定文件，写死模块边界、单文件行数上限、禁用模式清单，AI每次都能读到，就不会再把东西塞进一个文件。提PR必须能回答三个问题：这段逻辑我理解吗，为什么是这个方案，有没有更简单的做法，答不上就不合。commit message写"为什么"，不写"做了什么"。CI上四道门禁：静态检查、类型检查、单元与契约测试、覆盖率阈值，不绿不合并。每个迭代留百分之二十的工时还债，债务进backlog，不进心里

三周后的结果

核心路径测试覆盖率：6% → 62%

循环依赖：3处 → 0

最长单文件：2100行 → 380行

新增需求平均交付时长：5天 → 1.5天

更重要的是，团队终于能回答那个问题了：这个任务，是怎么跑完的。

04 三条硬纪律，比工具重要

第一，AI写代码，人来定架构。接口、模块边界、数据流是人决定的，AI只填实现。让AI设计系统，等于把最难的部分外包给一个不负责的同事。

第二，AI代码的审查强度要高于人工代码。人写的代码你能问作者，AI 写的代码没有作者。按"匿名外包且联系不上"的标准去审。

第三，认知速度必须跟上代码速度。每写完一个模块，用一句话说清数据流。说不清，就是债在积累。

工具不该背这个锅。AI是电锯，能砍十倍的树，也能锯到腿。