docs(任务规划): 新条目改用语义标识——"编号不回收"在实践中不可执行
登记簿原规则写着"编号不回收"(README §0 与 §3 各一处),但销项 = 删行, 删完仓库里就不留任何痕迹 → 该规则要靠人先想起去翻 git log 才成立。 实测撞号:登记簿 N-31(2026-10-11 的 Phase 7 复跑项)销项后,2026-10-14 新建条目按"现存最大值 +1"又取了 N-31,与 CH395F_Test_Guide.md、 自动化测试流程.md 里那两处历史引用同号。 裁定(用户 2026-10-14):新条目 # 列填语义短语(如 "沉降窗 800ms 上限只留痕"),不再新增字母+数字编号;存量编号冻结沿用, 已随销项消失的号一律永久作废、不得作为新条目候选。语义标识自带唯一性 (重名一眼可见),从结构上消除复用可能。 改动:README §0 表首新增"语义标识"行 + 撞号因果注记;§3 原"编号一律 沿用且不回收"整条重写;AGENTS.md 完成即销项条目追加本裁定。 已确认无门禁校验编号格式(check_doc_links 只校 §N.M 与文档路径, 脚本里的 N-23/T-1 是注释性出处)→ 换标识不破任何钩子。
This commit is contained in:
@@ -151,7 +151,7 @@
|
||||
|
||||
## 文档与图形
|
||||
|
||||
- **登记簿类文档「完成即销项」**:`docs/任务规划/README.md` 这类待办登记簿,事项修复/关闭后**直接从表中删除该行**(不保留"已消化"行)——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须:① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 `check_doc_links.py --all` + pre-commit
|
||||
- **登记簿类文档「完成即销项」**:`docs/任务规划/README.md` 这类待办登记簿,事项修复/关闭后**直接从表中删除该行**(不保留"已消化"行)——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须:① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 `check_doc_links.py --all` + pre-commit。**新条目标识(用户裁定 2026-10-14)**:`#` 列填**语义短语**(如 `沉降窗 800ms 上限只留痕`),**不再新增字母+数字编号**——"编号不回收"只写规则却不留痕迹就不可执行(销项删行后仓库无痕迹,实测 `N-31` 于 2026-10-14 被复用撞号),语义标识自带唯一性;存量编号冻结沿用、**已随销项消失的号永久作废** → `docs/任务规划/README.md` §0
|
||||
- 图形走 **`draw-diagram` skill**:精确布局图用 `tools/arch_diagram/gen_*.py` 生成器(产物放 `docs/images/`,脚本与 .svg 一并提交);拓扑图用 Mermaid;**勿手绘 ASCII 框图**。文件引用关系图走 `tools/refgraph`(`& 'tools\refgraph\gen_refgraph.bat'`)
|
||||
- **改名 / 挪目录一律走 `scripts/rename_ref.py`(先 dry-run,确认后 `--apply`)**:`git mv` + 自动改写全库引用(反引号引用 / Markdown 链接 / 图片 `../` 层级换算 / `#include` / `uvprojx` `<FilePath>` / `CMakeLists.txt`),落盘后自动跑 `check_doc_links --all` 复核——手工扫引用既慢又漏(一次改名历史上波及 10~30 文件)。引用章节用「`路径.md` §N.M」**紧邻写法**(`doc-links` 校验编号是否还在:紧邻/裸名/前缀/别名/自引用**全部拦提交**(钩子带 `--sections-strict`);每次跑打印「可判定比例」,`--section-todo` 出待改清单,昵称歧义就登记 `scripts/section_aliases.json` 或写清楚)→ `docs/文档规范.md` §3.5 / §3.6
|
||||
- 文档写作规范(编码/BOM/链接/表格/一致性钩子)→ `docs/文档规范.md`;全量索引与推荐阅读顺序 → `docs/README.md`
|
||||
|
||||
Reference in New Issue
Block a user