内容
# 前端审查工具 🧐
[](https://opensource.org/licenses/MIT)
[](https://github.com/leonhoffmann86/frontend-critic/releases)
[](https://claude.ai/code)
一个 [Claude Code](https://claude.com/claude-code) 子代理，用于在真实浏览器中判断渲染的页面，并且必须提供截图证明页面是否正确。
## 问题
编码代理通常声称页面“看起来正确”、“与网站匹配”或“位于容器中”，而无需实际渲染页面。数据库中的语法干净的模板并不是实际渲染的页面。结果是：自信地报告的布局在人类打开它们时却被破坏。
`frontend-critic` 将这种声称转化为可验证的检查。它通过 Playwright 加载页面，与已知的良好参考页面进行比较，检查响应式断点和 JavaScript 控制台，并报告 **通过/失败，并附带截图证据** —— 将它**观察到的**内容与它仅仅**怀疑**的内容分开。
## 工作原理
```mermaid
graph LR
A["🎯 目标 URL"] --> B["browser_navigate"]
B --> C["a11y snapshot<br/>(结构，快速)"]
C --> D["截图<br/>(证据)"]
D --> E["调整大小<br/>375 / 768 / 1440"]
E --> F["控制台检查<br/>(JavaScript 错误)"]
F --> G{"参考页面？"}
G -- 是 --> H["加载参考页面,<br/>相同视口,<br/>比较"]
G -- 否 --> I
H --> I["报告:<br/>观察到的 / 怀疑的 / 不确定的"]
I --> J{"通过 | 失败"}
J -. "每个声明都附带<br/>截图路径" .-> I
```
三条铁律驱动每次运行：
1. **没有截图的结论无效。** 没有截图路径的“看起来不错”是被禁止的。
2. **与参考页面比较。** 加载相同视口的 sibling 页面；明确指出差异。
3. **将观察到的与怀疑的分开。** 发现结果报告为 `观察到的` （有证据）、`怀疑的` （指示，未验证）或 `不确定的` —— 永远不会合并为一个。
## 安装
1. 将 Playwright MCP 服务器添加到 Claude Code（前提条件）：
```sh
claude mcp add playwright npx @playwright/mcp@latest
```
2. 复制代理定义：
```sh
# 全局安装，所有项目使用
cp frontend-critic.md ~/.claude/agents/
# 或按项目安装
cp frontend-critic.md your-project/.claude/agents/
```
> **注意工具名称：** frontmatter 中的 `tools:` 列表使用 `@playwright/mcp` 注册的工具名称（`mcp__playwright__browser_*`）。如果您使用其他名称注册了 MCP 服务器，请相应地调整前缀 —— 否则代理将继承所有工具。
## 用法
Claude Code 会自动为“此页面是否正确渲染？”类型的任务选择代理，或者您可以显式调用它：
```
> 使用 frontend-critic 代理检查 http://localhost:3000/pricing 是否与参考页面 http://localhost:3000/about 匹配
```
## 示例输出
```
网址：http://localhost:3000/pricing
参考页面：http://localhost:3000/about
观察到的：
- [容器] 内容溢出站点容器，渲染全宽
（证据：./screenshots/pricing-1440.png）
- [页脚] 站点页脚存在且与参考页面相同
（证据：./screenshots/pricing-footer.png）
- [控制台] 1 个 JavaScript 错误：“Uncaught TypeError: prices is undefined”
怀疑的：
- 缺少页面模板赋值 — 参考页面使用盒子布局，目标页面没有。
不确定 / 无法验证的：
- 登录后的行为（无凭证可用）。
结论：失败
```
## 检查内容
- **容器/宽度** —— 内容在站点容器内，还是全宽溢出？
- **站点导航** —— 头部和页脚存在，无外来/未样式元素注入。
- **目标元素** —— 预期表单/按钮/链接存在 **且** 有样式。
- **控制台** —— JavaScript 错误。
- **响应式** —— 375 / 768 / 1440 像素。
- **A11y 快速检查** —— 字段标签、按钮对比度。
## 相关工具
作为 Claude Code 工具家族的一小部分：
- [team-sprint](https://github.com/leonhoffmann86/team-sprint) 🏃 — 自动规划 → 实现 → 审查链：每个 TODO 项目都经过完整的迷你冲刺，在隔离的工作树中，带有门禁和失败关闭审查，从不自动合并。
## 构建者
**Leon Hoffmann** — [leonhoffmann.net](https://leonhoffmann.net) ·
[github.com/leonhoffmann86](https://github.com/leonhoffmann86)
## 许可证
[MIT](LICENSE)
