はじめに

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 として設計する価値があります。