Straitjacket：用规则约束编码智能体的 TypeScript 模板

一个 TypeScript 模板，让编码 agent 无法绕开规则。 TypeScript 7 · oxlint · Vitest · Stryker · aube · prek 编码 agent 速度快、不知疲倦，而且非常擅长“看起来做完了”。一旦放任不管，它们就会：

straitjacket 会让上述每一种行为都在你的机器上、在提交落地之前大声失败。 它自带工具链、门禁以及 agent 规则和技能——几乎不含应用代码。

当 agent 试图…… ……这个会拦住它 掩盖一条 lint 发现 oxlint-disable 被禁止；未使用的指令本身就是错误 提交没有断言的测试，或使用 it.only oxlint 的 vitest 规则会检查测试本身 覆盖一行代码却没有真正测试它 Stryker 变异测试，在 pre-push 时运行 悄悄放宽上限或阈值 漂移守卫会将每个引用的数字与其配置进行核对 让文档与代码脱节 对模块映射、sample.env 和规则镜像的漂移守卫 永久搁置一个 TODO 未注明日期或已过期的延期会让门禁失败 安装新发布、带脚本或来路不明的包 30 天发布年龄门禁、禁用脚本、OSV 恶意包检查 写出 300 行的函数 每个函数 120 行，复杂度 10，深度 3 直接使用 process.env 或 console.log 两者都是 lint 错误；env 和 logger 才是出路 提交密钥 gitleaks 在 pre-push 时扫描整个历史 和任何 straitjacket 一样，只有扣好搭扣它才管用。--no-verify 会直接绕过两个 git hook——见“门禁是两个 git hook”。

mise install # Node、aube、prek、gitleaks、osv-scanner aube install --ignore-scripts aube run hooks:install # git hook；没有东西会替你安装它们 aube run check

aube run hooks:install 是单独一步，这是有意为之。没有任何东西会在安装依赖时顺带安装 git hook——那会是一个生命周期脚本，而安装是在禁用脚本的情况下运行的。没有这一步，hook 永远不会运行。 ls .git/hooks 应该显示 pre-commit、commit-msg 和 pre-push；如果某个提交带着失败的检查顺利通过，就检查这里。

开发工具 工具 作用 mise 固定 Node、aube、prek、gitleaks 和 osv-scanner；mise.lock 保存每次下载的校验和 aube 包管理器，处于偏执模式，其守卫配置在 aube-workspace.yaml 中（见下文） TypeScript 7 strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes + verbatimModuleSyntax，ES2022 Vitest .test.ts 与代码放在一起；覆盖率阈值；.integration.test.ts 被排除在外 Stryker 变异测试——询问测试是否本会失败，而不只是它是否运行了那一行 oxlint 类型感知（通过 oxlint-tsgolint），沿用 typescript-eslint 的 strict-type-checked + 上限 oxlint vitest 检查测试本身：无断言、聚焦、禁用、条件 expect Prettier 格式化，由门禁检查；oxlint 不启用格式化规则 knip 未使用的文件、导出和依赖——在默认模式和生产模式下都检查 jscpd 复制粘贴检测，阈值为 0% dependency-cruiser 循环导入、孤儿模块以及你的模块边界 zod src/env.ts——环境在启动时解析并校验 pino src/logger.ts——结构化日志；no-console 是 lint 错误 commitlint Conventional Commits，在 commit-msg 时运行 prek git hook：pre-commit 运行 aube run check；pre-push 运行较慢的那一半 gitleaks 对整个历史进行密钥扫描，在 pre-push 时运行 aube audit 锁文件漏洞检查，在 pre-push 时运行，带经过审查的忽略列表 osv-scanner 第二道漏洞扫描，加上 OSV 的恶意包公告，在 pre-push 时运行

Agent 配置 AGENTS.md # 跨工具入口；一个指针，由测试守卫 agent_rules/ # 规则——唯一真实副本 ├── 01-overview.md 这个项目是什么（待填写） ├── 02-coding-guidelines.md 内部风格 + aube run check 规则 ├── 03-code-walkthrough.md agent 用来导航的地图 └── 04-committing.md 提交信息约定 .claude/rules -> agent_rules # 符号链接，让每个助手读同一份文件 .clinerules -> agent_rules .kilocode/rules-> agent_rules .claude/settings.json # 只读命令白名单，减少权限提示 .claude/hooks/ └── format-edited-file.sh # PostToolUse：每次编辑后运行 oxlint --fix + prettier .claude/skills/ ├── code-audit/ # 结构审计：命名、位置、内聚性 ├── add-dependency/ # star 检查、成熟度窗口、禁用脚本 └── write-tests/ # 内部测试约定，以及在变异测试中存活

只编辑 agent_rules/。三个规则路径都是指向它的符号链接。 AGENTS.md 是例外：文件不能符号链接到目录，所以它是手写的、指向 agent_rules/ 的指针。src/driftGuard.test.ts 断言它仍然列出每个规则文件且不列出其他文件。

编辑时 hook 是这里杠杆率最高的部分。aube run check 只在任务完成后才报告机械性问题，到那时修复会变成跨多个文件的 diff，与真正需要关注的问题争夺注意力。在编辑发生的那一刻修复格式和可自动修复的 lint，能让 check 的输出只关注需要判断的事情。

该 hook 直接调用 node_modules/.bin，从不经过包管理器。包管理器的 exec 可能判断依赖树已过期，并在运行前先安装——而这是在一个每次编辑都会触发的 hook 中，且无人看管。

命令 作用 aube run check 门禁——typecheck、format、lint、knip、jscpd、depcruise、test aube run fix oxlint 自动修复 + Prettier 写入。在阅读错误前先运行这个。 aube run typecheck tsc --noEmit（TypeScript 7） aube run lint oxlint，类型感知；警告即失败 aube run format Prettier，写入 aube test / test:watch Vitest aube run test:coverage Vitest，强制执行阈值 aube run test:mutation Stryker——变异得分，由 stryker.conf.mjs 门禁 aube run build 生成带声明的 dist/ aube run check:vulnerabilities aube audit，应用经过审查的忽略列表 aube run scan:osv osv-scanner 扫描 aube-lock.yaml，使用同一忽略列表 aube run scan:secrets gitleaks 扫描整个 git 历史 aube run hooks:install 安装 prek git hook（全新克隆后需要）

门禁是两个 git hook 没有 CI。整个门禁都是本地的：

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）