按理说，

引子这方面。一个吃灰三年的项目被重新盘活

写这篇博客的由头有点特别。

我有一个叫 front-end-checklist 的老项目，年初在公司做 Code Review 的时候顺手整理出来的。那会儿评审新同学的代码，总是在重复一样的话：“这里没做 XSS 转义”“useEffect 里有竞态”“label 没和 input 关联”。后来干脆把这些反复出现的问题写成清单，用 Jekyll 挂在 GitHub Pages 上。

接下来它就一直在那儿积灰。只有一次提交，只有一次到了 2021 年 12 月也还没动过。说起来，

——晚上，我本来只想顺手改一下清单里过时的条目。结果一头扎进 Claude Code，两小时做了 5 次提交把这个静态页面彻底改造了一遍。

真正让我想写这篇文章的，不是“AI 让我写代码变快”。快是肯定快，但这次改造最终落到了一件我之前没想过的事情上——一份静态文档。换了个交付形式，才真正开始被用起来。

清单本身的观点是，三年沉淀下来的 80 条检查项

它不是 ESLint 能查的那种风格规则。而是 Code Review 时需要结合业务和上下文判断的问题。目前一共 20 个分组、80 条检查项：

命名规范 数据与类型 函数设计 状态管理 控制流异步处理
数据请求 UI 与渲染 样式与响应式 路由与权限性能
安全与健壮性 表单与交互 错误处理 测试无障碍访问 使用者体验
代码质量 工程化 国际化日志与监控 依赖管理
浏览器兼容 文档与协作 PR 自检

随便挑几条看看：

这些不是靠格式化、类型推导或者简单 AST 规则就能稳定抓出来的问题。它们往往来自真实线上事故、返工、误解和交接成本。以前这些经验只能靠人去记，记不住就会在别的项目里重新踩一次。

从痛点来看，清单挂在网上。却从未进入工作流

User Pain Point #1 — 信息碎片化：团队里每个人都有自己的笔记本、GitHub Wiki 或者 Google Doc，但没有统一入口。于是即使有价值的检查项，也只能等到有人主动去搜才会被发现。

User Pain Point #2 — 主动记忆成本高：做 PR 时我知道清单里有条“处理并发请求的竞态”，但真的会每次都打开页面对照吗？答案是否定的，同事更不会。新人入职时我会把链接丢给他们，他们收藏，接下来就再也不打开了。

User Pain Point #3 — 缺少即时提醒：在 Code Review 场景里你必须先意识到自己可能漏了什么才能去查文档。而大多数遗漏恰恰是你根本没有意识到自己遗漏了什么。

I tried a few mitigations:

• 可搜索网页：搜索前提是你已经知道关键词，但 XSS、竞态、状态错位这类问题经常是因为根本不知道该搜什么。
• 勾选进度追踪：The moment I added checkboxes,doc turned into a “fill‑in‑‑form” task and adoption dropped.

The core issue isn’t that document isn’t flashy enough;it’s that “pull‑to‑read” docs rarely become part of anyone’s workflow.

转折的观点是，把清单变成 AI 的上下文

的 Skill 机制改变了这件事。

Simplified: a Skill is a piece of documentation that AI reads before executing a task. When you mention a trigger word in conversation。AI loads Skill and follows its instructions.

Skill 中定义的逻辑

1. 仅在使用者明确请求时触发：/frontend-checklist,“按前端清单 review”,“按 checklist 检查这段代码”。使用者没提，它不会自行扫描代码。
2. 确认检查范围：If a file is specified,only that file is examined;其实，if “review PR” is said。use git diff;orwise ask for clarification instead of scanning whole repo.
3. 按语言选择清单：The Skill auto‑selects Chinese or English version based on query language.
4. If an item does not apply,it stays silent.
5. Securitiy / data loss / race condition / memory leak first;老实说，naming style later.
6. This lets developers jump directly to offending line.

A developer no longer needs to memorize all 80 items—just remember re’s an entry point . When you type that command in your IDE or chat window。AI pulls checklist toger with your current diff and reports only hits with file paths and line numbers. The mental load drops from “remembering 80 rules” to “knowing re’s a shortcut”.

一个真实跑出来的 review 示例

坏例子代码

export function CommentList {
const = useState;const = useState;useEffect => {
fetch
.n => r.json)
.n => {
setList;})，},);const highlight = => {
if return text;return text.replace,'' + kw + '');}，return (




{list.map => (

 eval}>
{c.author.name}




))}

);不过，}

The code compiles and even passes most linters。but when fed into Skill it returns **7 命中**:

安全与健壮性

• #line 23:  直接渲染外部 tag tip ,存在 XSS 风险。建议默认文本渲染，若必须富文本，请使用  消毒后再渲染。
• #line 13:  用字符串拼接 HTML 再  注入，一样缺乏转义。建议改为基于  分段渲染，将匹配片段包裹  而非注入 raw HTML。
• #line 21:  把后端返回的字符串当代码执行，相当于任意脚本执行权交给接口数据。建议删除 eval，用映射表或组件回调代替。

数据请求

• #line 6:  变化时发起新请求但未取消旧请求，旧响应可能覆盖新数据。推荐使用  或 cleanup 标志进行取消。

UI 与渲染

• : 使用数组下标作为 key，会导致列表增删时状态错位。请改用业务唯一 ID（如 )。

无障碍

• : 缺少 /关联；说起来，缺少 alt 属性。

A generic AI review would likely output vague suggestions like “add error handling”. ESLint would only catch syntax errors or missing dependencies. **The Skill shines because it applies a concrete checklist – turning abstract best practices into actionable line‑by‑line feedback**.

I also ran or showcase cases: a user profile page triggered **6 条**;a registration form hit **5 条** . All are pieces of code that look “good enough” but become hidden traps once shipped.

怎么用

curl -fsSL https://github.com/wsafight/front-end-checklist/releases/latest/download/install.sh \
| sh -s -- claude

The script registers Skill for Claude. Afterwards you can simply type:

• `/frontend-checklist` – triggers a full repository scan .
• `按前端清单 review 我这个 PR` – automatically runs against `git diff`.
• `review this file src/components/Button.tsx` – focuses on a single file.

The same skill works with Kiro。Cursor or Codex – just replace command suffix accordingly.

The checklist remains bilingual. If you ask in English you’ll get English version automatically.

让沉睡三年的文档活起来

A two‑hour overhaul sounds like clickbait until you see what really happened: **A static checklist that sat untouched for three years suddenly became an active teammate**. The content didn’t change – still those ~80 vetted rules – but its delivery did. By embedding it into an AI workflow we turned passive documentation into proactive guidance.

If you have similar “valuable but unused” docs in your organization—architecture decisions,security policies,onboarding guides—spend an evening wiring m into an AI Skill. Turn knowledge hoards into instant assistants and watch your team’s productivity—and code quality—take off.

---

— 夜 🌙 于2026年8月12日撰稿 .

。

---