Front-End Checklist 规则质量提升实战指南:用 improve-rule 技能打磨可被 Agent 引用的规则库

原创2026-09-18 20:58:532,325 阅读

Front-End Checklist 规则质量提升实战指南:用 improve-rule 技能打磨可被 Agent 引用的规则库

本文基于仓库 skills/improve-rule/SKILL.md 及其配套评分规范 skills/improve-rule/references/scoring-rubric.md,系统讲解 Front-End Checklist 项目如何量化评估、诊断并改进每一条规则(rule)MDX 文件的质量。你将掌握评分维度与及格线、Stub 提示词识别、结构校验命令、Rule Contract V2 条件章节,以及一套可直接落地的 8 步改进流程,并通过真实规则文件剖析高分规则的写法。

为什么规则质量是一条可以量化的工程指标

Front-End Checklist 仓库的核心资产是 packages/content/rules/en/ 下按 accessibility、css、html、images、performance、security、seo 等分类组织的 385 份规则 MDX 文件。这些规则既是给人读的检查清单,也是给 AI Agent(如 Claude Code 技能)用的可触发指令源。

improve-rule 技能的核心观点是:规则质量分数是"这条规则对开发者与 AI Agent 有多大用"的代理指标。Stub 提示词会让 AI 收到泛泛而谈的指令而无法给出针对性帮助;缺少代码示例的规则难以被学习;缺少 aiContext 的规则作为技能时不会在正确时机被触发;缺少 relatedRules 的规则会变成知识孤岛,Agent 无法沿知识图谱遍历。因此仓库把"规则写得好不好"落成了一套可运行、可进 CI 的量化打分系统。

质量维度全景:从评分表到真实实现

SKILL.md 给出的质量维度表是技能层面的操作指南:

Dimension Max What "good" looks like
prompts.check 10 Specific audit instruction, not generic
prompts.fix 10 Actionable fix steps with CSS/HTML/JS specifics
prompts.explain 10 Explains the why, not just restates the title
tldr 5 3+ concise bullets, each a standalone takeaway
whyItMatters 5 1–2 sentences, concrete user impact
aiContext 5 "Applies to…" — when should an agent use this?
relatedRules 5 2+ slug + reason pairs
codeExamples 10 3+ ✅/❌ annotated blocks in the body
bodyDepth 10 300+ words, not a stub
resources 5 External links (MDN, WCAG, articles)
prompts.codeReview 5 Code review workflow prompt (optional)

需要说明的是,这是技能的简化描述。实际打分器 scripts/rule-structure/score-rules.ts 的权重略有不同,并引入了更多维度。从源码看,真实计分结构为:

  • Prompts 组(共 24 分):prompts.check / prompts.fix / prompts.explain 各 8 分,非 Stub 满分、命中 Stub 模式仅 2 分、缺失 0 分;
  • 元数据与来源组(共 42 分):tldr 4 分、whyItMatters 4 分、aiContext 6 分、relatedRules 6 分、sources 6 分、sourceQuality 4 分、resourcesOrTools 6 分、prompts.codeReview 6 分;
  • 正文内容组(共 34 分):codeExamples 10 分、bodyDepth 10 分、verification 8 分、thresholds 6 分;
  • Rule Contract V2 条件组(最高 12 分):exceptions、verificationSplit、standardsVisibility 各 4 分,仅在对应规则类型"应当包含"时计入总分。

评分细则在 skills/improve-rule/references/scoring-rubric.md 中有完整定义,其中每个维度的得分档位、Stub 自动检测模式和优秀示例都有明确标准。例如 tldr 3 条以上得满分、1–2 条得 2 分、缺失 0 分;whyItMatters 需超过 40 字符且解释用户影响;codeExamples 要求 3 个以上围栏代码块,并建议成对给出 ✅ 正确与 ❌ 错误示例。

评分分级与及格线

按照评分规范,分数按百分比映射到 A–F 六个等级:

Grade Score Range % of max
A 68–80 ≥ 85%
B 56–67 ≥ 70%
C 44–55 ≥ 55%
D 32–43 ≥ 40%
F 0–31 < 40%

最低及格线为 50 分。SKILL.md 原文表述为 "Base score: 100 with additional conditional V2 points. Target: ≥ 50 (passing)",而 score-rules.ts 中 DEFAULT_MIN_SCORE = 50 也印证了这一阈值——在 CI 或指定文件计分时,低于该分数会导致进程以退出码 1 结束。

识别 Stub 提示词:自动检测的"低质量模式"

Stub 提示词是自动检测到的低质量提示模式,SKILL.md 列出了三类典型:

  • "Verify if the project adheres to: [Rule Title]"
  • "Update the codebase to align with: [Rule Title]"
  • "Explain the importance of [Rule Title]"

实际检测逻辑在 score-rules.ts 的 STUB_PATTERNS 正则数组中,还包括两个变体:check if ... follows best practices(按最佳实践检查)与 ensure ... is implemented correctly(确保正确实现),且对以这些短语开头(^)的提示词大小写不敏感匹配。评分规范还补充了一个启发式规则:任何仅复述规则名、不足约 20 词的提示词也会被视为 Stub。

优秀的 check 提示词应点名要审计的具体 HTML 属性或模式,评分规范给出了范例:

"Audit all <img> elements for missing or decorative-but-present alt attributes. Flag images where alt is missing entirely, where alt contains 'image of' or 'photo of', and where decorative images have non-empty alt text."

同理,fix 应给出引用真实 HTML/CSS/JS 语法的分步补救方案;explain 应解释"为什么"——用户影响、浏览器行为、可访问性后果,而不是复述规则标题。

检查:跑分与结构校验双管齐下

SKILL.md 提供的检查流程分两步。第一步,对单条规则跑质量打分器:

pnpm score:rules packages/content/rules/en/{category}/{slug}.mdx

第二步,运行结构校验器:

pnpm validate:rule-structure packages/content/rules/en/{category}/{slug}.mdx

打分器支持的参数

从 score-rules.ts 的头部注释与 main() 实现看,pnpm score:rules 支持:

  • 无参数运行:对 packages/content/rules/en 下所有分类的全部规则计分,输出汇总报告(规则总数、平均分、及格/不及格数量、A–F 分布);
  • --failing:只打印低于阈值(默认 50)的规则;
  • --json:输出 JSON 供 CI 或其他工具消费;
  • --min 60 或 --min=60:自定义最低分数线;
  • 末尾追加 .mdx 文件路径:只计分指定文件,若有文件低于阈值则以退出码 1 退出,便于 CI 门禁。

报告输出采用排序条形图形式,例如 [C] alt-text 64/80 ████████...,并逐条列出各维度 note 提示(如 stub — needs rewriting、missing — add for better skill targeting)。

结构校验器支持的参数

validate-rule-structure.ts 提供更多能力:

  • pnpm validate:rule-structure:全量校验,与 scripts/rule-structure/rule-structure-baseline.json 基线比对,只报告"新增"问题;
  • pnpm validate:rule-structure --report:输出结构化报告,含各分类的 V2 缺口统计与迁移批次汇总(--json 可输出 JSON);
  • pnpm validate:rule-structure --write-baseline:把当前问题写入基线文件;
  • pnpm validate:rule-structure --baseline path:指定基线文件;
  • 指定单文件路径时进入 strict 模式,所有问题都会被报告(不受基线豁免)。

此外 package.json 中还有 report:v2-gaps(即 pnpm validate:rule-structure --report)快捷命令,且 ci:check 已把 validate:rule-structure 纳入全量 CI 流水线。

规则体的结构与契约

校验器检查的核心是 H2 章节的顺序与命名,规范定义如下顺序(scripts/lib/rule-structure.ts 中由 REQUIRED_RULE_SECTION_TITLES 与 analyzeRuleStructure 实现):

  1. 任何 H2 之前的引言段落(intro paragraph);
  2. ## Code Example 或 ## Code Examples;
  3. ## Why It Matters;
  4. 可选指导章节(guidance sections);
  5. 最后的 ## Verification。

自动检测的问题码(RuleStructureIssueCode)包括:missing-code-examples、missing-why-it-matters、missing-verification、code-examples-after-why-it-matters(代码示例不能排在 Why It Matters 之后)、why-it-matters-after-verification、verification-not-last(Verification 必须是最后一个 H2)、deprecated-verification-heading、inline-metadata-prose(禁止独立的 See also / Reference: 行)。

## Verification 的旧式别名会被标记为 deprecated,包括 Testing、Audit Checklist、Checklist、How to Verify、Testing & Validation、Testing and Validation、Testing & Monitoring 等,统一建议改名为规范的 ## Verification。可选章节则有固定词表(OPTIONAL_RULE_SECTION_TAXONOMY):Best Practices、Common Mistakes、Framework Examples、Tools & Validation、Thresholds、Exceptions、Browser Support、Support Notes、Standards、Implementation Notes、Common Patterns、Accessibility Requirements、Testing Tools、Performance Considerations——出现词表外的 H2 会被记为 unknown optional heading,作为漂移信号报告但不强制失败。

Rule Contract V2:按规则类型动态追加的条件章节

SKILL.md 强调,V2 契约只在规则类型真正受益时才要求追加:

  • ## Exceptions:适用于易产生误报、存在边界情况或合理例外的规则(exceptionHeavy 特征,如 accessibility、security、seo 类);
  • ### Automated Checks 与 ### Manual Checks:当规则既能自动化又能人工复核时,在 ## Verification 内拆分;
  • ## Browser Support、## Support Notes、## Standards:当浏览器兼容性或合规性会影响实现决策时使用。

特征判定逻辑在 scripts/lib/rule-structure.ts 的 analyzeRuleContract 中,通过正则扫描分类名、slug、标题、正文、prompts、sources、resources、tools 的拼接文本(haystack)来推断六类特征:compatibilitySensitive(如 subgrid、@property、container queries、service worker、HTTP/2、PWA 等关键词)、measurable(依赖 expectsThresholds 判定)、exceptionHeavy、automationFriendly(如 eslint、axe、lighthouse、playwright、jest 等)、manualReviewImportant、standardsSensitive(如 wcag、w3c、owasp、core web vital、canonical、robots、aria)。expectsThresholds 还会按 slug 中的 lcp/inp/cls/ttfb/budget/size/contrast 等关键词,或 performance/images 分类直接要求可见阈值。

SKILL.md 还特别提醒:浏览器支持说明必须使用仓库的 browser policy 与包级兼容性数据(scripts/lib/rule-support-data.ts 支撑),不要凭记忆猜测支持范围。thresholds 维度的可见阈值判定(hasVisibleThresholds)会检查正文中是否出现 ≤/≥/< 等符号加数字,或 ms/s/kb/mb/px/vw/% 等单位。

改进实操:8 步让规则从不及格到高分

SKILL.md 的 Fix 章节给出了明确的改进优先级,其中 Stub 提示词三项合计分数最高(按技能表为 30 分),应最先处理:

  1. 先修 Stub 提示词——check 点名要审计的属性/模式,fix 给出带代码片段的分步补救,explain 解释用户影响而非技术细节;
  2. 补充 aiContext——一句话即可:"Applies to any HTML page with [X]" 或 "Use when reviewing [Y] in [Z] context",这是技能在正确时机触发的关键;
  3. 补全/扩充 tldr——至少 3 条,每条都以可执行的经验法则收尾,避免复述规则名;
  4. 丰富正文——为每个概念同时提供 ✅ 好示例与 ❌ 坏示例的代码块;
  5. 添加 relatedRules——至少 2 对 "slug + reason",说明规则间的联系;
  6. 添加 resources——MDN 文档、WCAG 成功标准、权威文章(注意:正文中链接应融入自然语句,不要写孤立的 See also 行,否则触发 inline-metadata-prose 问题);
  7. 修复结构 lint 问题——把 Testing/Checklist 风格的结尾标题统一改为 ## Verification,指导章节放在 Why It Matters 与 Verification 之间,且 Verification 之后不得再出现 H2;
  8. 按需补充契约清晰度——Exceptions、验证拆分、标准/支持说明只在规则类型确实受益时使用。

Code Review:PR 验收清单

在 Review 新增或修改规则 MDX 的 PR 时,SKILL.md 要求逐项核对:

  • 无 Stub 提示词(可 grep "Verify if the project adheres to");
  • 至少 3 条 tldr 要点;
  • whyItMatters 具体明确(提及用户影响,而非空泛的 "improves quality");
  • 正文至少各有一个 ✅ 与 ❌ 代码示例;
  • ## Verification 是最后一个 H2,且 ## Why It Matters 位于其之前;
  • pnpm validate:rule-structure {file} 通过;
  • 分数 ≥ 50:pnpm score:rules {file}。

实战剖析:一条高分规则长什么样

以 packages/content/rules/en/images/alt-text.mdx 为例,可以看到上述所有要求的落地形态:

  • frontmatter 元数据完备:含 title、description、categories、subcategory、priority: critical、difficulty、estimatedTime;
  • aiContext 与 relatedRules:连接了 figure-figcaption、error-images、dimensions 三条规则,每条都附一句关联理由(如 fallback 图片同样需要 alt 文本);
  • prompts.check 高度具体:给出 5 条逐项审计指令,明确点名 <img>、alt 属性,甚至示例了要标记的坏值(alt="photo1.jpg"、alt="image");
  • prompts.fix 给出分步补救:按"信息图、装饰图、链接图、文字图、复杂图"五种场景给出不同的 alt 写法,复杂图建议 aria-describedby 或可见 caption;
  • prompts.explain 讲清为什么:关联 WCAG 2.1 SC 1.1.1,解释屏幕阅读器朗读 alt、坏 alt 与无 alt 无异、装饰图必须显式 alt="" 防止朗读文件名;
  • prompts.codeReview:为代码评审工作流描述应检查的资产、标记点与 DevTools 确认方式;
  • tldr 多条经验法则、tools(axe DevTools、WAVE、Lighthouse)与 resources(MDN、W3C WAI、WCAG 标准)齐全;
  • 正文以大量 ✅/❌ 代码块支撑,并以 ## Verification 收尾。

底层实现:打分与校验是怎么跑起来的

从源码看,score-rules.ts 的 scoreRule() 流程为:读取文件(并剔除空字节)→ 用 gray-matter 解析 frontmatter 与正文 → 以 body.match(/```/g) 数量除以 2 计算代码块数 → 按空白切分统计正文字数 → 调用 hasVerificationLikeSection、expectsThresholds、hasVisibleThresholds、analyzeRuleContract 做结构与契约分析 → 汇总维度得分与 A–F 等级。bodyDepth 的阈值档位是 300+ 词满分、150–299 词 6 分、60–149 词 3 分、60 词以下视为 stub 正文。

validate-rule-structure.ts 则先用 remark-parse + remark-mdx 构建 MDX 语法树,通过 unist-util-visit 提取标题节点(含行号、列号、偏移量),失败时退化为逐行正则扫描;随后按 Code Example(s) → Why It Matters → Verification 的索引关系生成问题列表,并对照基线文件决定是否放行。normalizeRuleStructureBody() 甚至支持自动修复——把验证别名标题改名为 Verification、把 Verification 之后的章节移到其之前。

结语

improve-rule 技能把"写好一条规则"从主观感受变成了一套可运行、可量化的工程流程:先 pnpm score:rules 跑分定位短板,再 pnpm validate:rule-structure 查结构契约,最后按 8 步清单逐项补齐 prompts、元数据、代码示例与 V2 条件章节。高质量规则最终会转化为高质量的 Claude Code 技能,让 Agent 能在正确的时机主动、精准地给出建议——这正是 Front-End Checklist 面向人类与 AI Agent 双受众的核心设计。完整的评分细则可继续阅读 skills/improve-rule/references/scoring-rubric.md,评分与校验实现分别在 scripts/rule-structure/score-rules.ts 与 scripts/rule-structure/validate-rule-structure.ts,契约分析核心逻辑位于 scripts/lib/rule-structure.ts。

登录后查看全文
Front-End-Checklist