05 · 连目录结构都要为 AI 重新设计

——底座：让 AI 可读、让人可审、让版本可回溯

这是《嵌入式 AI 落地手记》的第五篇。上一篇讲了为什么彻底重构，这篇讲新体系的工程底座：原始文件、目录、分支和版本，怎样围绕 AI 与人协作重新安排。

原始文件一定要转成 Markdown 吗

第二次试用新项目流程时，我们把 Word、Excel 原始文件直接提交进了 Git。

这个做法是有意为之。我们实际验证过，AI 直接读写这些文件已经很容易。既然这样，多一道 Markdown 转换，反而可能多一层信息丢失。

当时 Git 和文件服务器的分工还没有最终定论，我没有直接否定这种做法。这个理由很实在，也确实给我们出了一道题：如果 AI 已经能直接读原始文件，转换还有什么必要？

后来，我们仍然决定：后续项目的二进制原始件不进 Git，Markdown 转换件跟随软件版本管理。

这不是因为直接读取的路线错了，而是因为我们评价这件事时，看的已经不只是 AI 能不能读。

文件按“谁让它变”来分

文件服务器和 Git 的分工，最后落在一条原则上：看谁让它变，不是谁用它。

客户重新发布一版原始需求，变化发生在客户输入上，权威原件就按版本留在文件服务器。硬件资料随硬件改版演进，也留在那里。客户交付物和验收资料有自己的版本与体积，同样不适合塞进软件仓库。

工程师根据这些输入形成的需求规格、设计、代码、测试用例，是软件派生产物，全部进 Git。它们需要频繁修改、逐行比较、评审和回溯，Git 正好擅长这些事。

同一份资料可能被很多人使用，但使用方多，不代表每处都要存一份。接口定义可能同时被软件和硬件使用，它的演进主人仍然是外部输入；硬件设计文件可能被软件工程师参考，它的演进主人仍然是硬件改版。归属先看变化从哪里来。

如果按使用方各自复制一份，短期内大家取用都方便，变更后却很容易说不清哪份为准。人还能开口确认，AI 可能直接把两份看似都有效的输入一起读进来。

这条原则听起来和 AI 无关，却决定了 AI 以后读到的是哪一份、哪个版本，以及它能不能把不同阶段的产物放在同一个上下文里理解。

转换的目的，在用起来以后变了

最初把原始输入转成 Markdown 进 Git，目的很直接：让输入也能接受版本管理。二进制文件可以进 Git，也可以打上 Tag，但它的 diff 通常不能告诉评审者哪条需求变了；多人用 Office 编辑时，还可能出现锁文件。Markdown 转换件则可以和需求、设计、代码钉在同一个基线上，逐行比较，在 PR 里讨论。

实际用起来以后，重心慢慢移开了。

原理图、CAD 图这类文件，本来就不适合 AI 直接读。把它们转成文字的过程本身就是一次理解：哪些功能点还不确定，转换时会暴露出来，正好拿去和硬件同事、客户逐条确认。客户来的需求文档也类似：有的信息密度不高，有的有错误和没澄清的地方，转成 Markdown 的过程，同时就是需求的理解、评审和确认。

所以转换时，我们要求 AI 着重理解软件开发需要知道的细节，而不是逐字搬运原文。到今天，转换的主要目的已经不是用 Git 管住输入基线，而是让输入文档更适合后续开发中 AI 的理解。

输入基线换了一种方式管理：各版原始输入按版本号命名的子目录留在文件服务器，Git 分支与输入版本子目录的对应关系，记录在“软件版本与文档台账”里。

转换件跟随软件版本管理的约定没有变，双轨也不是“转完就扔原件”：

• 二进制原件留在文件服务器，可编辑，是权威源；
• Markdown 是派生件，进入 Git 后只读，禁止手工修改；
• 首行记录源文件、源版本和转换信息，首次转换及原件变更后由人抽检；
• 原件变了就重新转换，发布前再核对 Markdown 标注的源版本与冻结原件一致。

如果两边内容有出入，回到权威原件查证。直接读取仍然可以作为某些一次性任务的选择，但在我们的完整流程里，理解和确认这一步不能省略。

还有一层分工也藏在“只读”里：AI 可以阅读原始输入、提出疑问、生成派生产物，却不应该直接改写客户提供的权威文件。它需要修改的是自己的草稿，权威输入的变更仍然由人接收和确认。

Git 不只是代码仓库

这套体系里，文档和代码接受同样的版本管理与评审。

需求、设计、编码、测试用例各有阶段分支。阶段工作完成后，通过 PR 合并到主干，再打对应的基线 Tag。评审结论和被评审的提交都留在 PR 里，分支保护保证它不会只靠大家自觉执行。

之后进入测试和发布，再有发布分支与维护分支。量产后的修复需要立即形成补丁版本，也要回流到后续活跃版本，避免同一个问题在下一次发布里重新出现。

比如一个版本发布后发现了问题，而下一版已经在开发。只在维护分支上修，下一版可能继续带着同样的问题；直接改正在开发的主线，又无法保证已发布版本可维护。维护分支与修复回流，就是在同时照顾这两头。

我没有把这些分支设计得很花哨。真正重要的是，一个 Tag 能找回同一批需求、设计、代码和测试产物。人需要这个一致性，AI 也需要。它做设计时如果读到最新需求、旧版设计和另一版接口定义，生成得再流畅，基础也是错的。

目录是给人和 AI 的导航

项目仓库模板进一步规定每类产物的位置：需求、设计、代码评审、测试、发布各有目录，源代码、测试代码、工程文件和工具配置也各有归属。AI 不必每次扫描整个仓库猜测哪里有任务输入，人也能知道评审应该看哪些文件。

对 AI 来说，目录还是一种工作边界：哪些文件只读，哪些可以生成，哪些必须由人修改。边界越明确，误写权威原件、覆盖既有产物的风险越小。

文件服务器一侧则有一本“软件版本与文档台账”，把 Git 仓库、发布 Tag、维护分支、需求版本、交付版本和硬件改版联系起来。软件补丁不再新建一套交付目录，只在维护记录里增加一行。

例如同一块硬件先配正式版，后来只修复了一个软件问题：硬件没改，需求没变，只是软件多了一个补丁。若每种组合都新建目录，很快会出现大量重复；在台账里增加一条维护记录，就能保留各自独立的版本线。

这也提醒我，版本不是只有一根轴。需求版本、软件版本、硬件改版和客户交付版本彼此相关，却不一定同步变化。目录负责分类，台账负责把它们重新串起来。

踩坑与教训

写这篇之前核对规范时，我还发现几处没有同步的地方：说明文件里残留着已经取消的交付物，一个空目录的用途和当前原则对不上，仓库结构简图也没有跟上项目仓库模板的最新版本。

这类偏差过去可能只影响新人找文件，现在还会直接影响 AI。人会随口问一句，AI 更可能照着旧说明认真执行。规范本身也需要维护，不能把它当成一次设计、长期有效的静态资产。

如果你也在设计类似的工程底座，我会先检查四件事：每类信息是否只有一个权威源；派生文件是否禁止各自修改；每个产物是否有明确归属；版本和评审规则是否已经落到实际工具路径里。目录不是越多越好，能消除重复和歧义才有价值。

下一篇

工程骨架解决了文件放在哪里、版本怎样固定、评审怎样发生。接下来还有一层问题：AI 接到一个阶段任务后，具体先做什么、再做什么，什么时候必须停下来等人回答？

下一篇讲技能库：怎样把开发流程拆成 AI 能执行的步骤。