scaling.md

何时拆分

数字只用来阻止文件和目录无限膨胀，不表示到线后由工具机械切割。拆分必须按独立用户流程、代码 owner、输入输出或验证方式进行。

单个文件太长

大小	要求
doc/knowledge/CONTRIBUTING.md 超过 100 个非空行或 8 KiB	校验器报错。必须把细则继续下沉到 contributing/，入口只留路由和交付清单
达到 300 个非空行或 16 KiB	校验器给提醒。检查是否已包含两个以上独立主题
达到 500 个非空行或 32 KiB	校验器报错，必须按主题拆分。确有不拆理由时，在同目录 _index.md 里同时写出文件名和字面词 暂不拆分（校验器认的就是这两样），再补不拆原因和复核日期

不每 300 行切一刀。一篇 350 行但只有一个完整流程，可以保留；一篇 200 行但已混了五类日常任务，应该提前拆。

一个目录页面太多

• 一个知识目录先直接放最多 7 个普通内容页；_index.md、rules.md、architecture.md 不计。
• 出现第 8 个普通页，或已有 3 篇明显属于同一主题时，建立 guides/、incidents/ 或有明确人话含义的分类目录。超过 7 页只是提醒，由人判断要不要分类。
• 分类目录（guides、incidents、history、references、results、rfcs 及其子目录）不受这条 7 页提醒约束；但超过 20 篇当前有效页面时校验器报错，必须按稳定主题继续分类。
• 分类最多再向下增加一层，避免重新形成很深的目录。
• 错题先按问题主题分，不先按年份分。只有错题超过 50 篇时才增加年度历史入口。

从一个 dev 发展成前端和后端

项目早期可以只有：

repos/acme/
  _index.md
  architecture.md
  dev/
    _index.md

前端和后端在下列四项中至少有两项各自独立时，再拆成 component：

• 源码目录；
• 测试命令；
• 部署方式；
• 运行流程或输入输出。

拆分后：

repos/acme/
  dev/
    _index.md                       # 前后端共用的开发流程
  components/
    _index.md
    frontend/
      _index.md
      architecture.md
    backend/
      _index.md
      architecture.md

不拆成 dev/frontend/backend。dev 是工作主题，frontend/backend 是代码 owner。仓库根部 architecture.md 继续保留系统总览，细节分别下沉。

模型或代码模块长大

• checkpoint 和尺寸增加：先补别名和差异，不新建目录。
• 模型出现完全独立的源码、配置语义或运行流程：建并列模型目录。
• 代码模块出现至少两个独立源码区域，而且各自有架构和测试方式：拆成并列 component。
• architecture.md 很长但仍是一块代码：拆同目录专题页，不虚构新 component。

拆分必须同步完成

1. 新页面按主题分，不机械按行数分。
2. 每个新页面都从最近 _index.md 可达。
3. 创建或删除子目录时，更新上一层 _index.md。
4. 修复全仓指向旧路径的链接。
5. 旧文件不再继续接收新内容，重复正文已删除。
6. CLAUDE.md 仍然只是短入口，不因底层页面拆分而膨胀。
7. 运行 同步与校验 中的检查。