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

简介: 本文为《嵌入式AI落地手记》第五篇,聚焦AI工程底座建设:明确原始文件与派生文档的权责边界,以“谁让它变”定归属;Markdown转换重在理解确认而非格式迁移;Git统一管理软件全产物,确保人可审、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 能执行的步骤。

相关文章
|
28天前
|
人工智能 自然语言处理 供应链
1688商家AI提效实践:基于Accio Work的48句提示词体系
1688推出AI生意助手Accio Work标准化指令体系,覆盖经营日报、选品、广告优化等12类高频场景,提供48句即用型提示词。通过分层能力(感知→供应链)与工程化设计(显式指标、安全约束、分步任务),降低商家AI使用门槛,推动B2B电商AI渗透从“能用”走向“会用”。
|
21天前
|
人工智能 API 开发者
47岁货车司机自学AI日烧8亿Token,受邀全球 AI 大会
本文讲述一位47岁初中学历的货车司机胡师傅,零基础自学AI Agent,以自身职业痛点为出发点,研发“AI健康医生”等产品,获极客圈认可并登上全球智能大会——OPC完成度达90%:产品验证、一人闭环、真实落地俱全,唯缺商业化。非鸡汤,是普通人践行OPC的硬核样本。(239字)
|
24天前
|
人工智能 测试技术 开发工具
04 · 给 AI 的流程做减法:三个目标砍成两个的取舍
《嵌入式AI落地手记》第四篇:两次局部优化失败后,作者摒弃修补思维,于9月启动彻底重构——砍掉重复文档与形式主义,保留核心质量环节,重构设计结构与人机分工,将AI深度融入生成+检查全流程,构建以Git、模板、技能、知识库协同的AI原生工程骨架。
|
22天前
|
人工智能 自然语言处理 算法
AI搜索优化落地指南:让机器读懂你的工厂业务
本文解析AI搜索优化新逻辑:企业需提升内容的可检索性、可理解性与可引用性。通过结构化参数、量化实力、问答案例及跨平台一致性建设,抢占大模型认知锚点,实现从关键词排名到AI主动引用的可见性跃迁。
|
21天前
|
缓存 运维 物联网
Lindorm时序引擎的电表补录数据对齐方案
本文介绍工业园区96块Cat.1电表的Lindorm补录对齐实践:以业务时间戳入库、先查后写防覆盖、来源打标三层机制,解决断链恢复后数据乱序、重复与错位问题。方案保障负荷曲线完整、峰谷统计准确、对账零差额,适用于数百至数千点位场景。(239字)
113 1
|
21天前
|
Java
两个时间差多久?这个Java时间差值工具类2个方法搞定
这是一个基于Java 17+的高精度时间差计算工具类,支持`ChronoUnit`与`TimeUnit`双接口,严格区分日历语义(年/月/日)与时长语义(时/分/秒/纳秒),自动处理边界、溢出及空值异常,返回`long`型结果,开箱即用。
|
25天前
|
数据采集 人工智能 黑灰产治理
1688新品指数分的评估逻辑拆解:五维加权模型如何改变发品决策
1688新品指数分(满分5.0)首次量化新品期(30天)表现,以“四个真”保障数据真实,按发品前、新品期内、日常经营三阶段锁定评分,强调动作前移;附加服务为开关型加分项,运费模板合规具否决权。助力商家提升决策确定性与流程效率。
|
26天前
|
人工智能 BI
Accio Work 1688 店铺诊断的工程化拆解:从数据投喂到行动清单的完整链路
本文剖析B2B电商店铺诊断中“上下文工程不足”这一核心瓶颈,提出AI诊断四层公式(定角色×喂数据×划维度×定输出),通过事实与分析分层、结构化提示词、三轮追问及复诊闭环,将数据转化为可执行行动清单,助力企业沉淀自有运营方法论。
|
21天前
|
数据采集 人工智能 数据处理
企业AI落地的技术侧真相:瓶颈不在模型,在流程与组织
本文剖析企业AI落地“高接入、低ROI”困局,指出症结在于仅做工具增强而未重构业务流程。提出以五大经营指标(询盘量、转化率、人效等)替代调用次数验收,并强调需聚焦高频痛点多、结构化强、边界清的场景,由对指标负责的流程Owner推动闭环落地。
|
22天前
|
数据采集 供应链 监控
RFID实现托盘全生命周期的自动化与精细化管理
本方案基于RFID技术,为托盘赋予唯一“数字身份证”,构建标签—采集—应用三层智能架构,实现入库核验、在库追踪、出库校验、循环盘点及回收管理全流程自动化。提升作业效率50%以上,库存准确率达99.9%,显著降本增效、赋能科学决策。(239字)