Ratchet 是一个面向 AI 编程代理（尤其是 Claude Code）的代码复杂度“棘轮”工具。它通过 Claude Code 的 PostToolUse 等 hooks 监听代理对代码库的 Edit、MultiEdit、Write 操作，在代理仍处于同一会话时检测新增依赖、重复实现、手写标准库功能、无意义 wrapper、YAGNI 抽象、过大的新增代码量等问题，并把结果反馈给代理。核心目标不是靠提示词说服模型遵守规则，而是用可度量、可审计的机制持续压低或冻结代码复杂度。
适用领域
AI 编程代理治理 / Claude Code 插件 / Hooks / 代码质量控制 / 静态分析 / 依赖治理 / 复杂度预算 / 开发者工具 / 技术债控制 / LLM 工程化
配置难度
中等。个人开发者按 README 安装和运行并不复杂，但要在团队中落地，需要理解 Claude Code hooks、复杂度预算、baseline、strict/guard 模式差异，以及如何处理误报和例外。对于已在使用 Claude Code 的团队，上手难度较低；对于没有 AI 代理治理经验的团队，需要一定流程设计。
商业价值
对中国开发团队的价值主要体现在 AI Coding 质量治理和技术债控制。随着团队使用 Claude Code、Cursor、Copilot 类工具频率提高，AI 代理很容易为了完成任务而引入不必要依赖、过度抽象和大体量改动。Ratchet 提供了一个轻量但可审计的控制层：既能实时约束代理，又能留下复杂度趋势记录。它适合用于中长期维护型产品、SaaS 项目、内部平台和代码质量要求较高的团队。商业上，它可以降低代码审查压力、减少依赖供应链风险、避免 AI 生成代码造成的维护成本膨胀，并帮助团队把“少写代码、少加依赖、少造抽象”变成可执行的工程机制。
01
技术亮点
- 闭环治理：不是只给 AI 代理写规则，而是在每次编辑后检测代理是否真的遵守规则。
- 实时反馈：PostToolUse hook 会在同一会话内把检测结果返回给代理，便于代理立即修正。
- 复杂度预算清晰：按新增文件数、新增依赖数、净新增行数设置 guardrail。
- 支持多种模式：advise 只提示，guard 提示并预算警告，strict 可阻止确定性违规，off 完全关闭。
- baseline 机制实用：已有债务可以被接受，之后只关注新增债务，适合老项目渐进治理。
- 检测维度贴近 AI 代码常见问题：乱加依赖、重复造轮子、wrapper 泛滥、YAGNI 抽象、手写 email regex 等。
- 分级告警：certain、likely、heuristic，减少误报对开发者的打扰；strict 只阻止 certain。
- 账本与报告：.ratchet/ledger.jsonl 和 ratchet report 能展示复杂度趋势，而不是凭空估算收益。
- 提供 doctor、log 等自检工具，方便确认 hook 链路是否真的工作。
- MIT 许可证，适合个人和商业项目使用。
02
目标用户
- 使用 Claude Code 或类似 AI 编程代理的个人开发者
- 希望约束 AI 生成代码复杂度的工程团队
- 维护长期项目、担心 AI 代理引入过度工程的开发者
- 代码审查负责人 / Tech Lead
- 对依赖数量、代码体积、抽象层级有严格要求的团队
- 希望建立 AI Coding 审计记录的企业研发团队
03
配置要求
- 运行环境需要 Node.js >= 20。
- 建议安装 Git 并加入 PATH，以启用完整的度量、mark、ledger 和 audit 功能。
- 项目级配置文件为 .ratchet/config.json，建议提交到仓库。
- 可配置 mode：advise、guard、strict、off；默认是 guard。
- 可配置 budget，例如 newFiles、newDeps、addedLines。
- 可配置 ignore，用于忽略 migrations、generated 等目录。
- 可配置 scanTests，控制是否扫描测试文件。
- 用户级默认配置位于 ~/.config/ratchet/config.json。
- 支持环境变量 RATCHET_MODE、RATCHET_LOG、RATCHET_UI、RATCHET_SUBAGENT_MATCHER。
- 需要 Claude Code hook 机制；该工具定位明显偏向 Claude Code 生态。
- Windows UI 依赖仓库附带的 hooks/ratchetui.exe；README 中说明 UI 仅 Windows。
04
适用场景
- 在 AI 代理修改代码时实时发现新增依赖，并要求代理证明其必要性或改用标准库 / 平台能力
- 限制一次 AI 会话中新增文件数、新增依赖数和净新增代码行数
- 发现无意义的 wrapper 函数、单实现接口、重复函数命名等过度工程问题
- 为既有技术债建立 baseline，只对新增技术债报警
- 在 strict 模式下阻止确定性违规改动，例如新增不允许的依赖
- 生成复杂度趋势报告，追踪每次会话新增 / 删除代码、依赖和告警数量
- 在代码审查前执行 ratchet audit，扫描整个仓库中可裁剪的复杂度
- 为团队的 AI 编程流程建立可解释的审计日志和复杂度账本
05
部署与配置
- 确保本机安装 Node.js 20 或更高版本。
- 确保 Git 在 PATH 中；否则规则检测仍可运行，但 mark、ledger、audit 等基于仓库度量的功能不可用。
- 克隆仓库：git clone https://github.com/0xwilliamortiz/ratchet.git
- 进入目录：cd ratchet
- 全局安装：npm install -g .
- 进入需要被监控的项目目录：cd your-project
- 执行初始化：ratchet
- 工具会自动注册 hooks、初始化 .ratchet 目录、接受当前代码作为 baseline，并在 Windows 上尝试打开 UI 窗口。
- 重启 Claude Code / AI 代理，使其加载新的 hooks。
- 可选：运行 ratchet doctor 验证 hooks 是否能被真实触发。
- 可选：运行 npm test 验证项目自身测试。
06
风险与注意事项
- 生态绑定较强：README 明显围绕 Claude Code hooks 设计，对其他 AI 编程工具的适配可能有限。
- 规则是启发式与结构检测结合，likely 和 heuristic 级别仍可能出现误报或漏报。
- strict 模式可能阻断正常开发，特别是确实需要新增依赖或新增文件的任务，需要团队制定例外流程。
- 对大型仓库的扫描有上限和缓存策略，README 提到 symbol index capped at 3000 files，超大仓库可能覆盖不完整。
- Windows UI 是 exe 文件，企业环境可能需要额外安全审查；非 Windows 用户无法使用该窗口功能。
- 项目关注“减少复杂度”，如果团队不理解边界，可能误伤必要的安全、可访问性、错误处理和测试代码；虽然 README 已明确这些不应被预算限制。
- 需要开发者接受并维护 .ratchet 配置、baseline、mark 和 ledger，否则长期使用效果会下降。
- 当前安装方式是从源码 npm install -g .，相比成熟 npm 包分发，对普通团队的标准化部署略有门槛。
- 中文团队需要自行本地化规则说明、团队规范和提示输出，否则初期推广成本较高。
2026-08-07
第24名
新收录 · github_search
2026-08-06
第24名
新收录 · github_search
2026-08-05
第19名
新收录 · github_search
2026-08-04
第21名
新收录 · github_search
2026-08-03
第18名
新收录 · github_search
2026-08-02
第16名
新收录 · github_search
