企业官网建设流程全解析

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 分如何由 Prompts（30 分）、Metadata（20 分）、Body Content（20 分）与 Bonus（10 分）四大板块构成，以及 A~F 等级阈值与 CI 强制执行的 50 分通过线。同时结合 评分器源码 与 improve-rule 技能说明，逐条对照实现细节，给出"把一条 stub 规则提升到合格线以上"的实操步骤与命令。读完本文，你将能够独立审查任意规则 MDX 文件、定位丢分维度，并写出同时服务于人类开发者和 AI Agent 的高质量规则。

一、评分总览：满分 80 分的架构与等级阈值

评分细则文档定义了pnpm score:rules评估每条 Front-End Checklist 规则的完整规范，最高分为 80 分，按四个板块分配：

评分完成后按总分映射到五个等级（Grade Thresholds）：

最低通过分数为 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.check（10 分）——审计指令

Stub 模式（自动检测）：

• "Verify if the project adheres to: [title]"
• "Ensure [title] is implemented correctly"
• 任何不足约 20 词、只是复述规则名称的提示词

好的 check 提示词示例（来自细则文档）：

"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."

这条示例的要点：命名了精确的 HTML 属性（alt）、明确了审计对象（所有<img>元素）、给出了具体的判定规则（缺失、包含 'image of'/'photo of'、装饰图非空 alt）。这正是 stub 与高质量提示词的本质区别。

prompts.fix（10 分）——修复指令

与 check 采用相同评分规则。好的 fix 提示词应给出逐步修复方案（step-by-step remediation），并且必须引用真实的 HTML/CSS/JS 语法——比如针对上述 alt 问题，应写明"为信息图补充描述性 alt、为装饰图设置alt=""、移除冗余的 'image of' 前缀"这样的具体操作。

prompts.explain（10 分）——解释指令

与 check 采用相同评分规则。好的 explain 提示词应该追问为什么（the why）——用户影响（user impact）、浏览器行为（browser behavior）、无障碍后果（accessibility consequences），而不是复述规则本身。例如解释"缺失 alt 的图片会被屏幕阅读器朗读为文件名"这类实质影响，而不是"alt 属性很重要"。

三、Metadata 维度（20 分）：让规则可被机器理解

元数据是规则 frontmatter 中的结构化字段，决定了规则能否被 AI Agent 精准触发与关联。

tldr（5 分）

每条 bullet 应该是独立的、可执行的规则要点（standalone, actionable rule of thumb），避免只是复述规则标题。

whyItMatters（5 分）

细则文档强调：应解释用户影响而非技术正确性。优先写 "Screen readers announce..."（屏幕阅读器会朗读……），而不是 "This improves accessibility"（这改善了无障碍性）这种空话。

aiContext（5 分）

一句以"Applies to..."或"Use when..."开头的话，告诉 AI Agent 何时激活这条技能。示例：

• "Applies to any HTML page with<img>or<picture>elements."
• "Use when reviewing form markup with<input>,<select>, or<textarea>elements."

从源码角度看，aiContext缺失时评分器会在报告中给出 "missing — add for better skill targeting" 的提示（见 score-rules.ts），说明它直接关系到规则作为 Claude Code 技能的触发准确性。

relatedRules（5 分）

每条条目结构为：{ slug: "rule-slug", reason: "one sentence why they're related" }。reason 必须是一句话说明关联原因，而非空字符串。

四、Body Content 维度（20 分）：正文是学习价值所在

codeExamples（10 分）

最佳实践是成对给出 ✅ 正确 / ❌ 错误示例，并使用真实世界的模式，而非琐碎的伪代码片段。评分器源码中的实现细节是统计```围栏出现次数后除以 2 得到代码块数量（见 score-rules.ts）。

bodyDepth（10 分）

源码按body.trim().split(/\s+/).length统计词数（score-rules.ts），不足 60 词被标记为 "stub body"，不足 150 词被标记为 "thin body"（score-rules.ts）。

五、Bonus 维度（10 分）：资源引用与代码审查

resources（5 分）

推荐优先选择：MDN 文档、WCAG 成功标准（success criteria）、浏览器兼容性表、权威文章。以仓库中一条高质量规则 alt-text 为例，其 frontmatter 同时声明了tools（axe DevTools、WAVE、Lighthouse）与resources（MDN alt 属性文档、W3C WAI 图片决策树、WCAG 2.1 SC 1.1.1 说明），这类"工具 + 权威文档"的组合正是该维度拿满分的形态。

prompts.codeReview（5 分）

用于代码审查工作流（code review workflows）。应描述审查 PR diff 时要看什么，而不仅是泛泛的审计指令——例如针对 alt 规则："Review the diff for newly added<img>tags; 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 分模型之上做了扩展，各维度分值如下：

• Prompts：prompts.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 Checks
• standardsVisibility：当规则涉及可测量指标或兼容性（measurable / compatibilitySensitive / standardsSensitive）时，要求正文出现可见阈值、## Standards、## Browser Support或## Support Notes之一

以阈值检测为例，expectsThresholds（rule-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检测正文中是否真的写入了数值型判据。

等级计算与报告

gradeFromScore（score-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 步改进清单，实操路径如下：

1. 先修 stub 提示词——它们合值 30 分，是性价比最高的修复项。check命名要审计的具体属性/模式，fix给出带代码片段的逐步修复，explain解释用户影响
2. 补aiContext——一句话："Applies to any HTML page with [X]" 或 "Use when reviewing [Y] in [Z] context"
3. 扩充tldr——至少 3 条 bullet，每条以具体规则要点结尾
4. 充实正文——每个概念成对给出 ✅ 正确 / ❌ 错误代码块
5. 加relatedRules——关联 2 条以上规则并写明关联原因
6. 加resources——MDN 文档、WCAG 成功标准、相关文章
7. 修复结构 lint——把Testing/Checklist类标题改为## Verification，可选指导内容放在Why It Matters与Verification之间，绝不在Verification之后放任何 H2
8. 按需补充契约清晰度——仅在规则类型确实需要时使用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.json，pnpm score:rules对应tsx scripts/rule-structure/score-rules.ts，pnpm 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