我所理解的代码风格最佳实践（4）：哪些项目约定值得写成 Lint
- JavaScript 代码怎样从调用点读下去
- Vue 组件与 composable 的职责边界
- Nuxt 页面、目录与自动导入
- 哪些项目约定值得写成 Lint（当前）
假设一个页面直接导入了另一个页面的私有 helper。页面今天能跑，等那个 helper 随原页面改名或删除，依赖才暴露出来。第一次看到时可以在 review 里解释。要是同类问题总出现，目录也已经能稳定区分哪些是公开入口、哪些是私有实现，就可以让编辑器在 import 那一行先给出提示。
看检查需要拿到什么信息
格式化交给 Prettier 一类的工具。对 import 的来源、调用参数的语法形态、变量绑定和作用域做判断，可以用 ESLint。检查样式源码的选择器和声明，可以用 Stylelint。若判断需要 TypeScript 的类型信息，要先确认检查器使用的是这个文件对应的项目配置。
需要遍历目录、核对资源或打开构建产物的检查，我通常单独写成脚本。比如确认插件的产物确实包含某个入口，需要读取产物，源码里有导出语句只是其中一条线索。数据是否在正确时机刷新，要由运行时测试覆盖。一个组件是否值得拆、两个状态是否同属一个业务对象，则要结合调用方和需求判断，放到 review 里更合适。
Skill、AGENTS.md 或项目文档可以记录判断依据与常见例外。比如解释为什么页面之间要通过公开模块共享能力。Lint 报告则应该说清楚哪一行跨过了边界，以及调用方可以从哪里取公共能力。只有规则实施所需的路径、别名和例外，才需要变成配置。
先把规则写窄，再决定是否阻断
以私有导入为例，第一版只检查能够解析、且明确跨越两个页面目录的 import。先找三类样本：应该告警的跨页面引用、同一页面内合法的相对导入、走公开入口的引用。如果仓库有别名、生成目录或暂时无法迁移的旧入口，再各挑一个样本检查。自动修复也要看能否证明替换前后行为一致。仅凭文件名相同，无法知道一个私有 helper 该换成哪个公开入口。
对存量项目，我通常先在受影响目录用 warn 跑一轮，逐条区分真实问题、规则误报和有期限的迁移例外。等规则边界稳定，再把明确会造成问题的范围设为 error。项目可以只在新增目录先阻断，旧目录按负责人逐步处理。
最后在项目的检查命令上试一次，确认开发者和 CI 看到的是同一套配置。ESLint 的 --max-warnings=0 会让 warning 也导致命令失败，所以规则配置写了 warn，还要看命令行实际怎样处理告警。ESLint CLI 的告警阈值说明
项目偏好可以按目录启用
命名偏好和正确性检查适合分别配置。一个维护多年的项目已经稳定使用 useXxx.ts，就可以关闭要求小写加横线的命名规则。检查 SSR 边界、错误导入或私有依赖时，仍应识别项目允许的文件名。规则分组能让项目选需要的约定，也能避免为了换一种文件命名，连带失去别的检查。
我会先看现有规则能不能表达这个约定，再决定是否新增实现。自定义规则的文档、配置和可编辑例子放在同一个维护入口，方便读者从诊断追到规则选项。想看实际项目怎样给 ESLint、Stylelint 和专项脚本分工，可以接着读这篇。把项目约定写成 ESLint 护栏的原始实践