docs: codify docs structure contract

2026-08-10 01:20:59 +00:00 · 2026-05-05 02:11:38 +08:00
parent e6012e88c6
commit 370f0432ac
8 changed files with 53 additions and 3 deletions
@@ -20,13 +20,16 @@ concepts/

 ## 修改规则

+- 继承 `docs/AGENTS.md` 的 README 结构契约：H1 后直接进入 `## 字多不看`，再按 `快速导航 -> 完整细粒度目录 -> 使用方式 -> 正文` 排列。
 - 新增概念内容时，必须追加到 `README.md` 的对应章节。
 - 不再新增同级主题 `.md` 文件；如确需拆分，必须同步更新全仓链接和 `metadata/redirects.yml`。
 - 概念文档应优先使用稳定术语，避免同一概念多种叫法并存。
 - 不把一次性操作步骤放入本目录；操作型内容应放入 `docs/getting-started/` 或 `docs/references/`。
+- 不在 README 正文中写 `和其他目录的边界` 或 `维护规则`；维护者规则只写本文件。

 ## 质量要求

 - 每个概念先说明它解决的问题。
 - 尽量给出使用场景、判断标准和简单例子。
 - 不确定的外部事实必须标注 TODO，或放入 `docs/research/` 等待验证。
+- 修改后必须运行 `make sync-doc-toc` 和 `make test`。