- Codexとの対話は、ターンが増えるほど同じ履歴を送り直すので、累積のトークン消費がターン数の二乗に近い伸び方をします。
- そこでコンテクストを維持し続けるのをやめ、圧縮されることを前提に、再開に必要な最小状態だけをリポジトリ内の
memo/に置くことにしました。 - 置く情報は2種類だけです。変わりにくいプロジェクトの地図と、いま何が終わって次に何をするかという作業状態。
- ただし
memo/を正本にはしません。仕様の正本はdocs/、作業規則の正本はAGENTS.mdに置いたままにします。
1. 長い会話は、同じ話を何度も送り直している
Codexで長い作業をしていると、後半になるほど動きが重くなって、消費も増えていきます。
理由は単純でした。 言語モデルはターンごとに状態を持ち越しているわけではなく、毎回それまでの会話全体を読み直しています1。 1ターン目は自分の発言だけ、2ターン目は1ターン目の全部と今回の分、3ターン目はそのさらに全部。
つまり1ターンあたりの入力量が、ターン数に比例して増えていきます。 それを全ターン分足し合わせるので、累積の消費はターン数のおおよそ二乗で伸びる2。 20ターンの会話は10ターンの2倍ではなく、4倍近くになるという計算です。
そこで走るのが圧縮（compact：それまでの会話を要約して短い履歴に置き換える処理）です3。 これで入力量はいったん落ちますが、落ちるのは分量だけではありません。 「なぜその設計にしたのか」「どのファイルまで直したのか」といった、要約すると真っ先に削られる細部が消えます4。 そして次のターンで Codex は、消えた分をリポジトリの探索でやり直そうとします。
2. 忘れる前提で、再開地点をリポジトリに置く
だったら、コンテクストを長く保つ方向で頑張るのをやめようと思いました。 圧縮されるのは避けられないので、圧縮されたあとに短時間で戻れるようにする。 memo/ フォルダはそのために作ったものです5。
2.1. project-context.md には変わらないものだけを書く
1つめが memo/project-context.md です。 リポジトリ構成、アプリやモジュール間の境界、ビルドやテストの主要コマンド。 毎回調べ直す必要がなく、そう頻繁には変わらない情報だけを入れています。
ここは百科事典ではなく地図のつもりで書いています。 道路の混雑状況まで書き込むと更新が追いつかなくなるので、目的地までたどり着ければよい粒度で止める。 実際、詳しく書きたくなるたびに「これは docs/ に書くべきことでは」と引き戻しています。
2.2. 進行中メモは、いま何が終わって次に何をするか
もう1つが、作業対象ごとの進行中メモです。 このときは memo/nesprite-0.6.3-dev.md でした。 確定した判断、変更済みの箇所、未完了の作業、次にやること、検証結果。
こういう仕組みが必要になったのは、開発が短期間で連続して動いていたからです。 8月22日に一体だったアプリを Nesprite と Nescene に分離し、0.6.1では複数ファイル制作UIや外部フォルダ、参考画像まで広く手を入れました。 続く0.6.2では方針を変えて、編集対象を単一の .nesprite プロジェクトへ限定しています。 1週間前の判断がもう有効でないことがある。
なので Codex が読む順序も固定しました。 まず memo/project-context.md で地図を見る。 次に進行中メモで現在地を確認する。 それから、変更する箇所に直接関係する仕様書と実装だけを読む。 最初から grep でソースを探し回ったり、長大な dev-log を通読したりはさせません6。
3. memoを正本にしない
memo/ は便利なので、放っておくと仕様書と同じことを書き始めます。 そうなると docs/foo.md にはA、memo/current.md には古いB、実装はCという三重帳簿ができあがる。 これは避けたかったので、正本（source of truth：食い違ったときに最終的に正しいとみなす情報源）を最初に決めました。 仕様の正本は docs/、Agentの作業規則の正本は AGENTS.md。 メモと矛盾したら、必ずそちらを優先させます。
あわせて、確定した仕様をメモだけに残さないことも決めました。 対話の中で「ではこの方式で」と決まったものを進行中メモにだけ書くと、そのメモを整理した瞬間に根拠がなくなります。 検討中のうちは memo/ に置いてよい。 確定したら docs/ へ昇格させる。
古い記述を消すのもメンテナンスに含めています。 「A案を調査中」「B案に変更予定」「最終的にC案」の3つが同じ重さで並んでいると、次の Codex はどれが現在の判断なのかを推論し直さなければなりません。 dev-log は過去を消しませんが、再開用のメモは残すほど害になる。 ここはログとは逆方向の運用です。
書かないものも決めました。 /Users/ から始まる絶対パス、個人情報、たまたまクリップボードに入っていた内容。 再開用メモは繰り返し読み込ませる前提なので、一度書くと長く残ります。 そもそも必要なのは絶対パスではなく、リポジトリ内のどこを見るかという相対位置です。
4. 読ませるだけでなく、書き戻させる
読む手順だけ決めても、メモは自然には最新になりません。 なので作業の終わりに、今回確定したこと、変えた箇所、検証結果、未完了の作業、次の具体的な作業を進行中メモへ書き戻すところまでを1サイクルに含めました。 Codex に memo を読ませるのではなく、保守させる。
AGENTS.md のほうには詳細を書きませんでした。 書いたのは、長期作業の再開や圧縮のあとには memo/ を見ること、まずREADMEと project-context.md を読むこと、進行中メモがあれば読むこと、memoは正本ではないこと、詳しくは memo/README.md を見ること。 AGENTS.md は毎回必ず読ませるファイルなので7、ここが太ると圧縮対策をしている意味が薄れます8。 コンテクスト管理の詳細規則そのものを、段階的に読ませる形にしたわけです。
弱点もはっきりしています。 Codex が更新を忘れれば古くなるし、要約を間違えれば次回の初期認識ごと間違えます。 作業単位を細かく切ればメモが増え、1つにまとめすぎればまた巨大なコンテクストに戻る。
それから、この運用でトークンが何％減ったかは測っていません。 再探索を減らすことを狙って設計した、必要な情報だけを段階的に読ませる構造にした、というところまでが今言えることです。 効果の実感はありますが、数字で出すには比較のとり方から考える必要がありそうです。
覚えていてもらうのではなく、忘れたときにどこを見ればいいかを知っていてもらう。 そう決めてしまうと、書くべきものがだいぶ減りました。
- APIはステートレスなので、50ターン目には1〜49ターン目のすべてと、読んだファイルやツールの実行結果までを入力として送り直しています。 – What are tokens in Claude? Code session costs
- 累積入力トークンはN(N+1)/2という三角数の形になります。1ステップ1,000トークンの20ステップなら、単純計算の20,000ではなく210,000トークンです。 – AI Agent Loop Token Costs: How to Constrain Context
- OpenAIの解説によると、Codexは会話が auto_compact_limit を超えると、入力を小さな項目リストへ置き換えるcompactionエンドポイントを自動的に呼びます。初期の実装は手動の /compact コマンドでした。 – Codex エージェントループの展開
- 圧縮は要約である以上、情報の消失が起きます。Codex CLIでは任意のタイミングで /compact を実行することもできます。 – Codex CLIまとめ
- Anthropicはこれを structured note-taking と呼び、エージェントにNOTES.mdのようなファイルをコンテキストウィンドウの外へ書かせて、必要なときに引き戻す手法として説明しています。 – Effective context engineering for AI agents
- 必要な情報を必要なときに必要な分だけ読み込む設計は、Agent Skillsでも段階的開示（Progressive Disclosure）として中心に置かれています。 – Claude CodeのSkillsを作成例から徹底理解する
- AGENTS.mdは2025年8月20日にOpenAIが公開した、AIコーディングエージェント向けの指示を書くためのMarkdownフォーマットです。CodexのほかAmp、Jules、Cursorなどの開発チームと協力して作られました。 – AGENTS.mdとは？AIエージェント専用READMEの役割と使い方
- AGENTS.mdに詰め込みすぎると、ファイルが長くなるほど重要な指示を見落としやすくなります。長大な仕様書は別ファイルへ分けてリンクするのが無難とされています。 – AGENTS.mdとは？Codexにプロジェクト規約を守らせる設定と書き方