codex-workflows

English | 简体中文 | 日本語 | Español | 한국어 | Português (Brasil)

規模の大きなプロダクト開発では、Codexがユーザーの求める範囲を越えて、技術的な一貫性を追い求めてしまうことがあります。あらゆるエッジケースを処理し、すべての経路を決定論的にしようとすると、合意した成果には不要なはずの変更が、ユーザーから見える挙動にまで及びかねません。

codex-workflowsは、作業を「合意した最小限の成果」の内側に収めます。変更してよいユーザー向けの挙動と、変えてはいけないものを明確にし、完了前には根拠を求めます。その境界内の実装詳細は、リポジトリを踏まえてCodexが可逆的な選択を行います。

ワークフローは、OpenAI Codex CLI向けのAgent Skillsとカスタムエージェントとしてインストールされます。メインのCodexセッションが、設計前にスコープと概算コストを確認し、進行管理とレビュー判断を担い、承認済みの作業を実装から独立検証まで進めます。

Codexをそのまま使うのではだめ？

範囲が明確な修正、使い捨ての検証、単発スクリプトなら、Codexを直接使うほうが適しています。求める結果と安全な実装範囲がすでにはっきりしている場合は、そのほうが速く、コストも抑えられます。

技術的な選択がプロダクトの範囲やユーザー向けの挙動を変えうる場合、あるいは判断を別のコンテキストへ引き継ぐ必要がある場合には、codex-workflowsを使ってください。

たとえば、既存の認証経路を拡張する依頼から、技術的にはきれいでも別の認証方式、より広いバリデーション、新しいレスポンス契約が生まれることがあります。フロントエンドが対応し、テストも通っていても、ユーザーには承認されていない挙動が提供されてしまいます。

codex-workflowsは、実行中を通してこうした拡大を抑えます。

このワークフローは、Codexを直接使う場合よりエージェント呼び出しとトークンを多く消費します。合意した成果を守る価値が、そのコストを上回るときに使ってください。

Codexが対応できるというだけで、エッジケースへの対応が必要になるわけではありません。追加のバリデーション、決定論的な挙動、新しい抽象化は、承認済みの要件や観測可能な契約を守るため、または実際に確認された不具合に対処するためのものでなければなりません。

実際のワークフロー例

mcp-imageへのBytePlus Seedreamプロバイダー統合では、18ファイルにまたがって3つ目の外部画像プロバイダーを追加しました。8つの計画済みタスクを通じ、プロバイダー固有の実装を発展させながら、公開MCPリクエスト、クライアント、ファイル保存、ファイルURIの各契約は変えませんでした。

マージ前に実サービスを使って評価し、最終的なモデルルーティング、プロンプト上限、タイムアウト、レスポンス処理を確定しました。独立レビューでは、上限のないファイル読み込み、バリデーションの迂回、ブロッキングするFIFOパス、APIキー正規化の不整合も発見されました。4件すべてを修正し、19ファイル・303件のテストに加え、リトライなしの実プロバイダー呼び出しにも合格しました。8つのタスクと4つの修正を通じ、承認済みの公開契約は維持されました。

クイックスタート

Node.js 22以降と、最新のCodex CLIが必要です。

インストールと実行

cd your-project
npx codex-workflows install

Codex CLIでレシピを呼び出します。

$recipe-implement JWTによるユーザー認証を追加する

$を付けるとスキルを明示的に呼び出せます。利用できるワークフローは、$recipe-まで入力すると確認できます。

目的に合う入口を選ぶ

仕組み

flowchart LR
    A[依頼] --> B[役に立つ最小限の成果を合意]
    B --> C{実装方針が1つに定まるか？}
    C -->|はい| S[直接タスクサイクルとセキュリティレビュー]
    S --> L[完了]
    C -->|いいえ| D[調査・設計・レビュー]
    D --> E[依存関係を踏まえて作業を計画]
    E --> F[実装範囲を承認]
    F --> H[タスクごとに実装・検証・品質確認・コミット]
    H --> K[独立したコードレビューとセキュリティレビュー]
    K -->|修正あり| H
    K -->|要件または主要設計が変更| B
    K -->|合格| L[完了]

どの経路を通るかは、ファイル数やCodexが見つけたエッジケースの数ではなく、独立したプロダクト判断・設計判断の数で決まります。

ADRを作るのは、現在のスコープに属し、長く残る選択で、かつ実質的に異なる案が2つ以上ある場合だけです。該当する選択が複数あれば、ADRをまとめてレビューします。統合テストやE2Eテストを選ぶのも、より安価なテストでは必要な連携を証明できない場合だけです。どちらも不要な変更もあります。

長期的に残すプロジェクト文書へ引き継ぐのは、プロダクトまたはリポジトリ実装に影響する判断だけです。第三者の承認、本番環境へのアクセス、リリース作業、無関係な運用作業が実装のゲートになることはありません。

実装範囲が承認されると、オーケストレーターがタスク、対象を絞った検証、該当するリポジトリチェック、タスクごとの実装コミットを実行します。問題はまず、承認済み文書とリポジトリの根拠に基づいて解決します。ユーザーから見える挙動はプロダクト上の境界であり、内部的な整合性のために実装側が勝手に変えてよいものではありません。オーケストレーターが確認を求めるのは、新しいプロダクト要件、承認済みの主要設計判断の変更、ユーザーだけが持つ権限、または未承認の不可逆操作が必要になったときだけです。

各専門エージェントには、範囲を明確にした担当作業、関連する文書とパス、求める結果を渡します。専門エージェントは担当作業を完了まで進め、メインセッションはプロダクトとワークフローに関する判断を担います。メインセッションが介入するのは、判断や具体的な行き詰まりへの対応が必要なときだけで、次のフェーズへ進む前に結果を検証します。これにより、専門エージェントの裁量を保ちながら、承認済みの成果を広げる権限までは渡しません。

新しいコンテキストへ判断を引き継ぐ仕組み

コンテキストを分けることで、調査・設計・実装・レビューの間で暗黙の前提が共有されるのを防ぎます。同梱のWork Planテンプレートでは、各実装タスクをDesign Docの該当箇所と受け入れ基準に結び付けます。

### P1-T1: エラーレスポンス契約を維持する

- **根拠**: `docs/design/example-design.md`、API契約、AC-2
- **対象範囲**: リポジトリ実装と、対象を絞ったテストを更新
- **依存先**: なし
- **検証**: 契約テストを実行し、文書どおりのレスポンス形式を確認

Task File Contractは、根拠、期待する結果、対象ファイル、実行可能な検証方法を実装フェーズへ渡します。テストが通っても重要な挙動を証明できないおそれがある場合だけ、Verification Focusを追加します。実行後は、コミット前にタスクの変更全体へ該当するリポジトリチェックをかけます。最終レビュアーは、完成したコードを承認済み文書と照合します。さらに、承認範囲を超えた実装や重大なコード品質上の問題がないかも確認します。修正を採用したあとの再レビューでは、その修正の影響を受ける項目に対象を絞ります。$recipe-quality-profileを実行すると、実装とレビューで参照するリポジトリ固有の品質ルールをdocs/project-context/quality.yamlに定義できます。

インストール

必要なもの

• Codex CLI（最新版）
• Node.js 22以上

インストール方法

現在のプロジェクトへインストールします。

cd your-project
npx codex-workflows install

次のファイルがプロジェクトへコピーされます。

• .agents/skills/: Codexスキル（基礎スキルとレシピ）
• .codex/agents/: サブエージェントのTOML定義
• 管理対象ファイルを追跡するマニフェスト

すべてのプロジェクトでワークフローを使うには、ユーザー単位のCODEX_HOMEへインストールします。

npx codex-workflows install --user

スキルは$CODEX_HOME/skills/、エージェントは$CODEX_HOME/agents/へインストールされます。CODEX_HOMEが未設定の場合は~/.codexが使われます。

エージェントをカスタマイズする

エージェント定義は通常のTOMLファイルです。プロジェクト単位でインストールした場合は.codex/agents/、ユーザー単位でインストールした場合は$CODEX_HOME/agents/のファイルを編集します。model、sandbox_mode、developer_instructionsを変更できます。編集したファイルは、後述のとおりアップデート時にも保持されます。

更新

# 変更内容を確認
npx codex-workflows update --dry-run

# 更新を適用
npx codex-workflows update

# ユーザー単位のインストールを更新
npx codex-workflows update --user

ローカルで編集したファイルは、アップデート時にも保持されます。各ファイルをインストール時のハッシュと比較し、変更済みのものは更新をスキップします。バージョンごとの更新履歴に沿って移動と削除を順番に適用するため、ローカル変更は移動後のファイルにも引き継がれます。代替なしで廃止された変更済みファイルは、.codex-workflows-preserved/<version>/へ移動します。新しいファイルは自動的に追加されます。

# インストール済みバージョンを確認
npx codex-workflows status

# ユーザー単位のインストールを確認
npx codex-workflows status --user

ワークフローレシピ一覧

Codexでは$recipe-nameでレシピを呼び出します。$recipe-まで入力し、タブ補完を使うと利用可能なレシピを確認できます。

作業状態

レシピは、Work Plan、実装Task File、一時的なレビュー修正・テスト追加用Task Fileの作業領域としてdocs/plans/を使います。品質確認を通過した実装コミットごとにタスクとフェーズの進捗が更新されますが、進捗ファイル自体はそのコミットに含まれません。一時ファイルもレビュー対象にしたい場合を除き、プロジェクトの.gitignoreに次を追加してください。

docs/plans/

PRD、ADR、UI Spec、Design Docは長期的に残すプロジェクト文書であり、コミット対象です。

同梱のガイダンス

レシピは、現在のタスクに必要な、リポジトリの状況を踏まえたガイダンスを読み込みます。通常、これらのスキルを直接選ぶ必要はありません。

専門エージェント

レシピの実行中、Codexが必要に応じて次のエージェントを起動します。事前に役割を覚える必要はありません。オーケストレーターがワークフロー全体を管理し、レシピが分野に応じて担当エージェントを選びます。各エージェントは個別のコンテキストで、専門的な指示と明示された必須スキルに従って動作します。

プロジェクト構成

インストール後、プロジェクトには次のファイルが追加されます。

your-project/
├── .agents/skills/           # Codexスキル
│   ├── coding-rules/         # 基礎ガイダンス
│   ├── testing/
│   ├── ai-development-guide/
│   ├── reviewee-judgment/
│   ├── documentation-criteria/
│   ├── requirement-convergence/
│   ├── implementation-approach/
│   ├── integration-e2e-testing/
│   ├── external-resource-context/
│   ├── llm-friendly-context/
│   ├── task-analyzer/
│   ├── subagent-delegation/
│   ├── subagents-orchestration-guide/
│   └── recipe-*/             # ワークフローの入口（$recipe-*）
├── .codex/agents/            # サブエージェントのTOML定義
│   ├── requirement-analyzer.toml
│   ├── technical-designer.toml
│   ├── ui-analyzer.toml
│   ├── task-executor.toml
│   └── ...（全26エージェント）
└── docs/                     # レシピの利用に応じて作成
    ├── prd/
    ├── design/
    ├── adr/
    ├── ui-spec/
    └── plans/
        └── tasks/

エコシステム

Nautilusはプロダクトのアイデアを検証してPRDにまとめ、linear-prismは承認済みの要件を実装可能なLinearのissueへ整理します。claude-code-workflowsは同じアプローチをClaude Code向けに提供し、codex-workflowsと同じプロジェクトにインストールできます。

Astraを効率よく使いたい場合

ワークフロー全体をAstraで走らせると、利用枠をすぐ使い切ります。codex-subagent-playbookはサブエージェントごとにモデルを選ぶCodexプラグインで、結果に差が出る場面だけでAstraを使えます。

codex plugin marketplace add shinpr/codex-subagent-playbook

[[skills.config]]
path = "/Users/you/.codex/skills/subagent-delegation/SKILL.md"
enabled = false

[[skills.config]]
path = "/absolute/path/to/your-project/.agents/skills/subagent-delegation/SKILL.md"
enabled = false

設計の背景

ライセンス

MIT License。利用、変更、再配布は自由です。

@shinprが開発・メンテナンスしています。