unlazy: AIエージェントの「完了」を検査可能にするゲート台帳

unlazy が埋めようとしている穴は「完了報告」と「実際の完了」のずれ

AI エージェントにまとまった実装を頼むと、動いていないコードに対して「完了しました」と返ってくる場面がある。unlazy はこのずれを、エージェントの性格ではなく手続きの問題として扱う。README の冒頭には「Write the acceptance ledger first. Execute reviewed checks. Reverify returned work. Report only what the evidence supports.」とあり、最初に受け入れ条件の台帳を書き、レビュー済みのチェックを実行し、返ってきた作業を再検証し、証拠が支持する範囲だけを報告する、という順序が明示されている。対象読者は、Claude Code や Codex CLI に複数ファイルの改修を任せ、その完了報告を人間が読み直して確かめている開発者だ。単発の質問に答わせる用途を想定した作りではない。リポジトリのトピックには ai-agents、claude-code、prompt-engineering が並んでおり、JavaScript で書かれ、ライセンスは MIT。説明文には Depth Tree 方式（タスクを N 層に分割し、各葉にタスク全体の時間予算を与える）が挙げられているが、README の本文が実際に規定しているのはゲート契約のほうであり、以下の記述もそこに沿う。

GATES.md に書けるのは CHECK 行と EXPECT 行だけではない

ゲート台帳は Markdown のチェックリストとして書く。README の例では、G1 と G2 という 2 つのゲートが示されている。G1 は `CHECK: node scripts/verify-pricing.mjs` と `EXPECT: pricing verification passed` を持ち、G2 は同じ形に加えて `CWD: packages/checkout` を持つ。つまり、実行するコマンド、成功時に出力される文字列、そして実行する作業ディレクトリを 1 つのゲートに束ねる。`EVIDENCE: pending` は初期状態で、実行後にここが埋まる。実行可能なゲートが合格する条件は 2 つ同時で、プロセスが終了コード 0 を返すこと、そして `EXPECT:` の文字列が結合出力に一致すること。どちらか片方では通らない。出力には 1 MiB の上限があり、stdout と stderr を合わせた payload と、`EXPECT:` およびそのフィンガープリントが使う正規化済み UTF-8 文字列の両方がこの範囲に収まる必要がある。checker は上限を超えた照合文字列を切り詰めて成功扱いにすることはない、と README は書いている。証拠の自動記録は、パース済みの `CHECK:`、`EXPECT:`、生の `CWD:` 定義から取ったバージョン付きの完全な SHA-256 ダイジェストで始まり、その後に終了コードと成功出力のフィンガープリント、上限付きの環境情報が続く。パーサーはゲートが 0 件の台帳、id の重複、実行可能ゲートの記述漏れ、不正な期待値、理由のない放棄や未知のゲート id を拒否する。コードフェンス内の例は無視され、更新時には CRLF と LF の区別が保たれる。

checker の 4 つのモードと、承認が何を束縛するか

`scripts/gate-check.mjs` には役割の異なるモードがある。`--status` は常に非実行で、台帳の構造だけを見る。通常モードは、その oracle に正確な承認記録がまだない場合、解決されたコマンド、期待値、作業ディレクトリ、シェル、`PATH` を表示するだけで実行しない。README はここで注意を促している。通常モードを恒久的なドライランと考えるな、という点だ。いったん正確な oracle が承認されると、通常モードはそれを実行しうる。`--approve` は台帳を承認して実行する。`--reverify` は完了済みのゲートを含めて、実行可能なゲートをすべて再実行する。承認記録は既定で `~/.unlazy/approved` に置かれ、`UNLAZY_APPROVAL_DIR` で別のディレクトリを指定できる。ただし正規化した宛先が検査対象リポジトリの外にあること、所有者だけが読める実ディレクトリであることが条件で、シンボリックリンクのストアや、リンクされた記録、置き換えられた記録、非プライベートな記録はフェイルクローズで拒否される。1 件の承認記録が束縛するのは、台帳の絶対パスとゲート、`CHECK:` と `EXPECT:` の厳密な内容、解決済みの `CWD:` とシェル、タイムアウト、出力と正規表現の上限、正規表現ワーカーの上限、プラットフォーム、そして継承された `PATH` の全体だ。束縛された入力のどれかを編集すれば、承認を取り直す必要がある。

導入は npx skills add と 2 つの配置先から

インストールは skills CLI 経由で `npx skills add Leonxlnx/unlazy` を実行する。`-g` を付けるとユーザーレベル、`--all` を付けると検出されたすべてのエージェントに入る。手動で置く場合のパスは README に明記されていて、Claude Code は `~/.claude/skills/unlazy`、Codex CLI は `~/.codex/skills/unlazy` だ。呼び出し方は環境によって変わり、スラッシュスキルに対応した環境では `/unlazy`、Codex では `$unlazy`、それ以外ではスキル説明からの自然言語トリガーになる。中核は `SKILL.md` で、checker と任意の hook は Node 16 以上を要求し、サードパーティのランタイムパッケージは使わない。単独のタスクで試すなら `templates/gates-leaf.md` を `GATES.md` にコピーし、プレースホルダーを埋めてから `node <path-to-skill>/scripts/gate-check.mjs --status GATES.md` を実行する。このモードはコマンドを実行しない。実行まで進む場合は `CHECK:` 行がシェルコードそのものなので、呼ばれるスクリプトをすべて読んだうえで `--approve` を付けて実行する。機械的に弱い台帳のパターンは、非実行の `scripts/gate-lint.mjs` で検出でき、警告を失敗として扱いたいときは `--strict` を付ける。バージョンについては、現在のソースが `2.1.0` を対象としているが、README はこれをタグ付きの GitHub リリースとしては示していない。不変のインストールが必要なら正確なコミットを固定せよ、と書かれている。

証拠が証明できる範囲は、宣言したコマンドまで

このツールの最も実用的な記述は、限界についての部分にある。checker が証明できるのは、自分が宣言したコマンドの oracle だけだ。英語のタイトルと任意のシェルコードが同じ意味だと推論することはできない、と README は明言する。だから良いゲートには条件がある。成果が指す成果物やサービスを実際に読むこと。すべてのアサーションが通った後にだけ出る成功専用のマーカーを出力すること。不在を確認するチェックは、既知のポジティブコントロールに対して試すこと。供給された数値は `EXPECT:` に写すのではなく計測すること。結果の重い手動ゲートは、リスクに見合った証拠とともにレビューすること。もう 1 つ、証拠の束縛は鍵なしで行われるため、構造のずれは検出できても台帳の改ざんは検出できない。台帳を編集できる者は、正規化された証拠らしいものを偽造できる。`--status` と Stop はシェルを解決せずチェックも実行せずに定義のずれを検出するが、古い証拠は再実行ではない。親による検証には `--reverify` を使う。承認についても境界が明示されている。承認は同意であってサンドボックスではない。承認は呼ばれたスクリプト、フィクスチャ、依存関係、その他の推移的な入力まではハッシュしない。`--status` と Stop は記録された定義の束縛を検証するが、それらの成果物は検査しない。依存関係が変わったら再確認し、`--reverify` を実行する必要がある。

Windows の PATH とシェルの不一致は「成功」ではない

checker が使うシェルは、`--shell`、`UNLAZY_SHELL`、Node のプラットフォーム既定、の順に決まる。既定は Unix では `/bin/sh`、Windows では `process.env.ComSpec` とプラットフォームのフォールバックだ。チェックは起動時の環境を継承し、`PATH` もそのまま引き継ぐ。README がわざわざ節を割いているのが Windows の挙動で、Git Bash から起動した checker には見える Unix 風のツールが、PowerShell から起動した同じ checker には見えないことがある。`--shell` が変えるのはインタープリタだけで、`grep`、`tail`、`tr` などの外部プログラムをインストールするわけではない。だから移植性のある例は、リポジトリが持つ Node スクリプトを呼ぶ形になっている。親による再検証は、宣言されたシェルと必要なツールチェーンをそろえて行うべきで、シェルや PATH の不一致は解決すべき検証失敗であって、成功した証拠ではない。CI と開発機でシェルが違うチームにとっては、ここが最初に踏む落とし穴になる。

代替手段との違いは、合格条件を誰が書くか

同じ目的には、エージェントのフックでテストコマンドを実行させる方法や、既存のテストランナーに終了コードだけを判定させる方法がある。違いは、期待する出力を誰が、いつ書くかにある。テストランナーはテストコードの中に期待値を埋め込み、フックはイベントに紐づけて実行する。unlazy は期待値を台帳の `EXPECT:` 行として成果物の隣に置き、その定義そのものを SHA-256 で束縛する。テストを 1 行も足さずに、既存の検証スクリプトをゲートとして並べられる点が実務上の差になる。一方で、テストランナーが持つテスト間の分離や並列実行の制御は持たない。台帳は Markdown のチェックリストなので、ゲート同士の依存関係は人間が順序を守るか、親プロセス側で組み立てる必要がある。README にはオーケストレーションと並列作業の節へのリンクがあるが、提供された本文にはその中身が含まれていないため、並列時の挙動はここでは確認できない。

維持コストとライセンスの見取り図

checker と hook はサードパーティのランタイムパッケージを使わないと README にあり、Node 16 以上という条件以外の依存管理は発生しない。負担が増えるのはコードではなく台帳の側だ。ゲートを追加するたびに `CHECK:`、`EXPECT:`、必要なら `CWD:` を書いて承認を取り直し、依存関係を変えたら `--reverify` を回す。承認記録は台帳とゲート、コマンド、期待値、作業ディレクトリ、シェル、各種上限、プラットフォーム、`PATH` に紐づくので、CI の実行環境を変えると承認もやり直しになる。ライセンスは MIT で、これはソフトウェアの利用条件を定めるものであり、台帳や承認記録の扱いについて法的な助言を与えるものではない。バージョン面では、ソースが `2.1.0` を対象としているがタグ付きリリースとしては示されておらず、README 自身が不変のインストールが必要ならコミットを固定するよう求めている。変更履歴は `CHANGELOG.md` に未リリース分としてまとまっているという記述にとどまる。

編集部の結論

採用を検討すべきなのは、AI エージェントに複数ファイルをまたぐ実装を任せ、その完了報告を毎回手作業で検証しているチームである。逆に、単発の質問応答や、成果物がテキストの下書きだけで完結する用途には、GATES.md と承認記録の管理コストが見合わない。導入前に確認すべきは 3 点ある。第一に、チェック対象のリポジトリで Node 16 以上が動くこと。第二に、Windows なら Git Bash と PowerShell のどちらから checker を起動するかを決め、その PATH で検証用スクリプトが動くこと。第三に、--status で台帳を実行せずに検査し、--approve の前に CHECK 行が呼ぶスクリプトをすべて読むこと。承認はサンドボックスではないので、依存関係を変更したら --reverify を回す運用を先に決めてから入れるとよい。

公式情報源

1. Issues
2. Leonxlnx/unlazy on GitHub
3. License: MIT
4. README