tako 文档 GitHub

文档归属重构(2026-11-03)

性质:变更记录——当时为什么动、动了什么、怎么验收。不是方案,也不是施工真源。 现行规则看 doc/README.md §5 与 AGENTS.md「文档状态与真源」。 执行流水看同目录 tasks.md(冻结)。

病灶

旧规则按时效分家:doc/ 现行、docs/ 历史、tmp/ 台账。但实际放法按类型分——交接稿进 docs/、方案进 doc/、裁定进 doc/problems/。两套规则打架,同一类文档出现多个家:

  1. 记录被当垃圾:docs/2026-10-19-多租户-handoff.md 是 doc/28 引用的施工期实测实录,还在服役,目录名却说它过期。
  2. 同类文档三个家:交接稿在 docs/ 有 9 篇,doc/ 根还躺着 handoff-doc24-… 与 XX-taskboard-…。
  3. 检索污染:grep 一个机制先命中 v3/v4 再命中现行,逼出「已作废不作论据」这条补丁规则。
  4. 判断成本高:新人得先读规则才知道 doc/ 与 docs/ 的区别,而规则本身与刚写进去的跑分文章矛盾。

根因是用会变化的「时效」当归属轴:从现行变历史要搬家,但搬家从没发生;新内容又按类型随手放进一个叫「历史」的目录。

拍的轴

按类型定家,不按时效:

类型 家
现行真源 doc/ 顶层编号文档 + doc/19-v6/
设计裁定 doc/problems/
带日期的记录(交接、跑分、台账、文章) doc/log/
被整代取代的材料 doc/archive/
非方案(故事、求职材料) doc/blog/

时效变化不搬家,只改状态;只有被整代取代才进 doc/archive/。

动了什么

验收

bash scripts/check-doc-layout.sh    # doc layout: OK
bash scripts/check-master-plan.sh   # OK:doc/16 已覆盖 README §1 全部现行编号
test ! -d docs                      # docs gone

负向自检:在 doc/ 顶层放一个 2026-01-01-*.md,脚本判红并退出 1;删除后恢复 OK。

关联真源