Front-End Checklist 规则质量提升实战指南:用 improve-rule 技能打磨可被 Agent 引用的规则库
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 分):
tldr4 分、whyItMatters4 分、aiContext6 分、relatedRules6 分、sources6 分、sourceQuality4 分、resourcesOrTools6 分、prompts.codeReview6 分; - 正文内容组(共 34 分):
codeExamples10 分、bodyDepth10 分、verification8 分、thresholds6 分; - 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-presentaltattributes. 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 实现):
- 任何 H2 之前的引言段落(intro paragraph);
## Code Example或## Code Examples;## Why It Matters;- 可选指导章节(guidance sections);
- 最后的
## 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 分),应最先处理:
- 先修 Stub 提示词——
check点名要审计的属性/模式,fix给出带代码片段的分步补救,explain解释用户影响而非技术细节; - 补充
aiContext——一句话即可:"Applies to any HTML page with [X]" 或 "Use when reviewing [Y] in [Z] context",这是技能在正确时机触发的关键; - 补全/扩充
tldr——至少 3 条,每条都以可执行的经验法则收尾,避免复述规则名; - 丰富正文——为每个概念同时提供 ✅ 好示例与 ❌ 坏示例的代码块;
- 添加
relatedRules——至少 2 对 "slug + reason",说明规则间的联系; - 添加
resources——MDN 文档、WCAG 成功标准、权威文章(注意:正文中链接应融入自然语句,不要写孤立的See also行,否则触发inline-metadata-prose问题); - 修复结构 lint 问题——把
Testing/Checklist风格的结尾标题统一改为## Verification,指导章节放在Why It Matters与Verification之间,且 Verification 之后不得再出现 H2; - 按需补充契约清晰度——
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。