Ratchet はコーディングエージェントが自分に課されたルールを実際に守ったかを確認する

Ratchetが検査するエージェントの規律

README はよくある問題をこう説明している。標準ライブラリを優先する、依存関係を増やさない、差分を小さく保つといった、コーディングエージェントに与えられる最小主義的なルールセットは開ループになっている。指示はプロンプトに書き込まれ、モデルはそれを読むが、実際に守られたかどうかを確認する仕組みは何もない。README は、モデルが長いセッションの中で逸脱していく(実際に起きるとされている)場合、誰かが後でコードをレビューするまで誰も気づかないと述べている。README が説明する Ratchet の対応は、エージェントが行うすべての Edit、MultiEdit、Write を読み取る PostToolUse フックであり、それを測定し、作業がまだ続いている同じセッションの中に結果を返す。事後の別レビュー工程に委ねるのではない。

READMEにある違反検出の実例

README は具体的な一場面でこのループを説明している。ユーザーが設定ページに日付ピッカーを追加するよう依頼すると、エージェントは flatpickr パッケージをインストールし、ラッパーコンポーネントを書き、スタイルシートを追加する。するとフックが行数、ファイル数、依存関係数、そして三つの等級付きの検出結果を報告する。package.json に新たに記録された依存関係、type が date の input 要素として既に使えるネイティブな代替手段、そして Flatpickr にそのまま呼び出しを転送するだけのラッパーコンポーネントである。README によれば、エージェントは変更を取り消し、代わりにネイティブな input 要素を使う。文書ではこれは説明のための一例として提示されているのであって、ベンチマークや第三者の報告に裏付けられた結果ではない。実際のセッションでどれくらいの割合でこのような結末になるのかは README には書かれていない。

npmから導入してフックを有効にする

README が示す手順に従うと、セットアップは三つのコマンドで進む。git clone https://github.com/0xwilliamortiz/ratchet.git、cd ratchet、npm install -g . である。その後、監視したいリポジトリに移動して cd your-project と ratchet を実行する。README の説明では、ratchet を一度実行するだけでフックが登録され、測定が始まり、コード内に既にあるものはすべてベースラインとして受け入れられ、状態ウィンドウが開く。そのあとエージェントを再起動してフックを反映させる必要がある。README が挙げる前提条件は Node 20 以降、そして測定関連の半分の機能を使うには PATH 上に git が必要という点である。git がなくてもルールセットと検出器は動くが、mark、ledger、監査は動かない。README にはまた、ratchet init と ratchet baseline がこの二つの手順を個別に実行できるコマンドとして存在することも書かれており、Windows では同梱の hooks/ratchetui.exe がセットアップ中に自動的に開くとされている。

strict、warn、auditの判定モード

README は四つのモードを、漠然とした説明ではなく数値の閾値表として定義している。advise モードは新規ファイル 8 個、新規依存関係 3 個、正味追加 400 行までを許容し、超えると検出結果だけを表示する。既定の guard モードはこれを新規ファイル 3 個、新規依存関係 1 個、正味追加 150 行まで引き下げ、超えると検出結果に加えて予算の警告も出す。strict モードはまた新規ファイル 1 個、新規依存関係 0 個、正味追加 60 行まで絞り込み、超過すると編集そのものをブロックする。off モードは何も実行しない。README によれば、モードはセッションの途中で /ratchet strict のようなコマンドで切り替えられ、/ratchet default advise で設定を永続化でき、RATCHET_MODE 環境変数でも設定できる。

検出器の証拠と信頼度スコア

README によると、すべての Edit、MultiEdit、Write はタグ付けされた八つの検出器を通過する。dep は package.json や requirements.txt などのマニフェストファイルに新たに現れた名前を検出し、exists は新しいシンボルの正規化された名前が既にリポジトリの別の場所にあるかどうかを検出し、stdlib は標準ライブラリが既に提供している機能を手作りで再実装しているコードを検出し、native はプラットフォームが既に行っていることを重複して行う依存関係やコードを検出し、wrapper は同じ引数で別の関数にそのまま処理を転送するだけの関数を検出し、yagni は実装が一つしかないインターフェースや抽象クラスやプロトコルを検出し、validation は独自に書かれたメールアドレスの正規表現(README はこれを常に不正確だとしている)を検出し、budget は新規ファイル数、新規依存関係数、正味追加行数の累計そのものを検出する。それぞれの検出結果は certain、likely、heuristic のいずれかの等級を付けられ、README は strict モードが certain の等級だけをブロック対象にすると明記している。likely と heuristic の検出結果は別のグループにまとめられ、エージェントやユーザーの判断に委ねられる。

既存違反を扱うbaselineの設計

特定の検出結果を通す方法は二つあり、README はその意図の違いで区別している。ratchet-ignore: profiled, the clone is the hot path のような一行のコメントは、理由を書いた上でその一件だけを通す。一方 ratchet baseline コマンドは、その時点でリポジトリに存在するものすべてを一括で受け入れ、以降は新たに増えた負債だけが検出結果として現れるようにする。検出結果は行番号ではなくタグ、パス、形状によって指紋化されるため、README によればベースラインはコードの再フォーマットやファイル内での移動を経ても維持される。これとは別に、mark.json ファイルは行数とファイル数、そして書き込まれた理由とともに、受け入れられたリポジトリの規模を記録する。各セッションが終わるたびに ledger.jsonl に一行(モード、追加と削除の行数、依存関係数、検出結果数、リポジトリ規模)が追記され、ratchet report で読み返せる。README によれば、mark を引き上げるには accept-mark.js を引用符で囲んだ理由の文字列とともに実行するようなコマンドが必要になる。

ルール適用後に残る未説明の範囲

README は検出器の正体について率直に書いている。それは正規表現と git grep であって型チェッカーではなく、誤検出が生じるとしている。これが既定モードがブロックではなく報告にとどまり、strict モードが任意で有効にするものになっている理由だとされている。exists 検出器は正規化された名前を比較するため、本当に重複したヘルパー関数を捉えることもあれば、たまたま同じ名前になった無関係な二つの関数を捉えることもある。五文字未満の名前は除外され、certain の等級を付けられることは決してない。テストファイルやフィクスチャ(tests/、__tests__/、spec/、*.test.* などのパターンに一致するパス)は、設定で scanTests を true にしない限り一律スキップされる。README ははっきりと、これがコードを良くすることを示すベンチマークは存在せず、報告される行数や依存関係数だけが実際の数値だと述べており、予算超過時に本当にブロックされるかどうかはホスト側のエージェントが PostToolUse の decision フィールドに従うかどうかに依存するとしている。README が明らかにしていない点として、リポジトリはスター 430、フォーク 85、未解決の issue 1 件を示しているが、README はこれらの数字の由来を説明しておらず、利用者を一人も名指ししていない。ratchet doctor と ratchet log が実運用で二つの具体的なバグ(シンボルインデックスが重複を隠していた問題と、依存関係名のフィールドに文全体が保存されていた問題)を見つけたという主張は、プロジェクト自身の説明であって外部からの報告ではない。Development の項で触れられている 115 件のテストも、説明されているだけでここで再現されているわけではないので、そのカバレッジは README の言葉をそのまま受け取るのではなく、自分で確認する必要がある。

ratchet doctorで導入前に確認する

READMEが示す検証入口はratchet doctorです。監視対象リポジトリでratchet initのあとratchet doctorを実行し、Node 20以上、gitの有無、フック登録状態、mark.jsonとledger.jsonlの書き込み権限がREADMEの前提と一致するかを確認します。gitがPATHにない場合、READMEの説明どおりmarkとledgerは動かず、depやexistsなどの検出器だけが有効になる点もここで把握できます。

strictモードのブロックが実際に効くかはホストエージェントがPostToolUseのdecisionフィールドを解釈するかに依存します。READMEのflatpickr例のようにエージェントが変更を取り消す流れを再現するには、guardモードで小さなEditを試し、ratchet reportとledger.jsonlの一行がセッション終了時に追記されるかを見ます。115件のテストやratchet logが報告した二件のバグ修正はREADME記載の開発情報であり、npm install -g .後にnpm testを実行して通過件数を自分の環境で確認するのが妥当です。

編集部の結論

このプロジェクトは MIT ライセンスで公開されており、著作権表示とライセンス文を残す限り、商用利用を含む使用、複製、改変、再配布を許可している。ライセンス文自体はサポート、セキュリティ保証、保証責任について何も述べておらず、それらを明示的に否定している。このフックが実際の複数ファイルにまたがるセッションでどう振る舞うか、そして strict モードのブロック機能が実際に使うホストエージェントで本当に機能するかどうかは、README の例をそのまま信じるのではなく、ratchet doctor を実行してその出力を読むことで確かめる必要がある。

公式情報源

1. Project repository