Front-End Checklist 规则质量评分体系Scoring Rubric全解析从 80 分满分框架到 50 分通过线的提分实战【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导读本指南完整解析 Front-End Checklist 仓库中 规则质量评分细则skills/improve-rule/references/scoring-rubric.md的评分规范满分 80 分如何由 Prompts30 分、Metadata20 分、Body Content20 分与 Bonus10 分四大板块构成以及 A~F 等级阈值与 CI 强制执行的 50 分通过线。同时结合 评分器源码 与 improve-rule 技能说明逐条对照实现细节给出把一条 stub 规则提升到合格线以上的实操步骤与命令。读完本文你将能够独立审查任意规则 MDX 文件、定位丢分维度并写出同时服务于人类开发者和 AI Agent 的高质量规则。一、评分总览满分 80 分的架构与等级阈值评分细则文档定义了pnpm score:rules评估每条 Front-End Checklist 规则的完整规范最高分为 80 分按四个板块分配板块子项分值Prompts提示词prompts.check/prompts.fix/prompts.explain各 10 分共 30 分Metadata元数据tldr/whyItMatters/aiContext/relatedRules各 5 分共 20 分Body Content正文codeExamples/bodyDepth各 10 分共 20 分Bonus附加分resources/prompts.codeReview各 5 分共 10 分评分完成后按总分映射到五个等级Grade Thresholds等级分数区间占满分比例A68–80≥ 85%B56–67≥ 70%C44–55≥ 55%D32–43≥ 40%F0–31 40%最低通过分数为 50 分由pnpm score:rules在 CI 中强制执行——任何规则低于该线都会被标记为需要改进。注意 44–55 分区间C 级理论上包含 50 分附近但通过线被单独设定为 50意味着 50–55 分的 C 级规则勉强达标、44–49 分的 C 级规则则判为不通过。从 SKILL.md 看技能层面对该模型的表述为Base score: 100 with additional conditional V2 points基础 100 分 附加条件性 V2 分。这两者并不矛盾评分细则文档给出的是简化的 80 分核心模型而源码实现下文第五节在无条件维度上恰好合计 100 分并可叠加最多 12 分条件性维度与 SKILL.md 的描述一致。二、Prompts 维度30 分提示词是质量的第一道分水岭规则 frontmatter 中prompts对象包含三个核心提示词各占 10 分是单条规则分值最高的部分。prompts.check10 分——审计指令得分条件10存在且不是 stub3存在但匹配 stub 模式0缺失Stub 模式自动检测Verify if the project adheres to: [title]Ensure [title] is implemented correctly任何不足约 20 词、只是复述规则名称的提示词好的 check 提示词示例来自细则文档Audit allimgelements 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.这条示例的要点命名了精确的 HTML 属性alt、明确了审计对象所有img元素、给出了具体的判定规则缺失、包含 image of/photo of、装饰图非空 alt。这正是 stub 与高质量提示词的本质区别。prompts.fix10 分——修复指令与 check 采用相同评分规则。好的 fix 提示词应给出逐步修复方案step-by-step remediation并且必须引用真实的 HTML/CSS/JS 语法——比如针对上述 alt 问题应写明为信息图补充描述性 alt、为装饰图设置alt、移除冗余的 image of 前缀这样的具体操作。prompts.explain10 分——解释指令与 check 采用相同评分规则。好的 explain 提示词应该追问为什么the why——用户影响user impact、浏览器行为browser behavior、无障碍后果accessibility consequences而不是复述规则本身。例如解释缺失 alt 的图片会被屏幕阅读器朗读为文件名这类实质影响而不是alt 属性很重要。三、Metadata 维度20 分让规则可被机器理解元数据是规则 frontmatter 中的结构化字段决定了规则能否被 AI Agent 精准触发与关联。tldr5 分得分条件53 条及以上 bullet21–2 条 bullet0缺失每条 bullet 应该是独立的、可执行的规则要点standalone, actionable rule of thumb避免只是复述规则标题。whyItMatters5 分得分条件5存在且超过 40 字符2存在但 ≤ 40 字符0缺失细则文档强调应解释用户影响而非技术正确性。优先写 Screen readers announce...屏幕阅读器会朗读……而不是 This improves accessibility这改善了无障碍性这种空话。aiContext5 分得分条件5存在0缺失一句以Applies to...或Use when...开头的话告诉 AI Agent 何时激活这条技能。示例Applies to any HTML page withimgorpictureelements.Use when reviewing form markup withinput,select, ortextareaelements.从源码角度看aiContext缺失时评分器会在报告中给出 missing — add for better skill targeting 的提示见 score-rules.ts说明它直接关系到规则作为 Claude Code 技能的触发准确性。relatedRules5 分得分条件52 条及以上条目21 条条目0缺失每条条目结构为{ slug: rule-slug, reason: one sentence why theyre related }。reason 必须是一句话说明关联原因而非空字符串。四、Body Content 维度20 分正文是学习价值所在codeExamples10 分得分条件103 个及以上围栏代码块51–2 个代码块0无代码块最佳实践是成对给出 ✅ 正确 / ❌ 错误示例并使用真实世界的模式而非琐碎的伪代码片段。评分器源码中的实现细节是统计围栏出现次数后除以 2 得到代码块数量见 score-rules.ts。bodyDepth10 分得分条件10300 词5100–299 词230–99 词0 30 词视为 stub源码按body.trim().split(/\s/).length统计词数score-rules.ts不足 60 词被标记为 stub body不足 150 词被标记为 thin bodyscore-rules.ts。五、Bonus 维度10 分资源引用与代码审查resources5 分得分条件52 个及以上资源/工具21 个资源或工具0无推荐优先选择MDN 文档、WCAG 成功标准success criteria、浏览器兼容性表、权威文章。以仓库中一条高质量规则 alt-text 为例其 frontmatter 同时声明了toolsaxe DevTools、WAVE、Lighthouse与resourcesMDN alt 属性文档、W3C WAI 图片决策树、WCAG 2.1 SC 1.1.1 说明这类工具 权威文档的组合正是该维度拿满分的形态。prompts.codeReview5 分得分条件5存在且不是 stub0缺失或 stub用于代码审查工作流code review workflows。应描述审查 PR diff 时要看什么而不仅是泛泛的审计指令——例如针对 alt 规则Review the diff for newly addedimgtags; flag any img without alt, any alt starting with image of, and decorative images that received non-empty alt text.六、源码级实现score-rules.ts如何算出分数评分细则文档是规范scripts/rule-structure/score-rules.ts 是落地实现。对照源码可以发现几个细则文档未展开的机制Stub 模式的正则实现源码中的STUB_PATTERNS数组score-rules.ts实际检测以下五种模式const STUB_PATTERNS [ /^verify if the project adheres to/i, /^update the codebase to align with/i, /^explain the importance of/i, /^check if . follows best practices/i, /^ensure . is implemented correctly/i ]比细则文档列出的两条 stub 示例Verify if the project adheres to 与 Ensure ... is implemented correctly多出三条变体且均为大小写不敏感的锚定正则——任何以这些短语开头的提示词都会被判定为 stub。无条件维度合计 100 分从源码的维度数组score-rules.ts可以推断实际评分器在细则文档的 80 分模型之上做了扩展各维度分值如下Promptsprompts.check/prompts.fix/prompts.explain各 8 分共 24 分stub 仅得 2 分元数据与来源tldr4 分、whyItMatters4 分、aiContext6 分、relatedRules6 分、sources6 分、sourceQuality4 分、resourcesOrTools6 分、prompts.codeReview6 分共 42 分正文codeExamples10 分、bodyDepth10 分、verification8 分、thresholds6 分共 34 分以上无条件维度合计恰好100 分与 SKILL.md 中 Base score: 100 的表述吻合。条件性 V2 契约维度最多 12 分评分器还通过analyzeRuleContract实现在 scripts/lib/rule-structure.ts按规则特征动态启用三个条件性维度每个最多 4 分exceptions当规则被判定为易误报/需例外说明exceptionHeavy如 accessibility、security、seo 类别时要求存在## Exceptions小节verificationSplit当规则可自动化且需人工复核automationFriendly 且 manualReviewImportant时要求## Verification内同时有### Automated Checks与### Manual ChecksstandardsVisibility当规则涉及可测量指标或兼容性measurable / compatibilitySensitive / standardsSensitive时要求正文出现可见阈值、## Standards、## Browser Support或## Support Notes之一以阈值检测为例expectsThresholdsrule-structure.ts会在 slug 命中lcp|inp|cls|ttfb|budget|size|weight|contrast|zoom|tap|target|cache|header|status|score等关键词或 category 为performance/images时要求规则给出明确阈值hasVisibleThresholds则用正则/(?:?|?|||≤|≥)\s*\d|\b\d(?:\.\d)?\s?(?:ms|s|kb|mb|px|vw|vh|%|:1)\b/i检测正文中是否真的写入了数值型判据。等级计算与报告gradeFromScorescore-rules.ts按score / max的百分比划分等级阈值 0.85 / 0.7 / 0.55 / 0.4 与细则文档的 ≥85% / ≥70% / ≥55% / ≥40% 完全对应。CLI 支持--failing仅列出不合格规则、--json供 CI 消费、--min N自定义通过线默认通过线为 50当显式指定了.mdx文件且存在低于阈值的规则时进程以退出码 1 结束score-rules.ts这正是 CI 拦截不合格规则的机制。七、正文结构契约## Verification必须收尾评分并不只看 frontmatter正文的 H2 结构同样被校验。scripts/lib/rule-structure.ts 定义了规则正文的结构契约必备小节## Code Example(s)、## Why It Matters、## Verification见 rule-structure.ts顺序约束Code Example(s)必须出现在Why It Matters之前Why It Matters必须在Verification之前Verification必须是最后一个 H2 小节见 rule-structure.ts 的 issue 判定弃用别名Testing、Checklist、Audit Checklist、How to Verify、Testing Validation、Testing Monitoring等历史标题被视为Verification的弃用别名rule-structure.ts使用它们会触发deprecated-verification-heading问题可选小节白名单Best Practices、Common Mistakes、Framework Examples、Tools Validation、Thresholds、Exceptions、Browser Support、Support Notes、Standards、Implementation Notes等rule-structure.ts白名单外的自定义 H2 会被记为 unknownOptionalHeadings运行pnpm validate:rule-structure {file}对应 validate-rule-structure.ts即可检查这些结构约束。八、实战如何把一条规则提升到 50 分以上结合 improve-rule 技能 的 8 步改进清单实操路径如下先修 stub 提示词——它们合值 30 分是性价比最高的修复项。check命名要审计的具体属性/模式fix给出带代码片段的逐步修复explain解释用户影响补aiContext——一句话Applies to any HTML page with [X] 或 Use when reviewing [Y] in [Z] context扩充tldr——至少 3 条 bullet每条以具体规则要点结尾充实正文——每个概念成对给出 ✅ 正确 / ❌ 错误代码块加relatedRules——关联 2 条以上规则并写明关联原因加resources——MDN 文档、WCAG 成功标准、相关文章修复结构 lint——把Testing/Checklist类标题改为## Verification可选指导内容放在Why It Matters与Verification之间绝不在Verification之后放任何 H2按需补充契约清晰度——仅在规则类型确实需要时使用Exceptions、验证拆分、标准/浏览器支持说明可对照的高分范本是 alt-text 规则其 frontmatter 具备结构化relatedRules含 slug reason、多工具、多资源、编号分点的prompts.check是理解各项维度拿满的绝佳参照。常用命令速查# 为单条规则打分 pnpm score:rules packages/content/rules/en/{category}/{slug}.mdx # 只列出低于阈值的规则 pnpm score:rules --failing # 输出 JSON 供 CI 或其他工具消费 pnpm score:rules --json # 自定义最低分默认 50 pnpm score:rules --min 60 # 校验正文结构契约 pnpm validate:rule-structure packages/content/rules/en/{category}/{slug}.mdx命令注册于仓库根目录 package.jsonpnpm score:rules对应tsx scripts/rule-structure/score-rules.tspnpm validate:rule-structure对应tsx scripts/rule-structure/validate-rule-structure.ts完整的 CI 校验链还包括validate:guide-structure、validate:guides、validate:evidence等步骤。九、小结评分是质量代理最终服务人机双读者正如 SKILL.md 的 Explain 一节所强调的质量分数是规则对人与 Agent 都有用程度的代理指标。stub 提示词让 AI 只能给出泛泛指令缺代码示例的规则难以学习缺aiContext的规则不会在正确时机被技能系统触发缺relatedRules的规则则是知识图谱中的孤岛。高分规则最终会变成高质量的技能让 Claude 等 Agent 能够主动且精准地使用。掌握 scoring-rubric.md 的 80 分框架、理解 score-rules.ts 的实现细节再配合pnpm score:rules与pnpm validate:rule-structure两条命令形成打分 → 定位 → 修复 → 复测的闭环你就能系统性地把仓库中每一条规则打磨到 50 分通过线以上并稳步向 A 级≥85%迈进。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考