Abideでコーディングエージェントのルールをすべての編集に適用

Abideの機能

Abideは、通常のリンターでは確実に評価できないプロジェクト固有の指示を適用します。こうした指示はAGENTS.mdやCLAUDE.mdなどのファイルに記載され、手動バリデーションではなくYupを使う、呼び出し元が1つしかないヘルパーを作成しない、未加工のエラーをユーザーに公開しないといったルールが含まれます。

編集またはターンの完了後、Abideは関連するルールとコード差分をTypeSafeのJev判定モデルに送信します。Jevは自由形式の文章ではなく、確率を返します。その確率が違反を示す場合、Abideはどのルールに違反したかをコーディングエージェントに伝え、同じターン中にコードを修正するよう求めます。

Jevが確認するのはルールと差分であり、エージェントの会話ではありません。これにより、長時間のコーディングセッション全体で同じチェックを一貫して適用できます。リポジトリが公開しているリプレイベンチマークによると、Jevでのチェックは約300ミリ秒、Nodeの起動時間を含む完全なフックは約1秒です。

主な機能

• 編集の自動チェック：コード編集のたびにルールを即座に実行できます。
• ターン単位のチェック：タスク全体の差分を必要とするルールを、ターンの終了時に1回実行できます。
• エージェント連携：AbideはClaude Code、Codex、OpenCodeに対応しています。
• リポジトリ所有のルーブリック：コンパイル済みのルールは、読みやすくコミットにも適した.abide/rubric.jsonファイルに保存されます。
• スコープ付きルール：ルールではglobスコープを使えるため、APIルート、スタイルシート、その他のファイルグループごとに異なる質問を適用できます。
• 既存コードの監査：ファイルが作成された直後であるかのように判定できます。
• キャリブレーションと調整：最近のGit履歴に対してルールをテストし、効果のないルールを無効化し、一度も発動しないルールの書き換えを支援できます。
• フェイルオープンのフック：認証情報の欠落、ネットワーク障害、フックエラーがコーディングセッションをブロックすることはありません。
• 組み込みポリシーなし：Abideはあらかじめ定義されたルールセットを押し付けるのではなく、独自の指示ファイルから導出したルールを適用します。

前提条件

コーディングエージェント向けの指示があるリポジトリと、対応エージェント（Claude Code、Codex、OpenCode）のうち少なくとも1つが必要です。また、typesafe.aiのTypeSafe APIキーも必要です。代わりに、AI_GATEWAY_API_KEY環境変数を使用して、既存のVercel AI Gatewayキーを利用することもできます。

Abideのインストールと設定

ステップ1：APIキーを保存する

ログインコマンドを実行し、プロンプトが表示されたらTypeSafeキーを貼り付けます。

npx @coldtea/abide login

Abideはキーを所有者のみがアクセスできる~/.abide/.envに保存します。代わりに、リポジトリルートの.env.localまたは.envに認証情報を配置することもできます。認証情報は、まず環境変数、次にリポジトリ内のファイル、最後に~/.abide/.envの順に検索されます。

Vercel AI Gatewayを使用する場合は、TypeSafeキーではなくAI_GATEWAY_API_KEYを設定してください。認証情報はコマンドラインフラグでは受け付けず、ログにも記録されません。

ステップ2：エージェントフックをインストールする

リポジトリからAbideを初期化します。

npx @coldtea/abide init

エージェント名を指定しない場合、initは検出したすべての対応エージェントにインストールします。特定の連携先を明示的に指定することもできます。

npx @coldtea/abide init claude
npx @coldtea/abide init codex
npx @coldtea/abide init opencode

• Claude Code：連携設定が~/.claude/settings.jsonに追加されます。
• Codex：連携設定が~/.codex/hooks.jsonに追加されます。
• OpenCode：プラグインが~/.config/opencode/plugins/abide.jsにインストールされます。

チェックアウト時にチームメンバーも受け取れるリポジトリレベルのインストールを行う場合は、--projectを追加します。

npx @coldtea/abide init claude --project

Codexでは追加の承認手順が1つ必要です。Codexを起動し、/hooksと入力して、Abideの4つのフック項目を承認します。Codexがこの承認を求めるのは、新しいフックごとに1回だけです。

ステップ3：リポジトリのルールをコンパイルする

通常どおりコーディングエージェントを起動します。最初のセッションの開始時に、Abideは指示ファイルが変更されているか確認します。その後、エージェントが適用可能な指示を.abide/rubric.jsonにコンパイルし、検出内容を報告します。

新しいセッションを開始する前にコンパイルすることもできます。

abide compile

リポジトリで適用可能なルーブリックをチームが確認・レビューできるようにしたい場合は、.abide/rubric.jsonをコミットしてください。すべての判定で、このファイル内のルールと、そのルールの元になった指示が引用されます。

基本的な使い方

エージェントの編集をAbideで自動的にチェックする

初期化が完了したら、通常どおりclaude、codex、またはopencodeを起動します。別途バックグラウンドサービスを実行する必要はありません。たとえば、ある指示でAPIエンドポイントにYupを使用し、入力を手動で検証してはならないと定めているとします。エージェントが手動ガードを作成すると、Abideは次のようなメッセージを返せます。

Abide: この編集は、このリポジトリの指示にあるルールに違反しているようです。
- ~/.codex/AGENTS.md の65行目にあるルール「api-validation-uses-yup」:
  「APIエンドポイントを記述する際、入力検証を手動で記述してはいけません。
  Yup（明確な検証メッセージ付き）を使用し、APIハンドラー内で早期リターンしてください」。
  (0.86)
今すぐ apps/web/src/pages/api/logout.ts を修正し、その後タスクを続行してください。

エージェントは修正要求を受け取り、作業を続ける前に違反を修正できます。OpenCodeでは、編集違反がツール結果に追加されます。ターンレベルの違反では、ターン終了後にフォローアップメッセージが1件送信されます。

未コミットの変更を手動で確認する

フックと同じ方法で現在の未コミットの変更を評価するには、checkを使用します。

abide check

チェック対象を絞りたい場合は、パスを指定することもできます。

abide check apps/web/src/pages/api/

既存のコードを監査する

auditコマンドは、既存のファイルを新規作成されたかのように評価します。既存のリポジトリにAbideを導入する際に便利です。

abide audit src/

出力にはルールごとの概要と、ファイル別に整理された一覧が含まれます。READMEによると、実際のNext.jsアプリケーションで33個のAPIルートを監査する処理には約12秒、費用には約1セントかかりました。ただし、実際の結果はリポジトリとルールによって異なります。

ルールの活動状況を確認する

レポートコマンドを実行すると、ルール、発動したルール、まだ一度も発動していないルールを確認できます。

abide report

機械可読形式で出力するには、--jsonを追加します。check、audit、bench、calibrateでもJSON出力を利用できます。

ルールのタイミングと判定を理解する

コンパイル済みの各ルールは、次の2つのフェーズのいずれかで実行されます。

• 編集フェーズ: 個々の編集後に実行され、そのハンクを評価します。
• ターンフェーズ: ターン終了時に1回実行され、ターン開始時に取得したスナップショットとの差分全体を評価します。

ターンレベルの評価は、最初の編集だけでは判断できない問題、たとえばエージェントがユーザーの要求していない機能を追加したかどうかを確認するうえで重要です。ターン終了時には、Abideはシェルコマンドによって作成された変更にも編集フェーズのルールを適用します。

判定は確率帯に分けられます。

• 0.8以上: エージェントに違反の修正が指示されます。
• 0.5以上0.8未満: 注記が表示されますが、エージェントに修正は指示されません。
• 0.5未満: 何も表示されません。

高度なワークフロー

Git履歴に対してルールをキャリブレーションする

表現の悪いルールは、無関係な変更の多くで中程度のスコアになり、有用な結果をまったく出さないことがあります。キャリブレーションコマンドは、リポジトリのGit履歴にある最近の実際のハンクに対して、すべてのルールを評価します。

abide calibrate

Abideはこの処理に最近のハンクを20件使用し、効果的に機能しないルールを無効にできます。新しくコンパイルしたルーブリックをチーム全体で利用する前に、結果を確認してください。

発動しないルールを調整する

効果のないルールを特定したら、tuneを使ってエージェントにルールを書き換えさせます。

abide tune

各ルーブリック項目には元の指示が引用されているため、疑わしい判定を、その判定を生み出した文言までたどれます。元の指示を改善すると、通常は対応するチェックも明確になります。

過去のエージェントセッションを再生する

replayを使うと、サポートされているエージェントの過去のセッションを判定できます。

abide replay claude
abide replay codex
abide replay opencode

これにより、将来の違反を待つのではなく、すでに行われた作業に対してルーブリックを評価できます。

ローカルの遅延と費用を測定する

ベンチマークコマンドを実行すると、自分のマシンでパフォーマンスと費用を測定できます。

abide bench

リポジトリの報告によると、13個のルールをチェックする際の入力トークン数はおよそ1,000〜1,600、1回のチェックの費用は約$0.00004〜$0.00007、Jevでの所要時間は約300ミリ秒です。これらの数値はTypeSafeに対して直接測定されたものであり、変動する可能性があるため、自分の環境ではローカルベンチマークをより信頼できる指標として利用してください。

スコープを使って関連する質問に絞る

.abide/rubric.jsonのルールには、globベースのスコープを含めることができます。特定のファイルにのみ適用される指示には、これらのスコープを使用してください。たとえば、検証ルールはAPIルートに、スタイルルールはスタイルシートに限定できます。スコープを絞ると、無関係な判定が減り、判定結果を理解しやすくなります。

プライバシーと失敗時の動作

変更された行は、すべての呼び出しでデータ保持ゼロを要求したうえで、ユーザー自身のキーを使ってTypeSafeに送信されます。READMEには、データがAbide運営のサーバーには送信されないと記載されています。

Abideのフックは、エージェントのセッションを中断しないよう設計されています。フックのパスは正常終了し、厳格な期限を使用し、ホストが必要とする内容だけを出力します。キーがない場合やネットワークが利用できない場合、編集はチェックなしで続行されます。実行されなかったチェックは.abide/events.jsonlに記録され、abide reportの集計にも含まれます。

Abideをアンインストールする

インストール先のすべてのエージェントからAbideを削除します。

abide uninstall

1つの統合だけを削除するには、エージェント名を指定します。

abide uninstall codex

プロジェクトレベルのインストールを削除する場合は、--projectを追加します。アンインストールで削除されるのはAbide独自のエントリだけです。ルーブリックファイルと~/.abide/.envは、手動で削除するまで残ります。

まとめ

Abideは、自然言語で記述されたリポジトリの指示を、AIコーディングセッション全体で実行されるチェックに変換します。適切なフックをインストールし、.abide/rubric.jsonをコンパイルしてレビューしたら、自動チェック、監査、レポート、キャリブレーション、チューニングを活用してルールの有効性を維持します。その結果、従来のリンターでは表現できない規約に対応する、軽量な適用レイヤーが実現します。