Tracegate CI

Tracegate CI

変更によって影響を受けるテストだけを実行し、残りをスキップするには、その安全性を実証する必要がある TypeScript 向けローカル CI です。

Tracegate は、各テストファイルの実行時に、そのファイルが触れたものを記録します。実行した関数、読み込んだモジュール、読み取ったファイルです。コードを変更したとき、記録された入力に変更がなかったテストは、直近の成功結果を再利用できます。それ以外のテストは実行されます。

安全だと確認されるまでは、何もスキップしません。

• まずシャドーモード。 すべてのテストを実行し、スキップされるはずだったテストを Tracegate が記録します。
• 開始基準。 14 日間に 20 回実行され、直近 14 日間に未トリアージのミスがなければ、レーンでスキップを開始します。
• ランダム監査。 スキップ可能なテストの 5% は、スキップせず実行します。
• ミスがあれば一時停止。 スキップしても安全だと予測されたテストが実際には失敗した場合、そのミスを誰かが不安定なテストとしてトリアージしない限り、レーンは 14 日間すべてを実行します。

失敗を成功に変えることはありません。失敗したテストの記録は破棄され、72 時間を超える記録は再利用されません。

Tracegate は、約 3,700 個のテストファイルがあり、すべてのマージをゲートする非公開の TypeScript モノレポで生まれました。そこで測定されたミス率は、docs/evidence/ で公開されています。

インストール

npm install --save-dev tracegate-ci
npx tracegate init --write --mcp   # writes tracegate.config.json and wires the recorder
npx tracegate doctor --canary      # checks the setup by recording one test file
npx tracegate run                  # runs the lane; in shadow, everything still runs
npx tracegate savings              # what skipping would have saved so far

2 週間試して測定結果を共有するには、docs/trial.md をご覧ください。

--write を付けずに init を実行すると、実行内容を表示するだけです。既存の設定を上書きすることはなく、手動で編集する必要がある Vitest の設定も案内します。

要件： リポジトリに Node 22 以降、git、Vitest 4.1～5.x または Jest 30、TypeScript 5 または 6 が必要です。TypeScript 7 の場合は、Tracegate が検索するエイリアスの下に 6 もインストールしてください。 npm i -D tracegate-typescript@npm:typescript@6

Claude Code プラグイン

/plugin marketplace add davidscotttufts/tracegate-ci
/plugin install tracegate@tracegate

このプラグインは、MCP サーバー、2 つのサブエージェント（red-reader、deps-oracle）、2 つのスキル、フックを追加します。Tracegate リポジトリでは、このフックにより、エージェントがキューを介さずに vitest や npm test をそのまま実行することや、ミスのトリアージ、スキップされたテストの承認を自ら行うことを防ぎます。TRACEGATE_HOOK=off で無効にできます。

プラグインが実行・操作するもの（PRIVACY.md にも記載）：

• 実行するもの： 独自ファイルに対する node（stdio 経由の MCP サーバーとフック）、git、テストランナー、tracegate lease に渡すコマンド、attest の実行時に使用する ssh-keygen または gpg。
• 読み取るもの： リポジトリとその履歴、テストカバレッジ、このマシンの負荷とメモリ（macOS では ps、vm_stat、sysctl、pmset、Linux では /proc）。
• 書き込むもの： .git/tracegate/ 内の台帳、OS の一時ディレクトリ内の一時ファイルとソケット、attest の実行時に refs/notes/tracegate に作成する git notes、init --write に表示されるファイル。
• 送信するもの： デフォルトでは何もありません。テレメトリーもネットワーク呼び出しもありません。自分で有効にする 2 つの機能は、自分のログインを使ってネットワークに接続します。attest --status は gh を使って GitHub のコミットステータスを投稿し、release bus は gcloud を使って、指定した GCS バケットを読み書きします。
• インストールするもの： 何もありません。このパッケージにはランタイム依存関係がありません。

判定方法

依存先に変更がなければ、テストは直近の成功結果を再利用します。変更がないことを確認する対象は、次のとおりです。

• 実行した関数、使用する定数、読み込んだモジュール。
• 読み取ったファイル。
• テストファイル自体。
• package.json、ロックファイル、Vitest の設定などのグローバル入力。
• git を実行するテストの場合は、リポジトリの履歴。

未コミットの編集も対象になります。テストが実行していない関数内の編集は対象になりません。

記録では、時刻、環境変数、ネットワーク、その他のプロセスを検知できません。72 時間の制限、ランダム監査、少なくとも 1 日に 1 回の全件実行で、これらに対処します。ルールの全容は判定方法をご覧ください。

コマンド

コマンド	機能
tracegate run	テストを選択して実行し、結果を記録して、そこから学習します。
tracegate status	各レーンのモードと、開始基準までの進捗を表示します。
tracegate savings	これまでにテストをスキップしたことで節約できた時間を表示します。
tracegate report-card	95％信頼区間を含む見逃し率を表示します。プライベートリポジトリでは --redact を指定します。
tracegate triage	見逃しを、フレーキーテストまたはレコーダーのバグとしてマークします。
tracegate lease	マシンに余裕があるときにコマンドを実行します。
tracegate train	ブランチのキューをゲートし、問題のないものをマージします。
tracegate daemon	夜間に全レーンを実行し、キュー内のブランチを事前テストします。
tracegate bus	別のマシンが何をゲートまたはデプロイしているかを確認します。
tracegate attest / verify	コミットで何がテストされたかに署名し、確認します。
tracegate mcp	エージェント向けの MCP サーバーです。

tracegate --help ですべてのコマンドとフラグを確認できます。

設定

tracegate init --write で tracegate.config.json が作成されます。レーンはテストプロジェクトを表します。

{
  "lanes": {
    "api": { "dir": "packages/api", "src": "src", "globals": ["test/setup/"] },
    "web": { "dir": "packages/web", "src": "src" }
  }
}

テスト設定ディレクトリを globals に指定してください。すべてのテストで読み込まれるため、ここに変更を加えるとレーン全体が実行されます。すべての設定についてはガイドをご覧ください。

ほかの機能

機能	用途
ブローカー	マシン上の単一キューです。ゲート、バックグラウンドジョブ、すべてのエージェントのテスト実行が CPU とメモリを共有するため、互いに競合しません。
マージトレイン	ブランチのバッチを実際のマージコミットとしてゲートし、失敗したバッチを二分探索し、テストに合格したものだけを正確にマージします。
Red Reader	エージェントが失敗した実行を読み取り、「フレーキー」な失敗を実際のバグとしてマークできます。その逆は決してできません。
サイレンスガード	人が承認するまで、テストをスキップ、フォーカス、削除する変更を失敗扱いにします。
Conductor	失敗する可能性が最も高いテストから実行し、どのブランチを単独でゲートすべきかを提案します。
依存関係の変更	ロックファイルが変更された場合、変更されたパッケージを読み込んだテストだけを再実行します。
キー付き入力	翻訳ファイル内の文字列を1つ編集すると、それを使用したテストだけを再実行します。
デーモン	アイドル時間を利用して全テストを実行し、キュー内のブランチを事前テストします。
リリースバス	2台のマシンが互いのトレインとデプロイを確認できるようにします。
アテステーション	コミットの正確なツリーで何が実行されたかを記録した署名付きレコードです。

Vitest の recordDependencies を使わない理由は？ 比較では、同じコミットで両方を実行しています。Tracegate は関数単位で選択し、実行時に読み込まれたファイルを検出して、自らのスキップを監査します。

詳細

• ガイド：完全なリファレンスです。
• ロードマップと変更履歴。
• 背景：設計の基礎となった調査と測定結果です。
• レシピ：claude-code-merge-queue、編集単位のガード、worktree、bin/ci スクリプトを使った方法を紹介します。

Apache-2.0。LICENSEとNOTICEをご覧ください。