viettran-edgeAI/codex_workflow

codex_workflow – トークン効率的なCodexのエージェントオーケストレーション

概要

Pythonベースのワークフローパッケージで、Codex AIアシスタント（「Codex CLI/app」）を構造化されたマルチエージェント実行モードで拡張します。ユーザーはライト、ミディアム、ヘビーのルートを選択でき、それぞれがサブエージェント（Explorer、Investigator、Executor、Tester、Archivistなど）の起動数とコンテキスト共有方法を定義します。
ワークフローはプロジェクトレベルのメモリをagent_docs/フォルダに保存し、目標、アーキテクチャ決定、進捗ノート、引き継ぎサマリーをセッション間で保存します。

重要性

大規模言語モデルエージェントはトークンごとに課金されます。作業を専門のサブエージェントに委任し、結果をバッチ処理することで、codex_workflowはメインエージェントのトークン消費を削減しつつ、複雑なマルチステップタスクを可能にします。
カスタムオーケストレーションコードを書かずに、多くのプロジェクトで再利用可能な再現可能な「スウォーム」パターンを提供します。

クイックスタート（インストール）

ダウンロード GitHubのReleasesページから最新リリースのzipを取得。
提供されたSHA256SUMSファイルでダウンロードを検証。
アーカイブを解凍し、同梱のcodex_workflow/operate/bootstrap.mdの指示に従ってください（archivistサブエージェントを介してagent_docs/フレームワークを作成）。
Codexアプリを再起動。

任意のプロジェクトディレクトリから次のコマンドを実行できます：

codex_workflow --install   # そのプロジェクトのワークフローをセットアップ

要件 – Python 3.11以上と動作するCodex CLI/appのインストール。

ワークフローの使用方法

ルート	選択タイミング	機能
ライト	簡単なQ&A、クイックフィックス	追加のサブエージェントなし。メインのCodexエージェントが直接回答。
ミディアム	調査やドキュメントが必要だが、メインエージェントが実装/検証を行うべきタスク	Explorer（検索）、Investigator（深掘り）、Archivist（メモ取り）を起動。メインエージェントがコーディング/検証を実行。
ヘビー	大規模で学際的なプロジェクト（例：フロントエンドデザイン、3Dビジュアライゼーション、広範なテスト）	ミディアムスタックにExecutorとTesterを追加。メインエージェントはオーケストレーション、レポート統合、最終決定のみ。

ルート切り替え – Codexチャットで次のように入力：

use medium route. <タスクの説明>

または、mediumをheavyに置き換えてください。選択したルートは変更するまでアクティブです。

コマンド実行 – ワークフローには小さなCLIラッパーが付属しています：

codex_workflow --install      # 現在のプロジェクトをセットアップ
codex_workflow --check-update # 新しいリリースがあるか確認
codex_workflow --update       # ワークフローをアップグレード
codex_workflow --remove       # クリーンアンインストール
codex_workflow --version      # インストール済みバージョンを表示

コア機能

永続的なプロジェクトメモリ – agent_docs/が目標、アーキテクチャ、決定、進捗、引き継ぎを自動的に記録。
トークン認識バッチ処理 – 組み込みのヒューリスティック（v1.1.3以降）により、メインエージェントがワーカーを起動する頻度を制限し、繰り返しのコンテキストトークンを削減。
並列サブエージェント – 最大3つのワーカーが同時実行可能（Codexプラットフォームはセッションあたり合計4エージェントに制限）。
エビデンスリンク付きレポート – ワーカーは完全なログ/アーティファクトを参照する簡潔なサマリーを返し、メインエージェントのコンテキストを小さく保つ。
シニアエグゼキューターのフォールバック – 特に難しい問題には、より高容量のエグゼキューターが自動的に呼び出されます。
セッション終了時のトークン統計 – 各実行後に、各エージェントが使用したトークンの内訳を取得。
カスタマイズ可能なポリシーファイル – グローバル設定は~/.codex/AGENTS.mdに、プロジェクトごとのオーバーライドはagent_docs/と一緒に保存。

ベンチマークとパフォーマンス

リポジトリにはライトベンチマークが含まれており、バッチ処理ガイドラインがメインエージェントのキャッシュされた入力トークン（最大のコスト要因）を削減する方法を示しています。視覚分析（light_benchmark/analysis.png）とベンチマーク拡張の提案が提供されています。

制限と考慮事項

ワークフローはCodexプラットフォームの現在の4つの並行エージェント制限に依存します。プラットフォームの変更なしに大規模なスウォームは不可能。
ヘビールートタスクは、メインエージェントのロールアウトが削減されていても、より多くのサブエージェントがアクティブなため、全体でより多くのトークンを消費。
インストールプロセスでは、zipアセットの手動ダウンロードと検証が必要です。まだpipスタイルのインストーラーはありません。
トークン節約ヒューリスティックは著者の実験用に調整されています。LLMプロバイダーやモデルバージョンによって結果は異なる場合があります。

詳細情報

完全なアーキテクチャ、ライフサイクル、安全性に関する注意：workflow_breakdown.md
ベンチマークのアイデアと新しいテストの貢献方法：benchmarks/README.md
エージェントライフサイクルの詳細：codex_workflow/agent_lifecycle.md

結論 – codex_workflowは、Codexのパワーユーザーがクイックな回答から重量級の開発プロジェクトまで、マルチエージェントでトークン効率的なパイプラインを実行し、プロジェクト全体の知識ベースを自動的に維持できる、すぐに使えるオーケストレーションレイヤーです。