仓库知识地图

问题从哪来

很多仓库把规则、架构、流程全塞进根目录的 CLAUDE.md，文件很快涨到几百行。Agent 每次进项目都要吞掉大量上下文，内容还无法机械校验，代码一改文档就脱节。Slack 和口头共识若没写进仓库，对 Agent 来说等于不存在。

这套做法在做什么

核心立场是：CLAUDE.md 是地图，不是百科全书。入口文件只负责指向 docs/ 里的真相来源，配合渐进式披露——Agent 从小入口知道「去哪找什么」。

技能分两条路径：

• 从零：按模板搭 docs/ 骨架（如 ARCHITECTURE.md、QUALITY_SCORE.md、设计文档与 exec-plan 索引等），并在入口写明「这是地图，细节见 docs/」。
• 已有膨胀文档：评估现状 → 设计目录骨架 → 按主题拆到 docs/*.md → 把 CLAUDE.md 改写成指针表，并给每篇文档补「讲什么、何时读」。

doc-gardener 会在流程内做四类校验：断链、新鲜度（关键文档超过约 30 天未验证则待复核）、与代码域的覆盖、目录是否符合约定骨架。失败项会写成可直接执行的修复说明。

硬约束包括：CLAUDE.md ≤ 100 行、docs/ 内链断链率为 0、每个 docs/ 文件需有元数据头。

适用边界

• 单文件小脚本、只需改某一两篇文档时，不必上整套重构。
• 需要从零初始化完整 harness（含 .gitignore、CI 等）应走 harness-bootstrap，本技能聚焦知识治理与渐进式披露。
• 自动生成文档应放在 docs/generated/ 并标明；与手写文档冲突时，手写优先，doc-gardener 会按中等严重度报告。