一次失控项目的目录整理复盘

这次整理面对的是一个在长期探索式开发中逐步生长起来的工作区。年前赶进度的那段时间，所有精力都花在功能推进上，新的实验不断往里加，旧的尝试没空清理，文档、数据、中间产物随手放在离代码最近的地方——"先跑通再说"。当时这样做是合理的，毕竟时间紧迫，整理是可以推迟的事。

但过完年再打开这个项目时，情况就不一样了。一个月的间隔足以让人忘掉大部分上下文：哪些目录是正在用的，哪些是废弃的尝试？这个文件为什么放在这里？那个脚本到底是主线的一部分还是某次调试的临时产物？目录结构已经从"反映当前项目边界"退化为"记录历史开发过程"，打开项目看到的不是清晰的功能分区，而是一座小型屎山的横截面。面对这样的项目，心里甚至产生了一种畏惧感——不是因为技术难度，而是因为认知负担太重，不知道从哪里下铲子。

这正是启动整理的直接原因——不是为了追求完美的工程规范，而是因为现有结构已经开始拖慢实际工作，甚至阻碍了继续投入的意愿。

整理过程

第一步：识别边界，而非急于搬迁

整理的起点不是"把文件移到看起来更合理的地方"，而是先弄清楚当前工作区里到底有几类东西、它们之间是什么关系。

在动手之前，先对所有内容做了一轮语义分类：哪些是正在开发的主线，哪些是曾经的实验但已经停止推进，哪些是辅助工具、哪些是数据源、哪些是生成出来的中间产物。这一步花了不少时间，但它决定了后续所有搬迁操作的方向，避免了反复挪动。

第二步：把"混合总仓"拆成独立项目

原来所有内容共用一个 Git 仓库，什么都往里扔，日积月累就成了一锅乱炖。一个工具的提交记录和主线研究的提交记录混在一起，不仅看不清历史脉络，也给回溯带来障碍。

拆分的原则很简单：如果两个东西的生命周期不一样、维护频率不一样、关心它们的人不一样，它们就不应该共用一个仓库。拆分时，旧仓库的 .git 目录被重命名保留而非删除，确保历史可追溯。每个新项目各自初始化独立的 Git 仓库，拥有自己的版本历史和忽略规则，互不干扰。

第三步：在主项目内部建立层级

仅仅拆分项目还不够，主项目内部同样需要分层。主线实现、实验性实现、已经冻结的旧实现、原始数据、说明文档被分别放到不同的位置，并且为每一层制定了明确的定位。

其中最有价值的一个区分是对实验内容的三级划分：仍在推进的、需要兼容保留的、已经冻结归档的。这种分类让人一眼就能判断某个目录的状态，不需要打开文件去阅读才能知道"这东西还活着吗"。

第四步：分离"人维护的"和"机器生成的"

在整理之前，手工编写的数据、自动生成的中间产物、运行输出的结果文件混放在一起。这带来两个问题：一是很难判断哪些文件需要手动维护、哪些可以重新生成；二是 Git 的提交历史中充斥着大量无意义的变更记录，真正重要的改动反而被淹没。

解决方案是建立清晰的流向：人维护的原始数据放在固定的位置，通过明确的转换步骤生成运行所需的配置文件，而运行结果则通过 .gitignore 排除在版本控制之外。这样，仓库里保存的始终是"源"，而不是"果"。配合精心设计的忽略规则，少量需要长期保留的参考结果仍然可以被显式地纳入追踪，不会被一刀切地排除。

第五步：为归档内容设立标准

对于那些已经不再开发但仍有参考价值的旧实现，归档标准是明确的：归档内容必须能够独立运行，不依赖主线中随时可能变化的部分；必须有自己的入口说明和必要的参考结果。这样即使过了很长时间，想回头验证某个旧方案时也不需要考古式地拼凑运行环境。

收获的经验

目录结构应该反映当前的项目边界，而不是开发历史的时间线。 如果一个目录的存在需要口头解释才能被理解，说明它的命名或位置有问题。好的结构应该是自解释的。

先分类，再搬迁。 急于移动文件而没有想清楚分类标准，往往导致移了又移。花在前期辨析上的时间不是浪费，而是对后续工作的保护。

区分"源"与"果"是整理中最重要的原则之一。 需要人维护的输入数据、代码、文档是"源"，它们应该被 Git 追踪。构建产物、运行结果、缓存文件是"果"，它们可以从源重新生成，不应该污染提交历史。善用 .gitignore 把这条线画清楚，是保持仓库整洁的基本功。

实验和主线的边界越模糊，维护成本越高。 实验性的东西如果放在主线目录里，时间一长就分不清它到底是正式功能还是临时尝试。给实验内容一个明确的"身份"和"住所"，可以大幅降低认知负担。

整理不需要一步到位。 这次整理结束后仍有一些未完全收口的部分。重要的是建立起足够清晰的框架，让后续的收口工作可以在已有框架内渐进完成，而不是再来一次大规模重组。

记录整理本身。 整理过程中做了什么决策、为什么这样分、哪些事情还没做完——这些信息如果不记录下来，几周后就会遗忘，然后要么重复劳动，要么困惑于当初为什么这样做。整理工作的文档化和整理本身一样重要。

善用AI工具处理高密度的结构性工作。 这次整理全程借助AI编程助手完成，总共只花了两三个小时。项目整理这类工作的特点是：判断标准清晰但操作步骤繁琐——需要逐个检查文件归属、修改引用路径、调整忽略规则、补写说明文档。这恰好是AI工具最擅长的领域。人负责制定分类标准和做关键决策，AI负责执行大量重复性的搬迁、检查和文档生成。这种分工让整理工作从"大半天的苦力活"变成了"两三个小时的协作流程"，也大大降低了启动整理的心理门槛。

结语

项目整理不是一项额外的负担，而是对开发效率的投资。一个被整理过的工作区，让人打开目录就知道该去哪里找东西、新的内容应该放在哪里。这种清晰感会在后续每一天的工作中持续产生回报。

回头看，年前没有及时整理并不是错误——那时候赶进度是对的。但过了一个月再回来时产生的畏惧感提醒我：推迟整理是有利息的，间隔越长，认知负担的利息越高。屎山不是一天堆成的，但放着不管，它真的会越长越高。下一次，也许不必等到已经感到畏惧才开始。整理的最佳时机是项目还没有大到无法控制的时候——但如果已经大了，那最佳时机就是现在。