如何推动团队代码规范落地

代码规范写了没人遵守，比没有规范更糟糕——它成了摆设。

为什么规范推不动

1. 太复杂 — 200 页的规范文档没人看
2. 没工具 — 靠人工 code review 检查格式
3. 没强制 — 可以 skip，那就没人遵守
4. 没反馈 — 违反了也没后果

四步落地法

第一步：工具先行

不要先写规范文档，先配工具：

# 一键配置
pnpm add -D @antfu/eslint-config husky lint-staged

// package.json
{
  "scripts": {
    "lint": "eslint . --fix",
    "format": "prettier --write ."
  },
  "lint-staged": {
    "*.{ts,vue}": ["eslint --fix", "prettier --write"]
  }
}

工具能自动检查和修复的，不用写进规范。

第二步：Git 钩子强制

# .husky/pre-commit
pnpm exec lint-staged

提交前自动检查，不过就不能提交。这是最关键的一步。

第三步：Code Review 文化

工具检查格式，人检查逻辑。Code Review 时关注：

• 代码意图是否清晰
• 边界条件是否处理
• 性能是否有问题
• 是否有更简洁的写法

不要在 Review 里纠结格式——那是工具的事。

第四步：持续维护

// 定期检查
// 1. 每月跑一次全量 lint
// 2. 发现新问题加规则
// 3. 过时的规则及时移除

// package.json
{
  "scripts": {
    "lint:full": "eslint . --fix --max-warnings 0"
  }
}

规范文档该写什么

只写工具无法自动检查的规则：

• 命名约定（变量、函数、组件）
• 文件组织（目录结构、导入顺序）
• 业务规则（错误处理、状态管理方式）
• 禁止事项（不要用 any、不要用 var）

工具能检查的（格式、语法）不用写。

常见阻力及应对

阻力	应对
「太麻烦了」	工具自动修复，不用手动改
「我不习惯」	给一周适应期，之后强制
「这个规则不合理」	收集反馈，适当调整
「赶进度没时间」	lint 自动修复只要 1 秒

核心原则

自动化 > 文档 > 口头约定

能自动化的绝不要靠人记，能用工具检查的绝不要靠 Review。