LazyCodexの使い方：Codexのプロジェクト記憶と検証フロー

十数個のファイルにまたがる機能を変更し、Codexが「完了」と報告したので信じたものの、本番環境で例外処理の漏れが見つかる。複雑なリポジトリでは珍しくない失敗です。新しい会話を始めるたびにagentはプロジェクトを理解し直し、変更後の要約には「何をしたか」が並んでも、見落とした境界条件までは示されないことがあります。

LazyCodexは、OmO（oh-my-openagent）のうちCodexに適合する機能を軽量なagent harnessとしてまとめたディストリビューションです。プロジェクト記憶、作業計画、証拠に基づく完了判定に重点を置いています。中核となるのは、階層型AGENTS.mdを作る$init-deep、計画を書く$ulw-plan、永続状態を使って実行する$start-work、検証まで回し続ける$ulw-loopです。

LazyCodexとは：OmOをCodex向けにまとめた軽量版

LazyCodexとCodexの関係は、設定済みディストリビューションと基盤となるエディターの関係に近いものです。中核機能はoh-my-openagent（OmO）から来ており、LazyCodexはCodexのプラグインシステムに適合する部分をパッケージ化します。GitHubプロジェクトのライセンスはMITです。2026年7月に本稿の事実確認を行った時点で、公式はOmO Ultimateの完全移植ではなく、OmOのCodex Light版と位置付けています。

素のCodexとLazyCodexの主な違い

観点	素のCodex	LazyCodex（Codex Light）
プロジェクト記憶	リポジトリ内の説明と現在のセッションからコンテキストを得る。深い初期化フローは標準では付属しない	$init-deepが階層型AGENTS.mdを生成し、複雑なディレクトリに局所的な指示を置く
完了条件	境界確認をどこまで行うかは、タスク指示とその実行時の習慣に左右される	$start-workの5つの証拠ゲートと$ulw-loopのoracle検証で完了条件を明示する
フローの規律	直接編集することも、利用者が計画先行の手順を設けることもできる	$ulw-planが計画し、$start-workが実行し、$ulw-loopが証拠のループを閉じる
進捗の永続化	プロジェクトファイルとCodexセッションが保持する情報に依存する	.omo/boulder.jsonが計画の進捗を保存し、Stop hookが未完了作業を継続できる
ツール層	現在のCodex環境にあるskills、MCP、並列機能を使う	OmOのrules、hooks、skills、LSP、AST検索、モデルルーティング設定を追加する

このharnessはCodexの基盤モデルを変更しません。プロジェクトのコンテキストを作り、計画し、実行し、証拠で検証するという使い方を定型化します。ただし、OmO Ultimateの完全なdiscipline agentオーケストレーションとteam_*ツールはCodex Lightには含まれません。LazyCodexが作業を分散できる範囲は、現在のCodex環境が提供するagent機能に依存します。

インストール：グローバル導入せずnpxを1回実行

LazyCodexの主要なインストール方法はnpxで、npm i -gは不要です。

# 標準インストール
npx lazycodex-ai install

# OmOパッケージとCodexプラットフォームを明示する等価コマンド
npx --yes --package oh-my-openagent omo install --platform=codex

# 非対話モードで自律権限も設定
npx lazycodex-ai install --no-tui --codex-autonomous

# インストール状態を確認
npx lazycodex-ai doctor

インストーラーはCodexのプラグインキャッシュと関連設定を書き込みます。標準の対話フローでは、自律権限を設定するか確認されます。--codex-autonomousは権限設定を変更するため、その端末のセキュリティ境界を理解したうえで使ってください。インストールや更新後はCodexの起動時レビューでOmO hooksを承認し、新しいセッションを開始してプラグインを再読み込みします。

最初に覚えるコマンドは4つです。

1. $init-deep：階層型AGENTS.mdコンテキストを生成する
2. $ulw-plan：依頼を承認待ちのdecision-completeな計画に変える
3. $start-work：進捗を永続化しながら計画を実行する
4. $ulw-loop：単一タスクの実行と検証を続ける

導入内容を先に確認したい場合はnpx lazycodex-ai doctorを実行するか、LazyCodex公式READMEと公式ドキュメントを確認してください。

プロジェクト記憶：$init-deepで階層型AGENTS.mdを生成

大規模リポジトリを一度の会話だけで正確に説明するのは困難です。数百のファイルと多数のモジュールがあると、新しいagentは探索をやり直すか、局所的な制約を知らずに編集することになります。

$init-deepは、そのリポジトリに目印を作ります。

1. リポジトリを走査し、プロジェクトの実際の動作を決めるファイルを読む
2. ルートと複雑なサブディレクトリに階層型AGENTS.mdを生成する
3. 局所的な指示を、それが適用されるコードの近くに置く
4. 後続のagentが編集前に適用ルールを読めるようにする

階層化が重要なのは、モジュール固有の指示を巨大なルートファイルに詰め込まず、そのモジュールの近くに置けるからです。agentが対象ディレクトリに入ったとき、リポジトリ全体のマニュアルから選別せずに関連ルールを確認できます。

この考え方はAgent記憶システムの設計と似ていますが、同じものではありません。AGENTS.mdは自動的に想起される会話記憶ではなく、バージョン管理されたプロジェクトコンテキストです。それでも、階層化、局所コンテキスト、永続化を重視する点は共通します。1つの設定ファイルでClaudeを制約する方法で扱ったCLAUDE.mdの役割にも近く、AIが動く前にルールを読ませます。

生成されたAGENTS.mdは通常のMarkdownであり、必ず確認が必要です。リファクタリング、ディレクトリ責務の変更、コマンド更新があったら、$init-deepを再実行するか手動で保守してください。自動生成されたコンテキストは、永続的に正しい事実源ではありません。

4つのコマンド：記憶、計画、実行、検証を分離

LazyCodexのフローは、プロジェクト記憶の初期化、計画、実行、検証の4つに分かれます。個別の開発タスクでは、後半3つが計画・実行・検証のサイクルになります。

$ulw-plan：計画を書いて承認を待つ

$ulw-plan "what to build"

このコマンドは製品コードを書かず、計画だけを行います。流れは次のとおりです。

1. 曖昧な表現をそのまま実装仕様にせず、質問して要件を明確にする
2. リポジトリを探索し、独立した検索を並列subagentに分配する
3. 現在のコードと目標の差分を分析する
4. 参照、受け入れ基準、QA計画、コミット境界を含むplans/<slug>.mdを書く
5. status: awaiting-approvalを設定し、承認を待つ

重要な制約は、計画が黙って実装に変わらないことです。まず範囲と受け入れ基準を決め、承認済み計画を実行段階に渡します。Subagentでタスクを分割する方法でも近い分解パターンを扱っていますが、LazyCodexはそれを計画フローに組み込みます。

$start-work：永続状態で計画を実行

$start-work [plan-name] [--worktree <absolute-path>]

このコマンドは、最上位のcheckboxがすべて完了するまで承認済み計画を実行します。主な特徴は次のとおりです。

1. 永続Boulder状態：.omo/boulder.jsonがturnやsessionをまたいで進捗を保持する
2. Stop hook：計画が未完了なら次の作業サイクルを注入する
3. 並列subagent：現在のCodex環境が対応していれば、独立したサブタスクを分散できる
4. 厳格なTDDと5つの証拠ゲート：計画の再読、自動検証、手動QA、対抗QA、クリーンアップ
5. 進捗台帳：実行過程とcheckboxの状態を記録する

すべて完了するとORCHESTRATION COMPLETEと表示されます。この表示は、すべてのcheckboxと証拠ゲートが完了したとワークフローが判断したことを示します。ただし、1行の状態表示だけを信頼せず、テスト、手動QA、変更の証拠を確認してください。

$ulw-loop：範囲の決まった単一タスクを検証まで継続

$ulw-loop "task" [--completion-promise=TEXT] [--strategy=reset|continue]

このコマンドは、範囲がすでに明確で、証拠が通るまで処理を続けたい単一タスクに向いています。完全な計画の代わりにはならないため、タスクが曖昧なら先に$ulw-planを実行します。

• 反復上限：ultraworkモードは最大500回、通常モードは最大100回
• 戦略：resetはループのコンテキストをリセットし、continueは現在の状態を引き継ぐ
• completion promise：収集する証拠、通過必須の確認、情報が不足した場合の処置を明記する
• 停止条件：oracleが証拠とcompletion promiseを照合して判断する

反復回数は品質保証ではありません。完了条件が曖昧なら、曖昧な判断を速く繰り返すだけです。テスト、境界条件、手動QA、失敗時の処置をcompletion promiseに含めることが重要です。

複雑なリポジトリで受け入れ確認が重要な理由

複雑なリポジトリで起きやすいのは、主経路がすぐ失敗することではありません。変更が十数ファイルに広がり、正常系は動いても、例外経路、呼び出し元、設定ファイル、ドキュメントのいずれかが古いまま残ります。問題はモデルの能力だけでなく、完了の定義に証拠がないことです。

よくある見落としは次のとおりです。

変更の種類	見落としやすい作業
主経路の変更	ネットワーク失敗、引数検証、権限エラーなどの例外経路
新しいインターフェース	古いシグネチャを使い続ける呼び出し元やtest double
モジュールのリファクタリング	テスト、設定、ドキュメント、生成物
機能の削除	依存する入口、analytics、ログ、移行用shim

LazyCodexは、見落としが絶対に起きないと保証するものではありません。実際の増分は、確認作業をワークフローに入れることです。5つの証拠ゲートは、計画の再読、自動検証、手動QA、対抗確認、クリーンアップを求めます。$ulw-loopは合意した証拠が満たされるまで、範囲の決まったタスクを進めます。完了はagent自身の要約ではなく、事前に定義した証拠との照合で決まります。

それでも、証拠ゲートにはプロジェクト固有の事実源と質の高い受け入れ基準が必要です。シグネチャ変更なら全呼び出し元を調べ、機能削除なら入口を調べ、UI変更なら単体テストだけでなく実際の操作を確認します。harnessは手順の規律を提供しますが、すべての業務リスクを自動で推測するわけではありません。

OmOのdiscipline agentとLazyCodexのskills層

LazyCodexはOmOから派生していますが、両者の機能範囲は分けて考える必要があります。OmO Ultimateは完全なdiscipline agentオーケストレーションを提供します。Codex LightはCodexのプラグインシステムに適合するコンポーネントだけを持ち込み、Codex自身のagent機能を利用します。

discipline agent：完全なオーケストレーションはOmO Ultimateの機能

agent	役割	LazyCodex Lightでの境界
Sisyphus	実行と検証の作業を編成する	役割設定が見える場合はあるが、LightにはOmO Ultimateの完全なagentオーケストレーションは含まれない
Hephaestus	リポジトリの変更を実装する	独立した作業は、現在のCodex環境が提供するsubagent機能で実行される
Oracle	証拠に基づいて完了を判断する	$ulw-loopは証拠検証の習慣を残すが、Ultimateの全オーケストレーションツールを提供するわけではない
Librarian	コンテキストを記録し、取得する	プロジェクト記憶は主に$init-deepと階層型AGENTS.mdで実現する

OmO UltimateのTeam Mode、完全なdiscipline agentチーム、team_*ツールをLazyCodex Lightの内蔵機能として数えてはいけません。並列メンバーを作成できるかどうかは、現在のCodex AppまたはCLIが提供する機能に依存します。

skills層：専門的な判断を再利用可能なワークフローに置く

LazyCodexは複数のskillsとコンポーネントをインストールします。現在の公式ドキュメントでは、代表的な機能として次が挙げられています。

skillまたはコンポーネント	用途
review-work	複数の観点から実装結果をレビューする
remove-ai-slops	挙動を変えず、テンプレート的なAI由来の痕跡を除く
frontend	フロントエンド設計とUI実装の制約を適用する
LSP	診断、定義、参照、renameなどシンボル単位の操作を行う
AST-grep	構文構造に基づいてコードを検索・書き換えする
rules / comment-checker	プロジェクトルールを読み込み、コメント品質を確認する
git-bash	Bash互換の動作が必要な環境に対応する

これはClaudeのSkill機能で扱った設計と似ています。コマンドがプロセスを担当し、skillが分野固有の判断を担当します。具体的なskill一覧はバージョンによって変わるため、固定リストではなく、Codexの$メニューまたはdoctor出力で現在の導入状態を確認してください。

モデルルーティング：タスクのリスクに応じて推論資源を割り当てる

LazyCodexはモデルルーティングを設定し、役割やタスクに応じてモデルとreasoning levelを使い分けられるようにします。目的はtoken節約の保証ではありません。公式ドキュメントも、計画、実行、検証に十分なモデル能力とコンテキストを投入すると説明しています。

より安全な運用原則は次のとおりです。

• 日常作業にはmediumの推論強度を使う
• 失敗コストが高い作業やレビュー重視の作業では推論強度を上げる
• 最上位の推論強度は本当に難しい作業に限定する
• 1つのthreadにコンテキストが集中しすぎる前に長いタスクを分割する

モデル名とルーティング表は変化します。導入済みの現在の設定を事実源にしてください。ある時点のREADMEにあるモデル名を長期運用へ固定せず、マルチモデルルーティングが常に利用量を減らすとも考えないほうが安全です。

LazyCodexを導入しなくても使える4つの考え方

LazyCodexをインストールしなくても、4つの設計思想は他のagentワークフローへ移せます。

考え方1：大規模リポジトリに階層型コンテキストを書く

$init-deepはAGENTS.mdを生成しますが、本質は大規模リポジトリにバージョン管理可能な階層型コンテキストを用意することです。

• すべてのルールをルートに詰め込まず、複雑なディレクトリに局所的な指示を置く
• agentがそのディレクトリに入ったとき、適用ルールを確認できるようにする
• リポジトリ構造やワークフローが変わったら指示も更新する
• 古い説明が新しい失敗原因にならないよう、生成コンテキストを確認する

最小構成は、ルートのAGENTS.mdと、制約の多い少数のサブディレクトリに置くAGENTS.mdです。1つの設定ファイルでClaudeを制約する方法でも近いパターンを紹介しています。

考え方2：計画と実行を分ける

範囲、依存関係、受け入れ基準、QA、コミット境界を含むdecision-completeな計画をagentに作らせ、実装前に承認します。重要なのはplans/*.mdというパスではなく、計画段階が黙って製品変更を始めないことです。

考え方3：完了を証拠に結び付ける

複数ファイルの変更には確認表を用意します。インターフェース変更後は呼び出し元、機能削除後は入口、UI変更後は実際の操作、データ移行後はrollback経路を確認します。文章による要約ではなく、テスト、手動QA、境界の証拠を完了条件にします。

考え方4：タスクのリスクに応じてモデルとコンテキストを割り当てる

簡単な問い合わせに最上位の推論強度は不要です。アーキテクチャ変更、移行、リリースゲートには強い推論とレビューが必要です。長いタスクは意図的に分割し、token budgetを増やすだけでは対応しません。

最小限の導入形

harness全体を入れたくない場合でも、次の2種類のファイルをバージョン管理してください。

1. 決定事項、手順、受け入れ基準、未決事項を記録する計画チェックリスト
2. リポジトリ全体と各ディレクトリのルールを記録する階層型AGENTS.md

変更の種類ごとに検証コマンドと手動QAのチェックリストを加えれば、LazyCodexの考え方のうち移植しやすい部分をすでに取り入れられます。

向いている人と向いていない人

LazyCodexはhooks、状態ファイル、skills、ワークフロー制約を追加します。すべてのプロジェクトに必要な層ではありません。次の表でトレードオフを確認できます。

シナリオ別の適合性

観点	LazyCodexが向く場合	素のCodexが簡単な場合
リポジトリ規模	ディレクトリ固有のルールが多く、複数ファイルの変更が頻繁な大規模リポジトリ	小規模リポジトリまたは単一ファイルのプロジェクト
タスクの複雑さ	計画、実行、検証が必要な長時間作業	単発の修正または簡単なスクリプト
コンテキスト問題	新しいセッションのたびにディレクトリとルールを探索し直している	1つのセッションで終わり、既存AGENTS.mdも明確
受け入れ確認	例外経路を見落としやすく、証拠ゲートと手動QAが重要	完了条件が単純で、確認コストも低い
プロセス要件	先に計画を承認し、実行状態を永続化したい	直接編集を優先し、追加の状態層は不要
権限への許容	hooks、MCP、自律権限の設定をレビューできる	追加プラグインやCodex設定の変更を避けたい

導入効果の判断

リポジトリが大きく、タスクが長く、受け入れ確認が厳しいほど、LazyCodexのプロセス制約は役立ちやすくなります。複数ファイルのリファクタリング、sessionをまたぐ作業、自動テストと手動QAの両方が必要な高リスク変更が代表例です。

コストも具体的です。階層型コンテキストを保守し、hooksと権限を理解し、.omo/boulder.jsonなどの状態ファイルを受け入れ、harnessが生成した計画と検証結果を確認する必要があります。インストールするだけで見落としを防げる自動保険にはなりません。

向いていないケース

• 単発の修正：1つの関数、1つのフィールド、短い文章の変更
• 簡単なスクリプト：1〜2ファイルに収まり、停止条件が明確な作業
• 既存フローが成熟している：信頼できるAGENTS.md、計画テンプレート、CI、手動受け入れゲートがすでにある
• 追加設定を望まない：プラグイン、hooks、MCP、自律権限で現在のCodex環境を変えたくない

判断に迷うなら、最初は完全インストールを見送っても構いません。階層型AGENTS.mdと証拠チェックリストを手動で追加します。それでもsessionをまたぐコンテキスト、計画実行、検証が繰り返し問題になるなら、LazyCodexを評価してください。

まとめ

複雑なリポジトリでCodexを使うとき、難しいのはコード生成だけではありません。新しいセッションに局所ルールを素早く理解させ、複数ファイルの変更が重要な境界をカバーしたと証明する必要があります。LazyCodexは$init-deep、計画承認、Boulder状態、証拠ゲートをCodex Lightのワークフローとして組み合わせます。

価値があるのはSisyphusやBoulderという名称ではなく、検証できる3つの変化です。コンテキストを階層型ファイルに保存し、計画と実行の境界を明示し、テストと手動QAで完了を判断します。同時に、LazyCodexはOmO Ultimateではなく、完全なagentオーケストレーションやTeam ModeをLight版の機能として扱うことはできません。

次の一歩として、npx lazycodex-ai doctorで環境を確認し、実際の大規模リポジトリ1つに$init-deepを実行してみてください。範囲の明確な複数ファイルのタスクを選び、$ulw-plan、$start-work、$ulw-loopで一巡させます。素のCodexで実行した場合と、見落とし、コンテキストの再読、受け入れコストを比較すれば、このharnessが自分のワークフローに必要か判断できます。