tanzk/csctalon
0
0
Fork 0
Code Issues 19 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

[governance] 文档性质标记规范：区分「需求」与「需求的需求」+ 全量打标 #71

New Issue
Closed
opened 2026-09-11 19:11:39 +08:00 by tanzk · 1 comment
tanzk commented 2026-09-11 19:11:39 +08:00
Owner
Copy Link

背景

用户提出（2026-09-11）：

「我看这些需求条目，有的是需求，有的是需求的需求，都需要打上不同的标记。」

这个区分戳中了真实混乱：仓库 60+ 份文档混在一起，描述"做一个功能"的与约束"所有功能怎么做"的没有区分，导致：

症状 后果
用"需求"的标准要求"元需求" 要求规范写"验收标准"，但规范的验收标准是"它能否约束住别人"
用"元需求"的稳定性要求"需求" 需求本就该随迭代演进，被当成"锁定不可改"
找不到"约束源" 实现者不知道到底该遵守哪几条，规范沦为摆设
目录名误导 docs/standards/ 里混着 REF 与 REQ，新人无法判断哪份有强制力

影响范围

  • 全部约束性文档：AGENTS.md / docs/standards/*（18 份）/ docs/ 根级（4 份）
  • 新增 1 份规范 + 1 个 AI 指令文件
  • 零代码变更（纯文档治理）

根因判断（governance）

文档体系只有"放哪（docs/README.md）"与"任务怎么流转（issue-workflow）"两类约束，
缺少"文档是什么性质"这一维度 → 三类文档（META/REQ/REF）长期混用同一套审查标准。

处理动作

  • 新建 docs/standards/文档性质标记规范.md（v1.0）：
    三分类定义 + 判定判据 + 三类规则差异表 + 三层落地 + 存量策略
  • 全量打标 25/25 份（META 13 / REQ 5 / REF 7）
  • docs/README.md 新增 §六 文档性质索引（单一事实来源）+ 修复历史表格粘连缺陷
  • 补齐强制链：4 份"标记了但无强制入口"的 META 挂进 AGENTS.md 绝对禁止第 8~11 条
  • AGENTS.md 新增「文档性质纪律（强制）」章
  • review-checklist.md 新增「文档性质」检查项
  • 新增 AI 指令 .github/instructions/doc-class-rationale.instructions.md（自动加载）

关键产出：三类规则差异（这是分类的意义）

META REQ REF
审查标准 能否约束住别人 验收标准是否达成 是否与代码一致
变更成本 高（全仓影响） 中（局部） 低（同步即可）
走架构锁定 ❌ ✅ ❌
AI 自动加载 强制类必须 否 否

★ 盘点发现

  • 11 份 META 中曾仅 4 份有强制入口 → 其余 7 份"标记了但约束不住"
  • docs/standards/ 目录名误导：18 份里混着 4 份 REF + 3 份 REQ
  • 判断易错点：名为"XX接入规范"的文档若只约束一个集成 → 是 REQ 不是 META

验收标准 / 关闭条件

# 验收项 判据
1 规范文件存在 docs/standards/文档性质标记规范.md 含三分类定义 + 判定判据 + 规则差异表
2 标记覆盖率 全部约束性文档头部含 **性质**（实测 25/25）
3 索引登记 docs/README.md §六 含 META/REQ/REF 三张表
4 强制链完整 原 4 份"待挂"META 已进 AGENTS.md 引用链
5 审查可拦截 review-checklist.md 含「文档性质」检查项
6 AI 自动加载 .github/instructions/doc-class-rationale.instructions.md 存在且 applyTo 覆盖 docs/**

关联

  • 触发：#67 讨论中用户提出
  • 类似前例：#70（界面设计说明规范）
## 背景 用户提出（2026-09-11）： > 「我看这些需求条目，**有的是需求，有的是需求的需求**，都需要打上不同的标记。」 这个区分戳中了真实混乱：仓库 60+ 份文档混在一起，**描述"做一个功能"的**与**约束"所有功能怎么做"的**没有区分，导致： | 症状 | 后果 | |---|---| | 用"需求"的标准要求"元需求" | 要求规范写"验收标准"，但规范的验收标准是"**它能否约束住别人**" | | 用"元需求"的稳定性要求"需求" | 需求本就该随迭代演进，被当成"锁定不可改" | | 找不到"约束源" | 实现者不知道**到底该遵守哪几条**，规范沦为摆设 | | 目录名误导 | `docs/standards/` 里混着 REF 与 REQ，新人无法判断哪份有强制力 | ## 影响范围 - 全部约束性文档：`AGENTS.md` / `docs/standards/*`（18 份）/ `docs/` 根级（4 份） - 新增 1 份规范 + 1 个 AI 指令文件 - **零代码变更**（纯文档治理） ## 根因判断（governance） 文档体系只有"放哪（`docs/README.md`）"与"任务怎么流转（`issue-workflow`）"两类约束， **缺少"文档是什么性质"这一维度** → 三类文档（META/REQ/REF）长期混用同一套审查标准。 ## 处理动作 - [x] 新建 `docs/standards/文档性质标记规范.md`（v1.0）： 三分类定义 + 判定判据 + **三类规则差异表** + 三层落地 + 存量策略 - [x] 全量打标 **25/25 份**（META 13 / REQ 5 / REF 7） - [x] `docs/README.md` 新增 **§六 文档性质索引**（单一事实来源）+ 修复历史表格粘连缺陷 - [x] **补齐强制链**：4 份"标记了但无强制入口"的 META 挂进 `AGENTS.md` 绝对禁止第 8~11 条 - [x] `AGENTS.md` 新增「文档性质纪律（强制）」章 - [x] `review-checklist.md` 新增「文档性质」检查项 - [x] 新增 AI 指令 `.github/instructions/doc-class-rationale.instructions.md`（自动加载） ## 关键产出：三类规则差异（这是分类的意义） | | META | REQ | REF | |---|---|---|---| | **审查标准** | 能否**约束住别人** | 验收标准是否达成 | 是否与代码一致 | | **变更成本** | 高（全仓影响） | 中（局部） | 低（同步即可） | | **走架构锁定** | ❌ | ✅ | ❌ | | **AI 自动加载** | 强制类必须 | 否 | 否 | ## ★ 盘点发现 - **11 份 META 中曾仅 4 份有强制入口** → 其余 7 份"标记了但约束不住" - `docs/standards/` 目录名**误导**：18 份里混着 **4 份 REF + 3 份 REQ** - 判断易错点：名为"XX接入规范"的文档若只约束**一个集成** → 是 **REQ** 不是 META ## 验收标准 / 关闭条件 | # | 验收项 | 判据 | |---|---|---| | 1 | 规范文件存在 | `docs/standards/文档性质标记规范.md` 含三分类定义 + 判定判据 + 规则差异表 | | 2 | 标记覆盖率 | 全部约束性文档头部含 `**性质**`（实测 25/25） | | 3 | 索引登记 | `docs/README.md` §六 含 META/REQ/REF 三张表 | | 4 | 强制链完整 | 原 4 份"待挂"META 已进 `AGENTS.md` 引用链 | | 5 | 审查可拦截 | `review-checklist.md` 含「文档性质」检查项 | | 6 | AI 自动加载 | `.github/instructions/doc-class-rationale.instructions.md` 存在且 applyTo 覆盖 `docs/**` | ## 关联 - 触发：#67 讨论中用户提出 - 类似前例：#70（界面设计说明规范）
tanzk added the governance label 2026-09-11 19:11:39 +08:00
tanzk commented 2026-09-11 19:12:10 +08:00
Author
Owner
Copy Link

关闭凭证核验 (2026-09-11)

commit cab6599 · 59 文件 · gitleaks 通过

逐条对应正文「验收标准 / 关闭条件」：

# 验收项 判据 可复现核验方式 结论
1 规范文件存在 含三分类定义 + 判定判据 + 规则差异表 docs/standards/文档性质标记规范.md（229 行）· §二 三分类定义 · §四 三类规则差异表 ✅
2 标记覆盖率 全部约束性文档头部含 **性质** 正则扫描 25 份：25/25（META 13 / REQ 5 / REF 7 / 未标记 0） ✅
3 索引登记 docs/README.md §六 含三张表 §6.1 META(11+本规范) · §6.2 REQ · §6.3 REF · §6.4 待修复项 · §6.5 登记义务 ✅
4 强制链完整 原 4 份"待挂"META 已进 AGENTS grep -oE 'docs/standards/[^)]*\.md' AGENTS.md | sort -u → 9 份，含新增的 error-code / 数据采集合并去重机制说明 / 投诉渠道口径与对账说明 / 数据源接入与缓存加速规范 ✅
5 审查可拦截 review-checklist 含「文档性质」检查项 grep -c '文档性质' docs/standards/review-checklist.md → 检查项含 6 条子项 ✅
6 AI 自动加载 指令文件存在且 applyTo 覆盖 docs/** .github/instructions/doc-class-rationale.instructions.md，applyTo: 'docs/**/*.md,AGENTS.md' ✅

正文 - [x] 勾选

7 项处理动作已全部勾选。

附带的真实修复（超出原验收范围，一并有证据）

问题 根因 核验方式 结论
① Vue 3 模板被编辑器误报 [vue/no-v-model-argument] compileError VS Code ESLint 扩展以工作区根为 cwd，而根目录无 ESLint 配置 → 回退内置默认规则集（含 Vue 2 遗留规则） 实测：vite build / docker compose build --no-cache / 命令行 eslint 全部通过；Node API 复现两个 cwd 均得 118 条规则、该规则=[0] ✅ 已修
② el-radio-button 的 label 弃用告警 Element Plus 2.14.4（package.json 写 ^2.6.2）要求改用 value 迁移 28 文件 / 158 处；浏览器实测 el-radio 弃用告警归零 ✅ 已修

修复文件：eslint.config.mjs（根级桥接，单一事实来源）· web/jsconfig.json · .vscode/settings.json · web/eslint.config.js · scripts/migrate_radio_label_to_value.py（可复现迁移脚本）

验证汇总

文档性质标记覆盖    25/25
AGENTS 强制链 META   9 份
前端 eslint          0 error（5 warning 均为既有 v-html）
前端 vitest          52 例全绿
vite build           成功
docker build         成功（--no-cache）
gitleaks             通过

遗留（非阻塞，已记录在 §6.4）

项 说明
人均效率算法说明.md 存疑 自述为"说明"（REF），但含业务口径（难度系数 ×1.8/×2.0/×5.0），改动会影响全部效率数字 → 若确认需全仓评估，应升级为 META。待业务确认
standards/ 目录名误导 18 份混着 4 REF + 3 REQ；已在 §一 加警示。长期可考虑按性质分目录
存量文档未标性质 按规范 不追溯；谁改动、谁补齐

结论：全部验收项通过，予以关闭。

## 关闭凭证核验 (2026-09-11) > commit `cab6599` · 59 文件 · gitleaks 通过 逐条对应正文「验收标准 / 关闭条件」： | # | 验收项 | 判据 | 可复现核验方式 | 结论 | |---|---|---|---|---| | 1 | 规范文件存在 | 含三分类定义 + 判定判据 + 规则差异表 | `docs/standards/文档性质标记规范.md`（229 行）· §二 三分类定义 · §四 **三类规则差异表** | ✅ | | 2 | 标记覆盖率 | 全部约束性文档头部含 `**性质**` | 正则扫描 25 份：**25/25**（META 13 / REQ 5 / REF 7 / 未标记 0） | ✅ | | 3 | 索引登记 | `docs/README.md` §六 含三张表 | §6.1 META(11+本规范) · §6.2 REQ · §6.3 REF · §6.4 待修复项 · §6.5 登记义务 | ✅ | | 4 | 强制链完整 | 原 4 份"待挂"META 已进 AGENTS | `grep -oE 'docs/standards/[^)]*\.md' AGENTS.md \| sort -u` → **9 份**，含新增的 `error-code` / `数据采集合并去重机制说明` / `投诉渠道口径与对账说明` / `数据源接入与缓存加速规范` | ✅ | | 5 | 审查可拦截 | review-checklist 含「文档性质」检查项 | `grep -c '文档性质' docs/standards/review-checklist.md` → 检查项含 **6 条子项** | ✅ | | 6 | AI 自动加载 | 指令文件存在且 applyTo 覆盖 `docs/**` | `.github/instructions/doc-class-rationale.instructions.md`，`applyTo: 'docs/**/*.md,AGENTS.md'` | ✅ | ### 正文 `- [x]` 勾选 7 项处理动作已全部勾选。 ### 附带的真实修复（超出原验收范围，一并有证据） | 问题 | 根因 | 核验方式 | 结论 | |---|---|---|---| | ① Vue 3 模板被编辑器误报 `[vue/no-v-model-argument] compileError` | VS Code ESLint 扩展以**工作区根**为 cwd，而根目录**无 ESLint 配置** → 回退内置默认规则集（含 Vue 2 遗留规则） | 实测：`vite build` / `docker compose build --no-cache` / 命令行 `eslint` **全部通过**；Node API 复现两个 cwd 均得 118 条规则、该规则=`[0]` | ✅ 已修 | | ② `el-radio-button` 的 `label` 弃用告警 | Element Plus **2.14.4**（package.json 写 `^2.6.2`）要求改用 `value` | 迁移 28 文件 / 158 处；浏览器实测 **el-radio 弃用告警归零** | ✅ 已修 | 修复文件：`eslint.config.mjs`（根级桥接，单一事实来源）· `web/jsconfig.json` · `.vscode/settings.json` · `web/eslint.config.js` · `scripts/migrate_radio_label_to_value.py`（可复现迁移脚本） ### 验证汇总 ``` 文档性质标记覆盖 25/25 AGENTS 强制链 META 9 份 前端 eslint 0 error（5 warning 均为既有 v-html） 前端 vitest 52 例全绿 vite build 成功 docker build 成功（--no-cache） gitleaks 通过 ``` ### 遗留（非阻塞，已记录在 §6.4） | 项 | 说明 | |---|---| | `人均效率算法说明.md` 存疑 | 自述为"说明"（REF），但含**业务口径**（难度系数 ×1.8/×2.0/×5.0），改动会影响全部效率数字 → 若确认需全仓评估，应升级为 META。**待业务确认** | | `standards/` 目录名误导 | 18 份混着 4 REF + 3 REQ；已在 §一 加警示。长期可考虑按性质分目录 | | 存量文档未标性质 | 按规范 **不追溯**；谁改动、谁补齐 | --- **结论：全部验收项通过，予以关闭。**
tanzk closed this issue 2026-09-11 19:12:10 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
缺陷修复
 feature
功能需求
 governance
治理改进
 incident
事故处理
 ops
运维动作
 tech-debt
技术债
No Label governance
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
tanzk
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: tanzk/csctalon#71
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?