为什么值得关注

它把代理规则从只靠提示词的建议变为强制的反馈闭环：编辑发生时即被测量，发现按可信度分级，已有债务可通过 baseline 接受，账本记录每次会话的真实复杂度变化。

适合谁使用

使用 Claude Code 或其他编码代理的开发者
希望让 AI 生成的代码保持精简、少依赖的团队
需要了解代理是否偏离规则的技术负责人或审查者

典型使用场景

在代理会话中强制执行新增行数、新文件和新依赖的预算
捕捉代理添加的、重复实现标准库或平台功能的依赖
审计代码库中的包装函数、重复助手和过度设计
通过 ratchet report 追踪多次会话的复杂度趋势

项目优势

在 PostToolUse 中运行，每次 Edit/Write 都会在代理仍在工作时被检查并把发现送回同一会话
发现被分为 certain/likely/heuristic 三个等级，strict 模式只阻断 certain
mark/ledger 和 baseline 指纹让已有债务可以被豁免，而新债务仍会被标记
提供 ratchet doctor 和 115 个测试，用于验证钩子确实触发并能发现植入的问题

使用前须知

检测器是正则和 git grep，不是类型检查器，因此会有误报，strict 需要主动开启
默认不扫描测试文件，除非设置 scanTests: true，因此 tests/fixtures 中的问题不会被标记
没有基准证明代码变得更好；阻断编辑还取决于宿主机是否支持 decision 字段

README 快速开始

Ratchet

Your agent reads the rules. This checks whether it followed them.

A ratchet turns one way. Complexity in your codebase goes down or stays flat, unless someone deliberately turns it the other way and writes down why.

The problem

Every minimalism ruleset for coding agents is an open loop. You inject prefer the standard library, do not add dependencies, keep the diff small, the model reads it, and then nothing checks whether any of it happened.

Compliance is assumed. When the model drifts, which it does over a long session, nobody finds out until review.

What this does instead

The ruleset still goes in. But a PostToolUse hook reads every edit the agent makes, measures it, and reports what it found back into the same session, while the agent is still working.

you    add a date picker to the settings page

agent  [installs flatpickr, writes a wrapper component, adds a stylesheet]

hook   ratchet guard  ·  +71 -0 lines (net +71/150)  ·  2/3 new files  ·  1/1 new deps

       certain
         package.json:14        dep      new dependency flatpickr
                                         justify it against the stdlib and the platform, or drop it
         src/DatePicker.jsx:4   native   date picker component library
                                         
       likely
         src/DatePicker.jsx:22  wrapper  DatePicker only forwards to Flatpickr
                                         call it directly and delete the wrapper

agent  [reverts, ships ]

Nothing here depends on the model having felt persuaded by a system prompt.

Install

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

Then once per repository you want watched:

cd your-project
ratchet

That is the whole setup. It registers the hooks, starts measuring, accepts everything already in the code as a baseline, and opens the window:

ratchet is watching your-project

  hooks      C:\your-project\.claude\settings.json
  measuring  .ratchet\  (mark at 1284 lines)
  baseline   31 findings from before now accepted, only new ones fire
  window     opened ratchetui.exe
  plugin     C:\Users\you\ratchet

restart your agent so it picks the hooks up.

Restart your agent. Done.

Requirements. Node 20 or newer. Git on PATH for the measuring half; without

项目描述

Your agent reads the rules. This checks whether it followed them.

ratchet