AI 辅助：前端工程规范：从代码洁癖到团队可执行约束

AI 辅助前端工程规范从代码洁癖到团队可执行约束一、规范不是审美争论而是协作成本控制前端团队讨论规范时很容易滑向审美争论。单引号还是双引号文件名用 kebab 还是 camelCSS 类名怎么写。讨论本身没问题但如果规范只停留在偏好就很难长期执行。真正有价值的工程规范应该降低协作成本、减少线上风险、提升交付一致性。代码洁癖不是把代码写得像艺术品而是让代码在半年后还能被人安全修改。规范的目标也不是让每个人写出完全一样的代码而是让关键决策有统一底线。比如组件边界、状态管理、错误处理、性能预算、目录结构、测试要求这些比空格风格更重要。规范必须能自动执行。靠口头提醒维护规范最后一定会失效。能交给 Prettier 的不要拿到 Review 里吵。能交给 ESLint 的不要靠人肉检查。Review 应该留给架构、边界和业务风险。二、规范落地链路从文档到 CI 阻断flowchart TD A[团队规范文档] -- B[ESLint/Stylelint/Prettier] B -- C[本地 Git Hooks] C -- D[CI 检查] D -- E{是否通过} E -- 否 -- F[阻断合并] E -- 是 -- G[进入 Code Review] G -- H[架构与业务风险审查]这条链路强调分层。格式化问题在本地解决静态规则在 CI 解决架构问题在 Review 解决。不要把所有问题都塞进 Review。否则 Reviewer 会被低级噪声淹没真正重要的问题反而看不到。规范文档也要短。太长没人看。建议分成三层必须遵守、推荐实践、解释说明。必须遵守的内容要能被工具检查。推荐实践可以在 Review 中讨论。解释说明用于新成员理解背景。三、规则配置把底线写进工具下面是一组基础工程约束示例。{ scripts: { lint: eslint src --max-warnings0, stylelint: stylelint \src/**/*.{css,scss}\, typecheck: tsc --noEmit, test: vitest run }, lint-staged: { *.{ts,tsx}: [eslint --fix, prettier --write], *.{css,scss}: [stylelint --fix, prettier --write] } }--max-warnings0看起来严格但对长期项目有价值。warning 如果不处理很快会变成背景噪声。类型检查也必须进入 CI。TypeScript 如果只在编辑器里报错却不阻断构建就失去了工程约束的一半价值。组件规范也可以写成规则。比如禁止跨模块深层导入禁止业务页面直接引用组件内部文件禁止在渲染函数里创建复杂对象。部分规则可以用 ESLint 自定义插件实现。四、权衡分析规范太硬会降低局部效率严格规范会让某些临时改动变慢。比如一个紧急需求因为测试不全被 CI 阻断看起来很烦。但规范的价值就在于让风险显性化。可以有应急通道但应急通道必须记录原因并在事后补齐。规范也要分阶段推进。老项目一次性开启所有规则会产生大量历史问题团队很容易放弃。更好的方式是新代码严格旧代码逐步清理。可以先只检查变更文件再设定每周清理目标。不要把规范变成权力工具。规范服务工程质量不服务个人偏好。凡是不能解释收益的规则都应该谨慎加入。每条规则都应该回答它减少了哪类风险节省了哪类成本。生产落地补充从能跑到可维护从生产落地角度看这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束读者很难判断它能否放进真实系统。评估时建议先定义三类指标正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信稳定性指标回答失败时是否可控成本指标回答持续运行是否划算。三类指标要同时进入验收清单不能只用平均耗时或单次成功率证明方案有效。异常路径补充把失败当成接口契约下面的补充片段强调一个原则调用方必须得到稳定、可解释的错误而不是在超时、空输入或依赖失败时收到模糊结果。代码不追求覆盖所有业务细节而是展示输入校验、超时控制和错误封装这三个生产系统最容易遗漏的环节。type GuardedResultT { ok: true; data: T } | { ok: false; error: string }; async function runWithGuardT(task: () PromiseT, timeoutMs 3000): PromiseGuardedResultT { const controller new AbortController(); const timer setTimeout(() controller.abort(), timeoutMs); try { const data await task(); return { ok: true, data }; } catch (error) { const message error instanceof Error ? error.message : unknown error; return { ok: false, error: message }; } finally { clearTimeout(timer); } }五、总结前端工程规范的核心是可执行。格式交给 Prettier静态问题交给 ESLint 和 Stylelint类型交给 TypeScript质量底线交给 CI。Review 应该关注边界、风险和设计而不是空格和引号。落地建议先建立最小规范集格式化、Lint、类型检查、测试、目录边界。新代码严格执行旧代码分批治理。代码洁癖的正确打开方式不是挑刺而是把高频问题变成自动化约束。