Assurance

---

コーディングエージェントは 「完了しました。テストは合格しました」 と報告します。Assurance は実際に起きたことを読み取り、何を実行し、何を省略し、何を検証できなかったかを、平易な文章で伝えます。

クイックスタート

Claude Code または Codex を使ったことのあるプロジェクトで、次のコマンドを実行してください。

uvx assurance audit                        # with uv: runs it without installing anything
pip install assurance && assurance audit   # without uv

このフォルダーでどちらかのエージェントが残した最新のセッションを読み取ります。設定は不要で、どちらを使ったかを指定するフラグもありません。まだどちらも使っていない場合は、uvx assurance audit --demo を実行すると、同梱のサンプルセッションでレポートを確認できます。

uvxがありませんか？ uvに付属しています。インストールは1行で完了します。

場所	コマンド
macOS（Homebrew）	brew install uv
macOS / Linux	curl -LsSf https://astral.sh/uv/install.sh | sh
Windows	powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Windows（WinGet）	winget install --id=astral-sh.uv -e
Python が使える環境	pipx install uv または pip install uv

その後、新しいターミナルを開くと、uvx が PATH に追加されます。あるいは uv を使わず、pip install assurance を実行しても、同じ assurance コマンドを利用できます。

このリポジトリのサンプルセッションでの実際の出力を紹介します。エージェントには、invoice.py の丸め処理のバグを修正し、「pytest -q tests/test_invoice.py が合格することを確認する」 よう依頼しました。そして最後に 「完了しました。合計は正しくなりました」 と報告しました。

$ assurance audit examples/audit/sample-session.jsonl
Claude Code session demo-8f2 — 13 min in /home/you/my-app
10 tool calls, 3 failed — Bash 6, Edit 2, Grep 1, Read 1

  Looped: 3 rounds of Bash `pytest -q tests/test_invoice.py` failing the same way, with nothing new read
  After the last edit (14:09): no test or check it recognises; 2 unclassified commands ran after it (make lint-fix, python script)
  Against the last prompt (14:00, "The invoice totals are off by a cent for EUR. Fix it in inv…"):
    invoice.py: changed at 14:04 (src/billing/invoice.py).
    pytest -q tests/test_invoice.py: did not run after the last edit to src/billing/rates.py (14:09); it last failed at 14:08, before that.
    Only what the last prompt names is checked here; whether the work does what it asks is not.
  Not classified: 2 shell commands (make lint-fix, python script), so whether they read, wrote or tested anything is unknown.
  Also in the transcript: 1 assistant turn, 1 user turn, 1 bookkeeping record.
  Not read: 0 lines.

「完了しました」の報告に含まれていなかったこと：

• ❌ テストは3回連続で失敗し、毎回同じ結果でした。
• ❔ 最後の編集後に、Assurance が認識できるテストは実行されていません。コマンドは2つ実行されましたが、どちらについても合格かどうかを保証できないため、そのコマンドを示しています。何も言わないことは合格を意味しません。
• ❔ プロンプトで指定されたテストが最後に実行されたのは、最後の編集より前で、そのときは失敗していました。指定されたファイルは変更されています。修正が正しいかどうかは分からないと、Assurance は明言しています。

セッションごとに実行する

Stop フックを有効にすると、Claude Code は Claude がターンを終えるたびに監査を実行します。伝えることがある場合に限り、最初に示される次の 3 段階のいずれかで通知します。

レベル	条件	誰に確認するか
note	このターンでコードが変更され、まだテストされていない場合	あなたに一度、実行するコマンドを伝えます。Claude には何も尋ねません
suggested review	最後の編集後にテストが失敗した場合、保護対象のパスが変更された場合、または裏付けがないまま Claude がテストに合格したと言った場合	あなたと Claude に、修正するか、その理由を説明するよう求めます
stop and check	未テストのコードが main でプッシュ、マージ、公開、デプロイ、マイグレーション、またはコミットされた場合	あなたと Claude に、後続の作業に進む前に確認するよう求めます

assurance · note: no test or check has passed since the last edit to src/billing/invoice.py (14:04). Run pytest -q tests/test_invoice.py before you commit or push.
assurance · suggested review: the last test run after the last edit to src/billing/invoice.py (14:04) failed: pytest -q tests/test_invoice.py (tests/test_invoice.py::test_eur_rounding; 1 failed, 11 passed in 0.33s).
assurance · stop and check: pushed at 14:06 with no passing test or check after the last edit to src/billing/invoice.py (14:04).

uvx assurance@latest hook install   # shows the change to ~/.claude/settings.json, asks, then writes it
uvx assurance hook remove           # takes it out again; nothing else changes

Maven、Gradle、Bazel、Django、Rails、jest、vitest、go、cargo などのテストコマンドに対応しています。package.json、Makefile、justfile のスクリプトを読み取り、プロジェクト固有のコマンドを把握します。また、テストが 0 件の実行を合格として扱うことはありません。対応しているもの。

または、Claude Code プラグインとして利用できます。claude plugin marketplace add i-ops-hq/assurance を実行してから、claude plugin install assurance@i-ops-hq を実行してください。セッションをブロックしたり、失敗させたりすることはありません。バージョンの固定、チームとの共有、Windows、およびプラグインが実行する内容については、フックガイドをご覧ください。

ユースケース

Assurance が、現在の作業のどこに組み込まれるかを紹介します。各ページは簡潔です。問題が起きる場面、組み込む場所、設定する行を説明しています。

作業内容	確認する内容
決済とフィンテック	資金を扱うコードが依存するテストが、最後の編集後に実行され、何かをリリースする前に合格していること
銀行業務と規制対象の変更	セッションごとに、変更内容とテスト内容の記録が残ること。また、変更が及ぶすべての所有者に対して、依頼者が許可されているかどうか
医療とライフサイエンス	エージェントが依頼されていないのに変更した保護対象のパス、およびインストールで実行される内容を実行前に確認できること
法律、保険、文書	調査エージェントが質問に必要なすべての文書を読んだかどうか、およびレポートのフォルダーで欠けている期間
プラットフォーム、DevOps、SRE	未テストのコードに対するプッシュ、デプロイ、マイグレーション、変更が及ぶ範囲、およびセッションでは引き上げられない制限
独自のエージェントを構築するチーム	エージェントの「完了」とゲートの「許可」を、その後に起きたことと照らし合わせます。実行記録または OTel トレースから確認できます

prompt ─▶ agent edits ─▶ note ─▶ tests ─▶ suggested review ─▶ push / deploy ─▶ stop and check ─▶ CI gate

コマンド

インストールは一度だけ。コマンドは assurance だけです。

コマンド	確認できること
assurance audit	このフォルダーでの Claude Code または Codex のセッション、あるいは独自のエージェントの実行やトレースで、何が行われ、何がスキップされたかを確認します。
assurance hook	Claude Code の各ターン後に監査を実行するよう設定するか、実行を停止します：install、remove、status。
assurance notices	フックが各通知を出した後、次のターンでテストを実行したか、失敗を修正したか、ファイルを元に戻したかを確認します。このマシンのトランスクリプトから読み取るため、データは送信されません。
assurance serve	あらゆるエージェントがトレースや実行記録を送信でき、あらゆるワークフローが実行の監査を要求できるローカルエンドポイントです。
assurance coupling	Git の履歴から、変更したものと通常一緒に変更されるもの、そしてそのうちまだ触れていないものを確認します。グラフも設定も不要です。
assurance reach	Graphify などのコードグラフを使って、このファイルへの変更がどこまで影響するか、またそのグラフがコードからどれほど遅れているかを確認します。
assurance clearance	変更が影響するすべてのオーナーについて、依頼者に権限があるかを確認します。
assurance diff	作業が必要なものをすべて網羅したかを確認します。たとえば、取得したドキュメントと必要なドキュメントを照合します。
assurance pin	MCP サーバーが、承認後にツールの説明をひそかに変更していないかを確認します。
assurance deps	pip install または npm install がマシン上で何を実行するかを、実行せずに読み取ります。
assurance budget	エージェントの実行で予算をどこに費やし、どこでループしたかを確認します。
assurance authority	他人のアクセス権を借りずに、依頼者の権限でこのタスクを進められるかを確認します。
assurance check	日付付きレポートのフォルダーが完全か、どの期間が欠けているかを確認します。

すべてのコマンドは、そのまま CI ゲートとして使用できます。

終了コード	意味
0	確認済み。問題は見つかりませんでした
1	確認が必要なものがあります。確認できなかったものも含みます
2	実行できませんでした

ガイド

• 各セッション後に実行する：各レベルの詳細、ピン留め、チームでの設定、プラグイン、Windows
• プロジェクト独自のルール：独自のテスト、必須の合格条件、変更してはいけないもの、エージェントが引き上げられない上限を定義します
• 独自のエージェント：実行記録、OpenTelemetry トレース、ローカルエンドポイント
• その他のチェック：取得範囲の網羅性、MCP のピン留め、インストール、変更の影響範囲、MCP ツール

対応しないこと

• 推測しません。 数値を確定できない場合は、作り上げずにその旨を伝えます。
• モデルやネットワークを呼び出しません。 すべての結果は、自分で確認できる計算に基づきます。
• 確認した以上のことを主張しません。 audit は Claude Code のトランスクリプト、Codex のロールアウト、独自のエージェントが書き込む実行記録を読み取ります。認識できない形式の記録は、ツール呼び出しとして推測することなく未読として数え、その件数をレポートに表示します。他のエージェントのログへの対応は今後の予定です： 使用しているものをお知らせください。

問題がある箇所をお知らせください

まだ開発初期の段階です。実際の作業で実行していただくことが、最も役立ちます。

• 🎯 誤った回答や誤解を招く回答がありました。これが最も価値のある報告です。
• 🐛 何かが壊れました
• 💡 別のエージェント、ロックファイル、またはフレームワークへの対応を提案する
• 🤝 貢献する： good first issueを選び、CONTRIBUTING.mdをお読みください。

役に立った場合は、⭐を付けると、ほかの人にも見つけてもらいやすくなります。

パッケージ

pip install assurance を実行すると、すべてのコマンドがインストールされます。各パッケージは個別にインストールすることもできます。

パッケージ	内容
assurance-cli	assurance コマンド：diff、check、pin、drift、init
assurance-budget	コーディングエージェントのセッション用の audit と、実行ログ用の budget
assurance-deps	インストール時に実行される内容を、実行せずに読み取ります
assurance-authority	依頼した人にとって、タスクを進めてよいかどうかを判断します
assurance-reach	コードグラフを使って変更の影響範囲と、そのグラフがコードにどれほど遅れているかを確認します
assurance-mcp	--root の範囲に限定された、読み取り専用 MCP ツールとしてのチェック機能です
assurance-core	基盤となる純粋な判定ライブラリです。I/O、モデル、依存関係はありません

---