Ratchet：让 AI 编程助手守规矩的「单向棘轮」——GitHub Trending 日榜精选

你有没有这种感觉：让 AI 帮你写代码，一开始它规规矩矩，写着写着就开始擅自加依赖、引入新库、写出过度设计的东西？你明明在 prompt 里写了「尽量用标准库」「不要加不必要的依赖」，但它好像从来不放在心上。

这就是 Ratchet 要解决的问题。它的名字来自机械中的「棘轮」——只能朝一个方向转，不能倒退。用在代码管理上就是：复杂度只许下降，不许上升。

项目上线不到 3 天就拿下 400+ Star，被 Claude Code、Codex 社区热烈讨论。它不是另一个 prompt 模板，而是一个真正会检查 AI 每次编辑的钩子工具。

🔧 核心机制：不止是「建议」，是真的在检查

传统的做法是在 system prompt 里写规则，让模型「自觉遵守」。问题是模型经常忽略这些规则，等 code review 发现的时候已经晚了。

Ratchet 的做法完全不同：它通过 PostToolUse 钩子，在 AI 每次编辑文件后实时检查。新增了依赖？写了冗余的 wrapper？重复造了标准库的轮子？它会立刻把发现问题注入回对话中，让 AI 当场修正：

you    给设置页加个日期选择器

agent   [安装 flatpickr，写个 wrapper 组件，加样式表]

hook   ratchet guard  ·  +71 -0 行 (净增 +71/150)  ·  2/3 新文件  ·  1/1 新依赖

       certain
         package.json:14       dep     发现新依赖 flatpickr
                                       说明为何不用标准库，否则移除
         src/DatePicker.jsx:4  native  日期选择器组件库
                                       <input type="date">
       likely
         src/DatePicker.jsx:22 wrapper  DatePicker 仅转发调用到 Flatpickr
                                       直接调用即可，删除 wrapper

agent   [回退改动，改用 <input type="date">]

📊 三大运行模式

日常开发用 guard，重构项目切 strict，探索原型时切 advise。在对话中随时用 /ratchet strict 切换，灵活实用。

🔍 八大检测器，精准捕获「过度设计」

每个发现都按可信度分级：certain（精确解析）→ likely（结构分析）→ heuristic（模式匹配）。只有 certain 级别的发现在 strict 模式下才会阻止编辑。这个设计让误报不会影响工作流，但真正的隐患不会被漏掉。

📈 真实的数据追踪——你的代码在变好吗？

Ratchet 不像那些只会说「帮你省了多少时间」的工具。它记录的是硬数据：

ratchet report

complexity trend, last 3 sessions
─────────────────────────────────

  ▁█▆  18 to 22 lines

when        mode   added  removed  deps  flagged  repo
2026-08-01  guard     +3       -0     0        0  18 new
2026-08-01  guard     +5       -0     1        1  24 ▲ 6
2026-08-01  guard     +0       -2     0        0  22 ▼ 2

mark  14 lines, 8 lines above the mark
      reason: initial mark

净增行数、新增依赖数、被标记的问题数……这些都是实际数字，没有任何水份。.ratchet/ledger.jsonl 会记录每个 session 的数据，ratchet report 以可视化趋势展示。

🚀 安装与使用（5 分钟上手）

安装

git clone https://github.com/0xwilliamortiz/ratchet.git
cd ratchet
npm install -g .

要求 Node 20+，Git 需在 PATH 中。

初始化项目

cd your-project
ratchet

一行命令搞定：自动注册钩子、建立基线、启动仪表窗口。重启你的 AI 编程助手即可生效。

在对话中使用

终端命令

🎯 适用场景

• AI 辅助开发的团队：防止 AI 在长 session 中逐渐引入不必要的复杂度
• 个人开发者：在用 Claude Code / Codex 等 AI 工具编程时，自动保持代码简洁
• 代码审查辅助：在 CI 中集成 ratchet audit，自动发现过度设计
• 重构项目：切换到 strict 模式，强制只减不增
• 教学场景：帮助新手理解什么是「过度设计」和「YAGNI 原则」

⚡ 为什么不直接用 prompt？

Prompt 是「建议」，Ratchet 是「执行」。Prompt 依赖模型自觉遵守，Ratchet 在模型行动之后检查结果。Prompt 可能被忽略，Ratchet 把发现问题直接注入回对话。两者互补，不是替代。

Ratchet 内置了一套经过优化的 ruleset，会自动注入到你的 agent 中。它的检测器和 prose 部分是分开的：检测器做 regex 和 git grep 能做到的事，prose 部分覆盖需要判断力的场景。

🔩 技术亮点

• 零外部依赖的检测引擎：基于 regex 和 git grep，不依赖 tree-sitter 或其他解析器，启动极快
• 符号索引缓存：冷启动几百毫秒，热启动约 4ms，上限 3000 个文件
• 净行数追踪：删 50 行就赚 50 行额度，鼓励真正的简化
• 指纹识别而非行号匹配：baseline 在代码格式化或移动后仍然有效
• 115 个测试用例：覆盖所有检测器和平台兼容性（含 Windows 路径转义等边界情况）
• Windows GUI 仪表盘：ratchetui.exe 实时显示 session 状态，通过 PowerShell Start-Process 异步启动

💡 设计哲学

「棘轮只朝一个方向转。代码复杂度要么下降，要么保持，除非有人故意反向转动并写下理由。」

这个设计哲学体现在两个关键机制上：

1. 基线化：ratchet baseline 接受现有代码为基线，不追究历史债务，只关注新增问题
2. 提高基线需要声明理由：node scripts/accept-mark.js 要求写一句话说明原因，避免悄悄增加复杂度

⚠️ 注意事项

• 检测器是 regex 和 git grep，不是类型检查器，会有误报。默认模式只报告不阻止，strict 模式才是可选的强制模式
• 测试文件默认不扫描（tests/、spec/ 等目录），避免标记测试夹具中的故意错误模式
• 没有 git 的仓库仍可使用 ruleset 和检测器，但基线、ledger 和 audit 功能需要 git init
• 阻止功能依赖宿主环境支持 PostToolUse 的 decision 字段

📋 项目信息

• 项目名称：Ratchet
• GitHub：github.com/0xwilliamortiz/ratchet
• 作者：0xwilliamortiz
• Stars：408+（3 天内）
• 许可证：MIT
• 语言：JavaScript（Node.js）
• 当前日榜排名：#3

🏁 总结

Ratchet 解决了一个被长期忽视的问题：AI 编程助手没有反馈回路。你告诉它「保持简洁」，但它写多写少、加不加依赖，全凭自觉。Ratchet 在每一次编辑后加上了一个自动检查步骤，让「保持简洁」从一个模糊的愿望变成了一个可测量、可执行的标准。

它不是要取代你的 prompt ruleset，而是弥补 promt 做不到的部分——实际测量代码变更。如果你在用 Claude Code、Codex 或任何支持 PostToolUse 钩子的 AI 编程工具，Ratchet 值得一试。