AGENT SKILL

engineering-docs

Mosaic 仓库 engineering/ 两个平台(ai-platform、data-platform)的文档规范——四层文档模型(平台索引 / 方案设计 / 实施设计 / 单元定义)、各层固定章节骨架、中文文件名与单元目录编号、状态机与验收编号、覆盖矩阵与完成度检查。当在 engineering/ 下新建平台、新增或推进建设单元(项目 / 期 / 自研件)、写或重构平台级方案设计与实施设计、补写平台 README、对齐两个平台文档格式、做工程文档完成度检查时使用。本 skill 是 engineering/ 全部人手写文档的唯一权威规范,优先于对存量文档的直接模仿;不管 algorithms/(归 mindspring-lab)、roadmap/ 与仓库根 README。当前不带校验脚本,完成度检查按「场景 D」清单人工执行。

License 许可
MIT
所属仓库
Mosslau/Mosaic
最近更新
2026-11-14
Stars
★ 1
Forks
0

01 前言 Front Matter

name
engineering-docs
description
Mosaic 仓库 engineering/ 两个平台(ai-platform、data-platform)的文档规范——四层文档模型(平台索引 / 方案设计 / 实施设计 / 单元定义)、各层固定章节骨架、中文文件名与单元目录编号、状态机与验收编号、覆盖矩阵与完成度检查。当在 engineering/ 下新建平台、新增或推进建设单元(项目 / 期 / 自研件)、写或重构平台级方案设计与实施设计、补写平台 README、对齐两个平台文档格式、做工程文档完成度检查时使用。本 skill 是 engineering/ 全部人手写文档的唯一权威规范,优先于对存量文档的直接模仿;不管 algorithms/(归 mindspring-lab)、roadmap/ 与仓库根 README。当前不带校验脚本,完成度检查按「场景 D」清单人工执行。
agent_created
true

02 资源文件 5

03 SKILL.md 正文

engineering/ 文档规范(四层文档模型)

Overview

engineering/ 下并列两个平台:ai-platform/(AI 平台,7 个纵切项目 + 1 个集成项目)与 data-platform/(通用数据平台,p0–p6 期 + 自研件)。两个平台此前各按各自的方式写文档——一个按"单元六段式 + 索引表",一个按"单篇平台路线文档"——角色与骨架互不认。本 skill 定义统一的四层文档模型:让两个平台角色齐、骨架同、约定一致,只有单元的数量与内容不同。

本 skill 只含规范与模板,不维护任何平台的现状快照——谁做到哪,以各平台 README.md 的单元索引表与磁盘目录为准。

适用范围与边界

管辖:engineering/ 下两个平台的全部人手写文档——平台索引、平台级方案设计与实施设计、单元定义(含单元内的说明性 README)。

不管:

  • algorithms/ 的实验文档 → 归 mindspring-lab skill
  • roadmap/(理论/路线输入文档)、仓库根 README.md、engineering/README.md 的域总览定位 → 不套用本规范的模板结构
  • Markdown 语法与排版风格 → 归 markdown-style skill(本规范只管结构与约定,不管排版细节)
  • 工具产物与生成物(__pycache__/、构建产物、数据集缓存、运行日志、镜像/图表导出物):判据是能否由某条命令重新生成或由工具维护——能,就不归本规范

存量兼容原则:现有文档(如 ai-platform/ 的 7 份单元 README、data-platform/ 的单篇路线文档)与本规范存在出入时,以本 skill 为准,不通过模仿旧文档来推断规范;偏差在完成度检查(场景 D)中登记为待对齐项,而不是视为另一种合法格式。

四层文档模型

层 文件 回答什么 每平台份数 唯一真相源
L1 平台索引 <platform>/README.md 这是什么平台、现在到哪、单元怎么排、文档在哪 1 单元现状快照(状态/日期)
L2 方案设计 <platform>/方案设计.md 长什么样、选什么、边界在哪、契约是什么 1 架构与选型决策
L3 实施设计 <platform>/实施设计.md 分几期/几个单元、每单元做什么、怎么验、多少工作量、什么风险 1 排期、验收编号、风险
L4 单元定义 <platform>/<编号-单元>/README.md 这个单元的目标、范围、架构、验收、笔记 每单元 1 份 该单元的交付物与验收证据

两条宽容规则(为存量形态留合法位置):

  1. L2 + L3 可合体:一份平台路线文档用「上篇 · 方案设计 / 下篇 · 实施设计」分区即可,等价于两份(data-platform/通用数据平台建设路线.md 就是这种形态)。合体时文件名按内容自定,但上下篇的分界必须写在文档头部。
  2. 单元类别可不同:系统(一个可运行系统,如 ai-platform 的项目)、期(一个阶段,如 data-platform 的 p0–p6)、自研件(一块入口/胶水)。类别不同,L4 骨架相同。

各层固定骨架

节名与顺序是契约(用 ## 二级标题,顺序不得调整);每层的完整模板见 references/。

L1 平台索引(6 节):① 定位与状态 ② 单元索引表 ③ 依赖与开工顺序 ④ 覆盖视图(能力域 × 单元矩阵)⑤ 文档地图 ⑥ 边界与校验。

L2 方案设计(8 节):① 定位与判据 ② 总体架构(结构视图 + 数据流视图)③ 能力域与选型(含明确不选)④ 自研边界(入口 / 胶水 / 后置件 + 触发条件)⑤ 契约与规范 ⑥ 环境与规模假设 ⑦ 可用性与容灾口径 ⑧ 与仓库内其他域的关系。

L3 实施设计(7 节):① 实施原则 ② 单元总览 ③ 每单元五要素(目标 / 装什么或做什么 / 交付物 / 验收 / 不做)④ 全局验证清单 ⑤ 工作量与周期 ⑥ 风险与取舍 ⑦ 能力台阶(累积视图)。

L4 单元定义(骨架):元信息头 3 行 + ① 目标 ② 范围与不做 ③ 技术栈(或"装什么")④ 系统架构 ⑤ 前置与复用 ⑥ 验收标准 ⑦ 实施笔记。

  • 允许的两个可选段:「范围与不做」(推荐写);「目录导航」(单元内有子目录/代码时必写)
  • 除这两段外新增段落,须先改本规范再写(防止各单元长歪)
  • 第 ⑤ 段段名按平台固定:ai-platform 用「复用的算法实验」(指向 algorithms/,不许空着);data-platform 用「前置与复用」(指向上游期次 / 既有能力)

五条硬约定

  1. 命名——平台目录用 kebab-case ASCII(ai-platform、data-platform);平台级文档用中文文件名(方案设计.md、实施设计.md),索引页固定 README.md(渲染入口,不译);单元目录 = 可排序编号前缀 + 短名:统一用 P<编号>-<短名>(自 p0 起连续编号:p0-ai-data-foundation、p0-selection-validation)——P 是建设单元族(按建设顺序编号;p0 可作前置探针),单元的性质(系统 / 期 / 集成)由 L4 元信息头的 类别 列承载,不由前缀承载;自研件(入口与胶水)默认不作为单元——它们是单元的交付物,代码放承载单元的模块子目录(由该单元的「目录导航」段登记),确有需要独立成单元时才用 G<N>-<短名> 并按编号族分表。单元内不放无编号的同级单元目录。
  2. 元信息头——单元 README 首 3 行固定:
    > 状态:⬜ 未开始 | 🚧 进行中 | ✅ 已完成(YYYY-MM-DD)
    > 所属平台与单元:<平台> · <编号> <单元名>(类别:系统 / 期;例外:独立自研件单元)
    > 对应文档:<上游文档相对路径>
    
    单元目录编号必须与第 2 行里的编号一致。
  3. 状态机——⬜ 未开始 / 🚧 进行中 / ✅ 已完成:单元 README 首行声明 + L1 索引表同步 + ✅ 必须带完成日期。✅ 的判据是该单元验收清单全部有实测证据(不是"文档写完",也不是"代码能跑")。平台级文档(L2/L3)不用状态机,也不写文档版本号、评审状态与修订记录——文档永远只保留“当前最新”一份,历史由 git 承担。单元答"做到哪",文档答"现在是什么"。
  4. 验收编号——每个平台一套全局编号(前缀平台自定:data-platform 已有 V1–V48;ai-platform 建议 A1–ANN):编号连续、唯一、在 L3 的全局验证清单里逐条给出通过标准;单元的验收清单每条挂编号,每个单元至少承接一个编号。✅ 门槛 = 该单元名下编号全部有实测记录。
  5. 覆盖视图——L1 第 ④ 节必须有一张矩阵:能力域为行、单元为列,图例固定 ● 主要落点 / ○ 涉及 / — 不涉及;矩阵之外可以有说明,但不复制单元结论。单元索引表(第 ② 节)默认一族(P<编号>-),自研件不登记为单元;确有多族时按族分表(每表前 5 列同契约)。索引表建议加一列 形态——探针 / 纵切 / 能力层 / 收口 / 入口:它区分“能演示业务价值的纵切”与“能力铺垫与收口”,不改变单元的性质(期与系统都可能是纵切,也都可能是能力层)。

工作流

场景 A:新建一个平台

  1. 在 engineering/ 下建 <platform>/,先写 L2 方案设计.md(8 节骨架)——架构没定之前不要建单元目录
  2. 再写 L3 实施设计.md(8 节骨架):把建设拆成可独立验收的单元(纵切优先:每个单元跑得起来、可演示),给每个单元分配全局验收编号
  3. 然后写 L1 README.md(6 节骨架):单元索引表 + 依赖与开工顺序 + 覆盖矩阵(此时矩阵可以只有设计意图)
  4. 在 engineering/README.md 的域总览表登记一行(平台 / 目录 / 内容 / 规模 / 状态 / 文档入口)

场景 B:新增或推进一个建设单元

  1. 在 L3 里确认该单元的编号、五要素(目标 / 装什么 / 交付物 / 验收 / 不做)已写清;没有就先补 L3,再建目录
  2. 建 <platform>/<编号-单元>/,按 references/unit-readme-template.md 写 L4:元信息头 3 行(状态 ⬜)+ 骨架段落;不预建空目录——目录随"单元定义"或"真实产物"出现
  3. 在 L1 索引表登记一行:编号 | 单元(链接) | 一句话验收 | 状态 | 完成日期(附加列排在契约列之后)
  4. 推进时:填段落、跑通验收、把实测记录放进单元目录,逐条核对验收清单 → 单元 README 与索引表状态同步改 ✅(带日期)
  5. 单元完成后回看 L1 覆盖矩阵:该单元覆盖的域格子按实际改 ●/○

场景 C:写或改平台级文档(L2 / L3)

  1. 先判定形态:单文件(方案设计.md + 实施设计.md)或合体(一篇,头部写清"上篇 · 方案设计 / 下篇 · 实施设计")
  2. 骨架优先:先按固定 8 节把标题铺出来,再逐节填;缺的节也要留标题并写明"暂无",不许默默删节
  3. 结论唯一:L2 定架构与选型、L3 定排期与验收,同一结论只写一处,另一处用相对链接引用(不复制表格)
  4. 直接改:就地覆盖原文档,不升版本号、不追加修订记录(历史由 git commit 承担),改完检查 L1 索引表的编号/区间是否仍然对得上

场景 D:完成度检查(人工清单)

自动校验脚本暂缺,按下列清单逐项核对;发现问题记进 .dsh/memory/YYYY-MM-DD.md(沿用仓库既有落点,须写基线分支与提交)。

  1. 四层齐不齐:L1/L2/L3 是否都在?每个单元是否都有 L4?
  2. 骨架齐不齐:各层 ## 节名与顺序是否与 references/ 模板一致?缺失的节是否至少留了标题?
  3. 索引 ↔ 目录双向:L1 索引表登记的单元都在磁盘上?磁盘上的单元都登记了?
  4. 状态 ↔ 日期一致:单元 README 首行状态符 = 索引表状态;✅ 是否带完成日期且两处一致?
  5. 编号一致:单元目录编号 = 元信息头编号;全局验收编号是否连续、唯一、每单元至少承接一个?
  6. 覆盖矩阵:每个单元是否至少在一个域上标了 ●/○?是否有域在所有单元里都是 —(那就是缺口,需在 L3 里说明何时补)?
  7. 验收证据:✅ 单元的验收清单是否全部打勾,且每条证据可被第三方按所给命令重跑(命令、输入、观察结果三要素)?
  8. 内容深检(存在性全绿不代表合格):架构图与选型理由是不是"只列名词";工作量与周期是否给了人力假设;风险是否每条都有对策;"不做"清单是否存在。

与相邻规范的关系

规范 管什么 与本文档的分工
mindspring-lab algorithms/ 实验(手写纪律、双跑对照、六段式、索引表) algorithms/ 的结论不是本规范的模板;单元第 ⑤ 段引用实验时用相对链接
markdown-style Markdown 语法与排版风格 本规范不管标题层级之外的美观问题;两者可同时生效
仓库根 README.md 三大域的总体导航与校验入口 平台文档不重复根 README 的域介绍

Resources

references/

  • references/platform-readme-template.md — L1 平台索引六节权威模板
  • references/design-template.md — L2 方案设计八节权威模板(含合体形态的"上篇"写法)
  • references/plan-template.md — L3 实施设计八节权威模板(含单元五要素表与全局验证清单)
  • references/unit-readme-template.md — L4 单元定义骨架权威模板
  • references/index-format.md — L1 单元索引表的列序契约(前缀平台自定,列序固定)

记忆落点

  • .dsh/memory/YYYY-MM-DD.md — 场景 D 的缺口登记落点,每条必须带基线(分支与提交)

写作时先读对应模板再动笔;检查时先按场景 D 清单逐项核对,再登记缺口。

04 同仓库更多 Skills