Codex CLIの長時間作業を安定させるAgent Ops設計

はじめに

Codex CLI を使い込むと、最初に悩むのは「どのモデルを使うか」です。
しかし、ソフトウェア開発や技術書執筆のような長時間作業では、モデル選定だけでは安定しません。実際には、profile、instruction、サブエージェントの役割分担、repository / worktree の配置方針、更新時の確認手順まで含めた運用設計が必要になります。

この記事では、Codex CLI を単発の対話ツールではなく、継続的に作業する AI エージェント基盤として使うために整備した Agent Ops 設計を紹介します。

先に結論

Codex CLI をソフトウェア開発や技術書執筆で長時間使うなら、重要なのは「どのモデルを選ぶか」だけではありません。

実運用では、次のような Agent Ops が必要になります。

• 作業目的ごとに profile を分ける
• profile ごとに instruction を固定する
• 親セッションとサブエージェントの役割を決める
• repository / worktree の配置を統制する
• Codex CLI 更新時に regression check する

この考え方を GitHub で再利用できる形にまとめました。

検証環境は Codex CLI 0.128.0、2026-05-07 JST 時点です。

なぜ Agent Ops が必要か

Codex CLI は、コード調査、実装、テスト、レビュー、ドキュメント作成までを一連の作業として進められます。

一方で、長く使うほど次の問題が出ます。

• セッションごとに作業方針がぶれる
• 長時間作業で目的や完了条件が曖昧になる
• サブエージェントを使いすぎる、または使うべき場面で使わない
• clone や worktree が意図しない場所に作られる
• 技術書執筆とソフトウェア開発で同じ振る舞いをしてしまう
• Codex CLI 更新時に、設定がまだ妥当か判断しにくい

これはモデル性能だけでは解決しません。

「単一の最強モデルを選ぶ」よりも、作業の型を決めることが重要です。

作ったリポジトリ

作成したリポジトリはこちらです。

構成は次のようにしています。

docs/
  quick-start.md
  operations-guide.md
  github-management-plan.md
  upgrade-checklist.md
examples/
  config.sample.toml
managed-files/
  instructions/
  bin/
  templates/
scripts/
  install-managed-files.sh
  sync-from-local.sh
  check-public-safety.sh

単なる設定例ではなく、運用に必要なものを一式にしています。

全体像

考え方は次の図に近いです。

目的
  ↓
profile
  ↓
instruction
  ↓
wrapper
  ↓
workspace policy
  ↓
再現可能な Codex CLI 作業フロー

profile だけを決めても不十分です。

profile に対応する instruction、起動方法、作業場所、更新確認まで含めて初めて安定します。

1. profile を目的別に分ける

同じ Codex CLI でも、ソフトウェア開発と技術書執筆では求める振る舞いが違います。

このリポジトリでは、例えば次のように分けています。

profile / wrapper	主用途	方針
codex-dev / software_dev	ソフトウェア開発	設計、実装、テスト、レビューまで扱う親セッション
software_dev_deep_impl	実装集中	コード変更、デバッグ、テスト修正に集中
software_dev_fastfix	小規模修正	lint、型、局所的修正など低リスク作業
codex-book / tech_book	技術書執筆	説明構成、用語統一、読者理解を重視
tech_book_review	技術書レビュー	原則 read-only で正確性と理解容易性を確認

ポイントは、モデル名を先に決めるのではなく、役割を先に決めることです。

モデルはその役割に割り当てます。

2. instruction を GitHub 管理する

Codex CLI の振る舞いは instruction に強く影響されます。

そこで、以下を GitHub 管理対象にしました。

managed-files/instructions/software-dev.md
managed-files/instructions/tech-book-authoring.md
managed-files/instructions/tech-book-review.md

例えば、ソフトウェア開発用 instruction では次のようなルールを入れています。

• 作業開始時に .codex-local/AGENT_MEMORY.md と TASK_LEDGER.md を読む
• active /goal があれば、それを主目的として扱う
• 小さな作業はローカルで処理する
• 複雑、長時間、高出力、並列調査向きの作業でサブエージェントを使う
• repository や worktree を作業ディレクトリ配下に閉じる
• test、lint、hook failure を証跡として扱う
• 最終回答に outcome、files changed、verification evidence、residual risks を含める

毎回同じプロンプトを貼るのではなく、運用ルールとして version 管理する方針です。

3. サブエージェントの使いすぎを防ぐ

サブエージェントは有効ですが、何でも分担すればよいわけではありません。

使うべき場面は、例えば次のようなものです。

• 複雑なコードパス探索
• 長時間の実装
• 高出力のテストやログ解析
• セキュリティ境界の確認
• レビュー観点の独立検証

逆に、数行の修正や、すぐ判断が必要な作業は親セッションで処理した方が安定します。

そのため instruction では、次の方針にしています。

小さく密結合な作業はローカルで行う。
複雑、長時間、高出力、並列化に向く作業だけサブエージェントを使う。

4. workspace policy で作業場所を固定する

長時間作業では、どこに repository や worktree が作られるかが重要です。

意図せず /tmp に clone されると、再開、監査、削除、差分確認が難しくなります。

そこで、次のような配置方針にしています。

用途	推奨パス
workspace 管理 repo	<workspace>/repos/<repo>
workspace 管理 worktree	<workspace>/worktrees/<repo>/<task>
single repo の作業 worktree	<repo>/.worktrees/<task>
agent local state	<workspace-or-repo>/.codex-local/
scratch	<workspace-or-repo>/.codex-local/tmp/

この方針を .codex-local/WORKDIR_POLICY.md と instruction の両方で明示します。

5. wrapper で起動方法を標準化する

毎回 codex -p ... -C ... を手で指定すると、profile や作業ディレクトリを間違えます。

そこで wrapper を使います。

managed-files/bin/codex-dev
managed-files/bin/codex-book
managed-files/bin/codex-init-workdir-policy

ソフトウェア開発:

codex-dev -C <repo-or-workspace>

技術書執筆:

codex-book -C <book-workspace-or-repo>

技術書レビュー:

codex -p tech_book_review -C <book-workspace-or-repo>

wrapper で .codex-local/WORKDIR_POLICY.md や必要なテンプレートを初期化するため、セッション開始時点から作業ルールが明確になります。

6. install / sync script を用意する

GitHub 管理しているファイルをローカルに反映するため、install script を用意しました。

./scripts/install-managed-files.sh
./scripts/install-managed-files.sh --apply

デフォルトは dry-run です。

実際にコピーする場合だけ --apply を付けます。既存ファイルがある場合は backup を作成します。

また、ローカルで調整した管理対象ファイルをリポジトリへ戻すための sync script も用意しました。

./scripts/sync-from-local.sh
./scripts/sync-from-local.sh --apply

ただし、実際の ~/.codex/config.toml は同期対象外です。

理由は、private path、project trust、account 固有の model availability などを含みやすいからです。

7. /goal を長時間作業の軸にする

長時間作業では、途中で目的が曖昧になります。

そのため、長い作業では /goal を使って目的と受け入れ条件を固定します。

例:

/goal ISSUE #123 を実装し、ローカルレビューとテストを通したうえで PR を作成する

instruction 側でも、active /goal がある場合は task ledger、plan、acceptance criteria と整合させるようにしています。

検証時点では goals は under development の feature でした。そのため、Codex CLI 更新時には codex features list で状態を確認する前提にしています。

8. 公開してはいけないものを決める

Codex CLI の設定を GitHub 管理する場合、最初に「公開しないもの」を決める必要があります。

このリポジトリでは、以下は管理対象外です。

• GITHUB_TOKEN などの認証情報
• ~/.codex/auth.json
• ~/.codex/sessions/
• 実際の ~/.codex/config.toml
• private repository 名を含む project trust 一覧
• 個別案件の .codex-local/TASK_LEDGER.md
• cache/、raw/、大量の生成物

公開前の補助として、軽量チェック script も置いています。

./scripts/check-public-safety.sh

これは完全な secret scanner ではありません。公開前の目視確認を減らすための補助です。

導入手順

最短手順は次のとおりです。

git clone https://github.com/ootakazuhiko/codex-cli-agent-ops-playbook.git
cd codex-cli-agent-ops-playbook
./scripts/install-managed-files.sh
./scripts/install-managed-files.sh --apply

その後、examples/config.sample.toml を参考に ~/.codex/config.toml を手動で調整します。

確認例:

codex --version
codex features list
codex-dev -C <workspace-or-repo> exec --skip-git-repo-check "Reply with OK only."

まとめ

Codex CLI を本格的に使うなら、重要なのは単発のプロンプトではなく、運用の型です。

特に次の 5 つを GitHub で管理すると、再現性と保守性が上がります。

• profile
• instruction
• wrapper
• workspace policy
• upgrade checklist

モデル性能が上がるほど、エージェントに任せられる作業範囲は広がります。

一方で、目的、作業場所、レビュー、証跡、更新確認を管理しないと、長時間作業の安定性は上がりません。

Codex CLI を「賢い対話相手」ではなく「継続的に作業するエージェント基盤」として使うなら、Agent Ops として設計する価値があります。