Codexを使い始めて長時間稼働させるまで

こんにちは、データマネジメント部でデータエンジニアをしています。山城です。

Claude Codeがリリースされて早くも一年ちょっとが経ちました。恥ずかしながら今まで碌に使っていなかったので、ここ二か月ほどCodexをメインに使いながら設定を行っています。
公式からリリースされた機能についてまとめた記事などは色々確認できるのですが、具体的な設定やファイルの中身などはあまり見かけないので、整理がてら記事にしていこうと思います。

今回は設定したものの中でも、ある程度放置でも長時間実行できる環境にするための環境整備について書きます。理由はとても単純で、使っていくと投げたいタスクの粒度がだんだん大きくなり、権限もデフォルト権限で動かしていたこともあり承認を求められることも増えてきて面倒になったからです。多分リリースから使っていた人たちも同じような流れを辿ったんだろうな…と感じています。

設定前の知識と状態

設定前のAI Agentの使い方や知識について簡単にまとめます。といってもGitHub CopilotやCopilot Chatなどを利用していたときで止まっていたので、できることや知識もそこまでで止まっていました。

使い方

• ファイルの変換
  • json → yaml
  • json → テーブルのスキーマ作成
• 同じリポジトリ内の他コードを参考に大体同じ設計でコードを作る

知識

• とりあえずPlanモードで始めるのが良いらしい
• MCPまでは追いかけていたけど、Skills？なんだそれは

長時間実行でほしかったもの

個人的には長時間承認無しで動いてくれればなんでもいいと思っていたのですが、Codexに何が必要か確認をしながら進めたところ下記の要素が必要だと言われたので順次整備していきました。

• 調査、実装、検証の役割を混ぜない
• 作業中の現在地をファイルに残す
• 各リポジトリの検証コマンドでCodexが迷わない
• 危ないコマンドを自動実行しない

実際に設定したもの

今回設定したものは次の通りです。

~/.codex/AGENTS.md
~/.codex/rules/long-running-workflow.md
~/.codex/rules/checklists/research.md
~/.codex/rules/checklists/implementation.md
~/.codex/rules/checklists/ci-fix.md
~/.codex/rules/command-policy.rules
~/.codex/templates/agent-run.md
~/.codex/templates/repo-agents.md
~/.codex/skills/bootstrap-repo-codex/

それぞれ下記のような役割です。

ファイル	役割
~/.codex/AGENTS.md	Codexが最初に読む個人共通ルール
long-running-workflow.md	長時間作業の進め方、停止条件、再開手順
research.md	調査用チェックリスト
implementation.md	実装用チェックリスト
ci-fix.md	CI修正用チェックリスト
command-policy.rules	sandbox外実行の承認ルール
agent-run.md	作業メモの雛形
repo-agents.md	リポジトリごとの AGENTS.md 雛形
bootstrap-repo-codex	リポジトリ固有のCodex運用ファイルを作るskill

AGENTS.md

下記の文言を ~/.codex/AGENTS.md へ追記します。
内容としては役割とタスクの分割、途中に作業メモを残しながらやるように指示しています。

また、途中のメモ以外にもファイル変更を伴う依頼では明示がなくても最後にコミットをするようにして、長時間作業の最後を曖昧にしないようにしています。

~/.codex/AGENTS.md

# Global working rules

## Delegation policy
- 調査と実装を同じ agent に抱え込まない。

## Long-running work
- 長時間の調査、実装、CI修正では、必要に応じて `~/.codex/rules/long-running-workflow.md` を読む。
- 作業の目的、現在地、次の一手、検証結果を active run note に残す。
- 実装前に調査結果を分けて記録し、実装中に前提が変わったら run note を更新する。
- 完了前に対象repoの `AGENTS.md`、README、Makefile、package/pyproject設定から検証コマンドを確認して実行する。
- 破壊的操作、外部公開、deploy、大きな依存更新、認証情報に触れる変更は人間の承認を取る。

## Personal Codex references
- 長時間ワークフロー: `~/.codex/rules/long-running-workflow.md`
- 調査チェックリスト: `~/.codex/rules/checklists/research.md`
- 実装チェックリスト: `~/.codex/rules/checklists/implementation.md`
- CI修正チェックリスト: `~/.codex/rules/checklists/ci-fix.md`
- run note雛形: `~/.codex/templates/agent-run.md`
- repo用AGENTS雛形: `~/.codex/templates/repo-agents.md`

長時間ワークフロー

詳細な進め方は ~/.codex/rules/long-running-workflow.md に分けました。

ここでは、いつこのワークフローを使うかを明確にしています。

~/.codex/rules/long-running-workflow.md

## When to use

- 30分以上かかりそうなコード実装
- 大きなコード調査やリサーチ
- CI失敗の調査と修正
- 複数repoや複数サブシステムにまたがる作業
- 中断、再開、引き継ぎが起こりそうな作業

さらに、長時間作業を次の3つに分けています。
調査しながら実装すると、途中で前提が変わったときに「なぜこの変更をしたのか」が分からなくなります。そこで、単一セッションで進める場合でも、run noteの中で Research、Implementation、Verification の節を分けるようにしています。

Research
  既存実装、仕様、ログ、依存関係、関連ファイルを読む。
  コード変更はしない。

Implementation
  調査メモを前提に、最小差分で変更する。

Verification
  lint、typecheck、test、build、CI結果を確認する。

active run note

作業中のメモです。作業ごとに、目的、現在地、次の一手、検証結果をファイルに残します。 ~/.codex/templates/agent-run.md を雛形にするようにしています。

~/.codex/templates/agent-run.md

# Agent Run: <task-name>

## Goal

<何を達成するか>

## Scope

- In scope:
- Out of scope:

## Research

### Relevant files

- 

### Findings

- 

## Implementation Plan

- 

## Changes

- 

## Verification

- Format:
- Lint:
- Typecheck:
- Test:
- Build:
- CI:

## Current State

- 

## Next Step

- 

チェックリスト

調査、実装、CI修正は、それぞれ見るべきものが違うのでチェックリストを作りました。

~/.codex/rules/checklists/research.md
~/.codex/rules/checklists/implementation.md
~/.codex/rules/checklists/ci-fix.md

research.md には、実装前に見るものをまとめています。
implementation.md では、既存変更を戻さないこと、最小差分で実装すること、差分を読み返すことを明示し、 ci-fix.md ではCIログを読んで原因分類してから修正する流れにしています。

まとめていて思ったのですが、各役割でモデルや権限なども調整するべきだと感じています。

~/.codex/rules/checklists/research.md

- 依頼内容を一文で言い換える
- 対象repo、cwd、関連ディレクトリを確認する
- `AGENTS.md`、README、設定ファイルを読む
- 関連ファイルを `rg` / `rg --files` で探す
- 既存の設計パターン、命名、テスト方針を確認する
- 直近の変更や未コミット差分を確認する
- 調査結果、前提、未確定事項を run note に書く

各リポジトリの設定を作るskill

リポジトリ固有のCodex運用ファイルを作るために bootstrap-repo-codex というskillも作りました。

このskillの役割は、作業リポジトリを見て作業メモや検証スクリプトの雛形を作ることです。
ただ、scripts/check.sh は検証コマンドが明確なときだけ作るようにしました。適当に npm test や make test をでっち上げると、長時間作業の最後に壊れた完了判定を使うことになるからです。

<repo>/AGENTS.md
<repo>/docs/agent-runs/
<repo>/docs/agent-runs/README.md
<repo>/scripts/check.sh

コマンド承認ルール

最後に整備したのが、~/.codex/rules/command-policy.rules です。

これは Markdown の運用メモではなく、Codexがsandbox外でコマンドを実行してよいかを判定する .rules ファイルです。
詳細は公式ドキュメントを参考にしてください。

default.rules に最初から許可していた一部ルールがありましたが、空に近い案内コメントだけにして自分で管理するルールは command-policy.rules にすべて移管しました。

~/.codex/rules/command-policy.rules

# Personal command policy rules.
#
# These rules were moved from default.rules so manually maintained command
# approvals live in one place.

prefix_rule(pattern=["uv", "run", "pytest", "-q"], decision="allow")
prefix_rule(pattern=["uv", "run", "mypy"], decision="allow")
prefix_rule(pattern=["uv", "run", "ruff", "check", "."], decision="allow")
prefix_rule(pattern=["git", "add"], decision="allow")

allow にしたもの

とりあえずローカル検証や安全寄りの確認コマンドを中心に承認なく動くようにしました。開発するときにはPythonが多いのでそれに関連するものと、git/gh関連の一部も許可しています。

prefix_rule(pattern=["uv", "run", "pytest", "-q"], decision="allow")
prefix_rule(pattern=["uv", "run", "mypy"], decision="allow")
prefix_rule(pattern=["uv", "run", "ruff", "check", "."], decision="allow")
prefix_rule(pattern=["git", "add"], decision="allow")
prefix_rule(pattern=["git", "commit"], decision="allow")
prefix_rule(pattern=["gh", "issue", "list"], decision="allow")
prefix_rule(pattern=["gh", "issue", "view"], decision="allow")
prefix_rule(pattern=["gh", "issue", "create"], decision="allow")
prefix_rule(pattern=["gh", "pr", "view"], decision="allow")

forbidden にしたもの

Codexが戻せない操作をしないように破壊的なファイル変更や、外部へのファイル送信系はとりあえず拒否しています。

forbidden

prefix_rule(
    pattern=["git", "push"],
    decision="forbidden",
    justification="This is a destructive remote-changing operation and must not be run by Codex.",
)
prefix_rule(
    pattern=["git", "reset", "--hard"],
    decision="forbidden",
    justification="This is a destructive change that discards local work and must not be run by Codex.",
)
prefix_rule(
    pattern=["git", "clean"],
    decision="forbidden",
    justification="This is a destructive change that removes untracked files and must not be run by Codex.",
)
prefix_rule(
    pattern=["git", "checkout", "--"],
    decision="forbidden",
    justification="This is a destructive change that can discard file edits and must not be run by Codex.",
)
prefix_rule(
    pattern=["git", "restore"],
    decision="forbidden",
    justification="This is a destructive change that can discard file edits and must not be run by Codex.",
)
prefix_rule(
    pattern=["rm", "-rf"],
    decision="forbidden",
    justification="This is a destructive filesystem change and must not be run by Codex.",
)
prefix_rule(
    pattern=["rm", "-fr"],
    decision="forbidden",
    justification="This is a destructive filesystem change and must not be run by Codex.",
)
prefix_rule(
    pattern=[["npm", "pnpm", "yarn"], "publish"],
    decision="forbidden",
    justification="This is a destructive publishing change and must not be run by Codex.",
)
prefix_rule(
    pattern=["gh", "release"],
    decision="forbidden",
    justification="This is a destructive release-changing operation and must not be run by Codex.",
)

prompt にしたもの

prompt

prefix_rule(
    pattern=["gh", "pr", "create"],
    decision="prompt",
    justification="This creates a remote pull request and should require explicit user approval.",
)
prefix_rule(
    pattern=["gh", "pr", "merge"],
    decision="prompt",
    justification="This mutates a remote pull request and should require explicit user approval.",
)
prefix_rule(
    pattern=["npm", "install"],
    decision="prompt",
    justification="This may download dependencies and change lockfiles, so it should require explicit user approval.",
)
prefix_rule(
    pattern=["uv", "sync"],
    decision="prompt",
    justification="This may download dependencies and change environments, so it should require explicit user approval.",
)
prefix_rule(
    pattern=["docker", "compose", "up"],
    decision="prompt",
    justification="This can start long-running local services, so it should require explicit user approval.",
)
prefix_rule(
    pattern=[["python", "python3"], "manage.py", "migrate"],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)
prefix_rule(
    pattern=["uv", "run", ["python", "python3"], "manage.py", "migrate"],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)
prefix_rule(
    pattern=["alembic", ["upgrade", "downgrade"]],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)
prefix_rule(
    pattern=["uv", "run", "alembic", ["upgrade", "downgrade"]],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)
prefix_rule(
    pattern=["npx", "prisma", "migrate"],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)
prefix_rule(
    pattern=["npm", "run", "migrate"],
    decision="prompt",
    justification="This runs database migrations and should require explicit user approval.",
)

今後の課題

現状ここまで設定を行いました。
毎回承認を求めてきたりせずに1時間くらいの処理を投げることができています。というか投げたタスクが1時間くらいで終わってしまったので実際どこまで動くのかは分からないです。
そこの検証も含めて、下記の内容が今後整備する対象だと感じています。

• 作業の役割ごとの権限制御
• 長時間動いた場合、セッション・作業メモの評価をしてみたい
• 設定を作ったはいいけど自前PCと仕事用PCの間で簡単に共有できるようにしたい
  • リポジトリで管理するなど

まとめ

今回はCodexを放置して長時間動いてもある程度戻ってこられるための設定についてまとめました。
AI Agentを使い始めて二か月ほどですが、ようやく世間の今年のはじめくらいの感覚に追いついたと思います。

具体的な設定内容は、次の3つです。

• ~/.codex/AGENTS.md から個人用の長時間ワークフローへ戻れるようにする
• リポジトリごとにrun note、検証コマンド、AGENTS.md を作れるskillを用意する
• command-policy.rules で allow、prompt、forbidden を明確に分ける

また、今後は作成した設定やskillを他マシンへ共有できる状態にしていきたいと思います。