rule-change-control
Skill0 starsChanged 5 months agoApache-2.0View on GitHub
修改 GEODoctor 审计规则前必读的变更管控——加规则、删规则、调阈值、调权重、改判定逻辑时使用。核心是三重合同与快照失效链。
In this repository14 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- acceptance-gatesSkill
- architecture-contractsSkill
- bilingual-docs-contractSkill
- debug-audit-pipelineSkill
- debug-site-quirksSkill
- debug-test-failuresSkill
- diagnostic-commandsSkill
- evidence-registry-contractSkill
- failure-archaeologySkill
- release-versioning-controlSkill
- security-boundariesSkill
- showcase-refresh-protocolSkill
- skill-mapSkill
The file
Files
规则变更管控
适用场景
对 src/rules/{access,structure,chunkability,citability,freshness}.ts 的任何改动:新增、删除、调阈值、调权重、改 check 逻辑。
动手前必知的三条锁链
1. 三重合同(tests/version.test.ts 强制执行)
- 规则总数断言为恰好 33——加删规则必须同步改这个数字,否则 CI 红
- 每条规则的
evidence数组至少一个 id,且必须存在于src/evidence/papers.ts注册表——先去读 evidence-registry-contract - 规则 id 全局唯一
2. fixture 余量只有 25 个词
tests/fixtures/good-article.html 的 main 正文 ≈ 175 units,而 cit.fact-density、cit.source-citations、cit.quotables、chunk.list-table-density 的适用门槛都是 150 units。这意味着:
- 把任何适用门槛调高到 176+,这些规则对 fixture 判
na,"good article passes" 系列测试雪崩 - 往 fixture 删一句话同样会雪崩
- 首日真实案例:
list-table-density曾设 200 被 fixture 卡成na(详见 failure-archaeology 案 2),修复决策是统一内容规则适用门槛为 150——这个共识没有写在任何代码注释里,改一处必须改全部 - 辨析:仓库里有三种"150",只有第一种受本共识管——① 上述 4 条内容规则的适用门槛(na 线);②
access.js-dependency的空壳判 0 分线(units < 150);③chunk.paragraph-size的超长段落线(LONG_PARAGRAPH_UNITS = 150)。②③是独立语义,数值巧合,不在"改一处必须全改"范围内
测量 fixture 当前体量的命令在 diagnostic-commands。
3. showcase 快照失效链
任何影响打分的改动(阈值、权重、判定、维度权重 DIMENSION_WEIGHTS)都会让 docs/showcase.md 里 11 个站点的公开分数变成谎言。改分数逻辑 = 必须按 showcase-refresh-protocol 重跑榜单,没有例外。
变更检查清单
- 阈值/权重的新值有依据吗?"感觉更合理"不算——要么引证据,要么在 PR 里写清工程权衡
resultFromScore的全局 status 阈值(fail < 0.4 ≤ warn < 0.85 ≤ pass)不许为单条规则改——单规则需要特殊阈值走第四参数thresholds(chunk.definitions有先例:{ failBelow: 0.3 })- 正反测试都有:pass 路径 + fail 路径 +(若有)na 路径
docs/methodology.md的规则表是手工维护的,与代码没有自动同步——改规则名/权重/证据必须手动同步该表(规则表生成脚本在 diagnostic-commands 的"文档同步"节)- 双语文案按 bilingual-docs-contract 检查
- 安全项:新规则若把站点来源的字符串拼进 finding,必须先过
stripControlChars(security-boundaries D2 防线) - 跑
pnpm test:coverage(CI 不守覆盖率门,见 acceptance-gates)
什么时候不该用这份文档
- 改的是爬虫层(fetcher/page/site)→ architecture-contracts(那里没有 33 合同,但有更硬的数据流不变量)
- 规则输出正确但报告显示不对 → debug-audit-pipeline
- 只是想理解某条规则为什么存在 →
docs/methodology.md - 想给规则找新证据 → evidence-registry-contract
姊妹文档
evidence-registry-contract(证据先行)· acceptance-gates(新规则 DoD)· showcase-refresh-protocol(改完必做)· debug-test-failures(改完测试挂了)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

