两轮项目结构整理的踩坑与反思

起因：当你发现自己在害怕打开某个文件夹

这轮整理的起点，其实不是某个技术决策，而是一种很具体的不适感：打开项目目录，不知道该看哪里。

这个项目已经"能跑"了。模型写好了，仿真跑得动，数据也能出图。但每次想改点什么，或者想回忆三周前某个参数到底放在哪里，都要花相当一段时间重新定位。目录结构是从最初"先写着试试"开始一路堆叠上来的，每个文件夹的存在都有合理的历史原因，但合在一起已经没有人能一口说清全貌了。

这不是"技术债"那种听起来很抽象的东西。这就是一种很日常的、每天打开项目都会多花十分钟的摩擦力。这轮整理，本质上就是在处理这股摩擦力。

第一步不是动手，是先弄清楚"这里面到底有几件事"

一开始的冲动是想赶紧动手：重命名文件夹、搬文件、删旧代码。但很快发现，如果不先搞清楚"这个工作区到底在做几件不同的事情"，搬了也白搬，过两周还是会乱。

于是先停下来，花了一整轮时间回答一个问题：这个目录里，到底混着几种不同性质的东西？

答案比想象的多。有主线实现代码，有实验性的另一套写法，有跑仿真用的参数数据，有建模推导留下来的说明文档，有跑出来的结果图，有测试脚本，有半成品的讨论稿，有已经过时但不敢删的旧模型。它们全都平铺在差不多的目录层级里，只靠文件名和记忆区分。

弄清楚这一点之后，才知道该怎么动手：不是按"新旧"分，而是按"性质"分。代码归代码，数据归数据，文档归文档，测试归测试，实验归实验。这听起来像废话，但在一个长期试验式推进的项目里，这些东西是天然混在一起的，因为它们确实是一起产生的。

"两套代码做着差不多的事"是最容易踩的坑

整理到中途，发现了一个比目录混乱更实质的问题：两条实现线里有好几块代码在做几乎一样的事。

这不是谁偷懒复制粘贴造成的。这是自然演化出来的。一开始只有一条主线，后来想试另一种写法，于是开了一条实验线。实验线需要用到一些基础功能——数值计算、数据解析、格式转换——主线已经写好了，但直接调用主线的代码会引入不想要的依赖，于是实验线自己也写了一份。

刚开始没什么问题，两份代码各走各的。但时间一长，主线那边改了一版，实验线这边没同步，两份代码就悄悄分叉了。更麻烦的是，哪份是"对的"已经说不清了。

这次整理的一个核心动作，就是把这些重复的功能找出来，抽到一个两边都能共用的地方。这件事听起来简单，做起来有一个很关键的前提：你必须先判断"这些重复的代码，本质上是不是真的在做同一件事"。有些看起来像，但仔细看其实在处理不同的情形；有些看起来不像，但底层逻辑完全一样。如果不做这一步判断就直接合并，反而会引入新的混乱。

最后抽出来的共享层不大，也就四个方向的基础能力。但这四个方向是两条线每次修改都会触碰的地方。把它们合到一处之后，"改了这边忘了那边"的问题至少在这个范围内消失了。

数据的归属感比代码更容易搞混

代码谁写的、归谁管，通常还比较明确。但数据往往不是。

项目里有一批数据，原来放在实验线的目录下面，看起来像是实验线的私有资产。但仔细一看，主线其实也需要这批数据，只是一直在用另一份格式不太一样的副本。

这种情况在研究型项目里特别常见：一份数据最初是为某个具体实验准备的，放在那个实验的目录里顺理成章。但后来这份数据变成了所有人都需要的公共输入，位置却没有跟着调整。结果就是要么到处复制，要么靠路径硬编码指向一个"不该属于你"的目录。

这次处理的方式是：把原始数据提到一个明确属于整个工作区的位置，然后写一个统一的前处理步骤把它转成标准格式，各自的实现线只使用自己目录下的标准化结果。这样，数据只有一份源头，但每条线都有自己干净的消费入口。

测试和算例的区别，比想象中重要

整理之前，"测试"和"算例"是混在一起的。有些脚本是自动化跑的、用来验证代码有没有改坏；有些脚本是手动跑的、用来看某个工况下的仿真结果。它们都放在叫"tests"的文件夹里。

这两件事的性质其实很不一样。自动化测试需要明确的输入、确定的预期输出、可重复运行。算例更像是一次实验，输入是研究者根据工况设定的，输出是拿来分析的，甚至每次跑的参数都可能不一样。

把它们混在一起的后果是：想跑自动化测试的时候，需要小心避开那些手动算例脚本；想加一个新算例的时候，又怕影响测试框架的收集规则。更深层的问题是，混放会让人搞不清"这个脚本的结果到底是已经验证过的基线，还是上次手动跑的一次性输出"。

分开之后，自动化测试有自己的目录和入口，算例有自己的目录和入口。测试可以放心地自动收集，算例可以自由地增减工况。各自做各自的事，不互相干扰。

文档的分层，解决的不是"写不写"的问题，而是"放哪里"的问题

这个项目不缺文档。理论推导写了，设计讨论写了，参数说明写了，实现笔记也写了。但这些文档全都放在同一个文件夹里。

问题不是内容不好，而是你在找一份东西的时候，不知道该在哪个文件里找。一篇偏理论总览的长文和一篇记录某次讨论结论的草案，性质完全不同，但它们并排放着，只靠文件名区分。

这次做的事情很简单：把文档按性质分成了几个子目录。理论说明放一处，讨论草案放一处，历史归档放一处。然后把那些跨项目的、更偏全局的文档上提到工作区根目录，不再挤在子项目的文档文件夹里。

这不是什么精巧的设计。但做完之后，"我要找那篇关于某某问题的讨论"这件事变得快了很多。

"先把问题定义清楚，实现留到以后"是一种有用的策略

整理过程中碰到了一些确实应该统一、但短期内没法一口气做完的问题。比如不同模型导出的中间数据格式不统一——都是矩阵，但字段名不一样、结构不一样、元信息不一样。

一开始想着要不趁这次整理一并处理掉。但仔细一想，这件事涉及到好几个模型的接口改动，而且需要先在实践中试验哪种格式更合理。强行在这一轮里做完，大概率做出来的方案也不对。

最后选择的做法是：写一份草案，把问题描述清楚，把当前状态记录下来，把后续需要做的事列出来，然后先不动代码。这样做的好处是：这个问题不会被忘掉，因为它已经被写成了正式文档并登记在待办里；但也不会因为急着收口而引入一个不成熟的方案。

这种"承认这件事当前做不完、但正式记录下来"的策略，在大规模整理中非常实用。否则要么什么都想一轮做完，结果哪个都做不好；要么做完之后忘了还有这个问题，几个月后又要重新发现一次。

删东西比加东西更难下决心

整理过程中最犹豫的环节，不是"把这个文件搬到哪里"，而是"这个旧目录还要不要留着"。

理性上知道，一个已经被完整迁移走的目录，留在原地只会误导后来者。但感性上总觉得删了就"回不去了"。尤其是那些旧模型、旧测试、旧的目录结构——删掉之前总想着"万一以后还要参考呢"。

最后的处理方式是：真正需要保留的旧实现，给它一个正式的"归档"身份，放在一个明确标注为归档的位置，附带足够的说明让它可以独立运行和理解。而那些只是"搬走之后剩下的空壳目录"，直接删掉，不留恋。

这个决策过程的启发是：保留旧东西的正确方式不是"原地不动让它慢慢腐烂"，而是"给它一个明确的安置方案"。要么正式归档，要么果断删除。卡在中间的状态最消耗心力。

每搬一个文件，就要更新一处说明

这是整理过程中最枯燥、也最容易遗漏的部分。每次移动一个目录、改变一条数据链路、调整一个入口脚本，都需要同步更新相关的说明文档和指引。

忽略这一步的后果很明确：代码和文档立刻脱节。一个新加入项目的人——或者三周后的自己——按照文档找路径，发现路径已经不存在了。这种脱节如果不在改动发生的当下就修复，之后再补的成本会成倍增长，因为你已经忘了当初为什么搬、搬到了哪里。

这次整理坚持了一个原则：每完成一次结构调整，立刻更新所有受影响的说明文件。不攒着，不拖到最后一起改。这个过程确实很慢，大量时间花在更新那些看起来不起眼的说明文档上。但回头看，这些即时更新的文档，才是整理成果能"活下来"的保证。

回过头看：整理不是一次性的事

做完这两轮之后，最强烈的感受不是"终于搞好了"，而是"原来这个过程必须是渐进的"。

第一轮把工作区从一个混合仓拆成了几个独立项目，理清了大的边界。但做完之后发现，其中一个子项目内部的问题暴露得更明显了——原来被整体的混乱掩盖着的内部结构问题，在外围清晰之后反而更扎眼了。于是有了第二轮，专门针对这个子项目内部进行重新梳理。

这不是第一轮做得不好。这就是整理工作的本质：你不可能一步到位看清所有层级的问题。每一轮整理都是在当前能看到的层级上做力所能及的收口，做完之后视野更清楚了，然后才能看到下一层该做什么。

接受这一点之后，心态会轻松很多。不用追求"一次做到完美"，只需要保证"这一轮确实比上一轮更清楚"，就够了。

最后

如果要用一句话总结这两轮整理的核心经验，大概是这样：

一个项目最容易腐烂的部分，不是代码逻辑，而是目录结构和文档。因为代码不对会报错，但结构不对只会让你每天多花十分钟。这十分钟不致命，但会慢慢磨掉你继续推进的意愿。

定期花时间把结构理一理、把边界画清楚、把过时的东西归档或删掉、把当前的状态写下来——这些事不紧急，但它们决定了一个项目到底是"能跑一阵子"，还是"能一直跑下去"。