反模式技能——交付真实代码,而非装饰品
本技能用于检测并阻止最常见的反模式,这些反模式会让软件显得未完成或不专业。
禁止的反模式(零容忍)
UI/UX 反模式
❌ 禁止:
- “即将推出”(Coming Soon)部分或标签
- 非功能性按钮(必须可工作或移除)
- 不提交到任何地方的表单
- 生产组件中的硬编码假数据
- 假装是动态表格的静态表格
- 指向无处的链接(href="#")
- “建设中”(Under Construction)横幅
- 永久设置为 false 的功能开关
- 没有明确说明就被禁用的输入框
- 没有有用提示消息的空状态
- 实际上不分页的分页
- 实际上不搜索的搜索栏
- 返回相同结果的筛选器
- 当用户要求“一个网站”时只提供单个落地页(必须是多页面)
- 未定义配色方案前就编写 CSS
- 没有文档化设计系统的随机十六进制颜色
- 页面间颜色不一致(不同的蓝色、不同的间距)
- 网站中任何地方使用 EMOJI(请使用 Lucide/Heroicons/Phosphor 的 SVG 图标)
- 区块相互接触(内容块之间没有间距)
- 页脚直接贴在上方区块上(没有呼吸空间)
- 导航超过 7 个顶级项(杂乱、令人不知所措)
- 服务页面没有单独的详情页(只有 /services,没有 /services/web-design)
- 产品页面没有单独的详情页(只有 /products,没有 /products/[slug])
- 通用的服务描述(每个服务只有 2-3 行描述是不够的)
✅ 要求:
- 每个可见按钮都触发真实的事件处理器,否则删除
- 每个表单都有连接到 API 调用的真实 onSubmit
- 每个列表都从真实数据源加载,并展示加载状态
- 每个链接都导航到真实目的地
- 空状态解释原因并建议下一步操作
- 错误状态显示来自服务器的真实错误消息
- 加载状态在真正异步操作期间出现
- 多页面网站,包含独立路由(首页、关于、服务、联系、产品)
- 专业的 6 色调色板(--color-primary、secondary、accent、bg、surface、text)
- 所有页面一致的设计系统
- 零 emoji —— 使用 SVG 图标(Lucide、Heroicons、Phosphor)
- 区块间距:区块之间最小 80px 内边距
- 页脚:最小 128px 顶部内边距(绝不紧贴上方内容)
- 导航:最多 7 项,分组使用下拉菜单,二级链接放在页脚
- 服务:列表页 + 每个服务的独立详情页
- 产品:列表页 + 每个产品的独立详情页
- 每个服务详情应包含:描述、流程、交付物、定价、常见问题、行动号召
- 每个产品详情应包含:图库、规格、定价、评论、相关产品
网站架构反模式
❌ 禁止(当用户说“构建一个网站”时):
- 仅创建 index.html 一个文件
- 将所有内容放在一个可滚动的页面中
- 使用锚点链接(#about、#services)代替独立页面
- 当它只是一个落地页时却称之为“网站”
- 区块/页面之间没有导航菜单
- 页面之间没有共享的页眉/页脚
- 每个页面没有唯一的元标题/描述
✅ 要求:
- 每个部分都有独立的路由/页面(例如 /about、/services、/contact)
- 链接所有页面的导航菜单
- 共享的页眉 + 页脚组件
- 每个页面有唯一的 <title> 和 <meta description>
- 所有页面一致的调色板和排版
- 任何“网站”请求最少 5 个页面(首页、关于、服务、产品/作品集、联系)
代码反模式
❌ 禁止:
- return []; // TODO: implement
- throw new Error('Not implemented');
- // placeholder
- 假装是 API 响应的硬编码数组
- 空体的函数
- 默默吞噬错误的 catch 块
- 生产环境中的注释掉的代码
- 没有命名常量的幻数
- 复制粘贴的代码(违反 DRY 原则)
- 上帝函数(超过 100 行)
- 深度嵌套的回调(超过 3 层)
- 循环中的 N+1 数据库查询
✅ 要求:
- 每个函数都有真实的、可工作的实现
- 每个错误都得到正确处理并提供用户反馈
- 常量已命名并记录
- 代码遵循 DRY 原则——提取共享逻辑
- 函数聚焦且不超过 40 行
N+1 查询检测
❌ 禁止(N+1):
// 这为每个用户发起 1 次查询 = N+1 问题
for (const user of users) {
const orders = await db.query('SELECT * FROM orders WHERE user_id = ?', [user.id]);
}
✅ 要求(批量):
// 这总共只发起 1 次查询
const userIds = users.map(u => u.id);
const orders = await db.query(
'SELECT * FROM orders WHERE user_id IN (?)',
[userIds]
);
// 然后在内存中分组
const ordersByUser = groupBy(orders, 'user_id');
SQL 反模式
❌ 禁止:
SELECT * FROM users -- 禁止 SELECT *
WHERE name LIKE '%" + input + "%' -- SQL 注入
ORDER BY RAND() -- 性能杀手
HAVING COUNT(*) > 0 -- 请改用 WHERE
WHERE YEAR(created_at) = 2024 -- 破坏索引使用
✅ 要求:
SELECT id, name, email FROM users -- 显式指定列
WHERE name LIKE ? -- 参数化查询
ORDER BY id DESC LIMIT 20 -- 确定性排序
WHERE created_at >= '2024-01-01' -- 对索引友好
AND created_at < '2025-01-01'
验证清单
在任何交付物被标记为完成之前:
通用
- 没有“即将推出”或“建设中”字样
- 所有按钮都可用或被移除
- 所有表单都提交到真实端点
- 所有列表从真实数据源加载
- 生产路径中没有硬编码的演示数据
- 没有 N+1 查询(检查每个循环中的查询)
- 没有不带问题引用的 TODO 注释
- 错误状态处理真实错误
- 加载状态在真实操作期间显示
设计与 UI 反模式
- 网站任何地方零 emoji(仅使用 SVG 图标)
- 区块之间最小 80px 内边距(不接触)
- 页脚最小 128px 顶部内边距(不紧贴内容)
- 主导航最多 7 个顶级项
- 二级链接放在页脚,而非主导航
- 服务有独立的详情页(不仅仅是列表页)
- 产品有独立的详情页(不仅仅是列表页)
- 每个服务详情包含:描述、流程、交付物、行动号召
- 每个产品详情包含:图库、规格、定价、评论
- 交替的区块背景以增强视觉区分
SEO 反模式(适用于网站项目)
- 没有缺少唯一 和 的页面
- 没有缺少 Open Graph 标签(og:title、og:description、og:image)的页面
- 没有缺少 JSON-LD 结构化数据(
<script type="application/ld+json">)的页面 - 没有非首页页面缺少 BreadcrumbList 架构
- 没有重复的 JSON-LD 块(请使用
@id引用代替) - 没有缺少
robots.txt或sitemap.xml - 没有图片缺少
alt文本 - 没有页面缺少 canonical URL
- 没有缺少
<html lang="xx">属性 - 没有页面包含多个
<h1>
何时不宜使用
在以下情况下请勿使用此技能:
- 执行通用代码质量审查(请使用 code-review 技能进行更广泛的分析)
- 设计数据库模式(请使用 database-design 技能进行模式规划)
- 编写应用业务逻辑(请使用 domain-driven 技能处理完整模块)
- 审查 API 端点实现(请使用 api-design 技能进行端点模式审查)
- 执行安全审计(请使用 security-auditor 技能进行漏洞分析)
- 分析部署配置(请使用 deployment 技能处理 CI/CD 管道)
- 审查 git 工作流或版本控制(请使用 git-workflow 技能处理分支/提交)
- 编写 SQL 查询(请使用 sql-best-practices 技能进行查询优化)
- 设计多页面网站布局(请使用 design-system 技能进行专业 UI/UX 设计)
- 审查现有代码以进行重构(请使用 refactoring 技能以确保安全转换)