node-lint

node-lint

配置 lint 和格式化工具，让它们发现真正的问题，而不是互相冲突。 此技能可解决以下问题：模型编写当前 ESLint 主版本已无法加载的旧版 .eslintrc 配置、混用两个格式化工具、声称 Biome 可以替代类型检查，以及迁移时重置有意定制的规则。

不适用场景

• Next.js 应用 → nextjs-quality 负责 eslint-config-next 和 RSC 规则。
• 类型检查 / tsconfig → node-typescript（Biome 的类型感知规则不能替代 tsc——绝不能声称可以替代）。
• 测试设置 → node-testing；编写 CI 工作流 → node-ci。

工作流

1. 先检测，再选择。 检查包管理器（锁文件）、现有配置 （.eslintrc*、eslint.config.*、biome.json*、.prettierrc*）、框架 和插件需求（a11y、导入、框架专用）。插件需求决定工具：阅读 references/lint-playbook.md 中的决策表。
   • Biome — 使用一个工具完成 lint 和格式化；这是对没有特殊插件需求的 TS 库 / 应用而言最快的方案。
   • ESLint（仅限 flat config——现代主版本不会加载 eslintrc）+ Prettier — 需要使用插件生态系统时采用。
   • 绝不使用两个格式化工具；绝不在使用格式化工具的同时启用 ESLint 风格规则。
2. 根据操作手册的起始配置块编写明确的配置——使用完整配置，不依赖随版本变化的默认值。为 package.json 配置脚本（lint、format、lint:fix），供 CI 使用时加上 --max-warnings=0。
3. 迁移（存在旧设置时）：遵循操作手册中的流程——使用官方 flat-config 迁移工具或 biome migrate eslint。比较生效的规则集；保留有意定制的规则；先在整个代码库上运行并分类处理新发现的问题，再删除旧配置。
4. 验证：

   python3 "${CLAUDE_SKILL_DIR}/scripts/check_lint_setup.py"
   

   并在仓库上运行所选工具，确保没有问题（npx biome check . 或 npx eslint . --max-warnings=0）。
5. 报告所选工具的原因、明确禁用的规则，以及 CI 应在哪里调用这些脚本（将工作流接线工作交由 node-ci 处理）。

输出规范

一个 lint 工具 + 一个格式化工具，明确且已提交的配置，已接入的脚本；当前代码库中没有错误 / 警告（或附有问题分类清单）；没有遗留的旧配置文件；注明编辑器设置。

注意事项

• 在当前 ESLint 主版本中，flat config 会相对于每个被 lint 文件所在的目录解析——monorepo 中的各个包可以拥有自己的配置层。
• biome migrate eslint 只会映射能够处理的规则；没有 Biome 对应项的规则会被静默丢弃——务必进行比较并列出这些规则。
• 对所有内容进行版本核验：工具主版本更新很快；操作手册会标出使用时必须对照官方文档重新核验的说明。
• 只通过禁用规则来让 lint 通过，属于失败——应通过修复问题来调整工具输出。

文件

• references/lint-playbook.md — 决策表、明确的起始配置、迁移流程和调优规范。
• scripts/check_lint_setup.py — 确定性健全性检查（仅使用一个格式化工具、不同时存在旧配置和 flat config、脚本已接入）；违规时以非零状态码退出。