エグゼクティブサマリー
この記事は、Codex CLI / Codex App を使っているうちに AGENTS.md、.codex/config.toml、Skills が増えてきて、「どこに何を書けばいいんだっけ？」となったときの整理メモです。
結論は、Codex活用の本質は「指示を増やすこと」ではなく、Codexに読ませる文脈を制御することです。共通ルール、開発用ルール、レビュー・管理用ルールを分けつつ、実ソースは1つに保つ構成にすると扱いやすくなります。
結論はこの4つです。
- 役割は分ける
- ソースは分けない
- 入口だけ分ける
- Codexに読ませる文脈は、必要最小限にする
結論
最終的には、python/src を本体にして、dev と manage を別の作業入口として分ける構成がよさそう。
python/
├── AGENTS.md
├── .codex/
│ ├── config.toml
│ └── skills/
├── src/
├── dev/
│ ├── AGENTS.md
│ ├── .codex/
│ └── src/ -> ../src
└── manage/
├── AGENTS.md
├── .codex/
└── src/ -> ../src
開発するときは python/dev を開き、レビューや設計整理をするときは python/manage を開きます。どちらから見ても src は同じ実ソースを指しているので、ファイルの二重管理はしません。
背景
Codexを便利に使おうとすると、自然に指示ファイルが増えていきます。
最初は AGENTS.md だけで十分でも、開発ルール、レビュー観点、命名規則、テスト方針、Skills、設定ファイルが増えてくると、Codexに毎回どこまで読ませるべきかが分かりにくくなります。
ここで大事なのは、「全部まとめて読ませる」のではなく、作業の入口ごとに読ませる文脈を変えることです。
補足：背景や課題感
困っていたことは、だいたいこのあたりです。
-
AGENTS.mdに全部書くと、常時コンテキストが重くなる - Skillsを増やすと便利だけど、発動条件が曖昧だとノイズになる
- 開発用の指示とレビュー用の指示が混ざると、Codexの動きがぶれる
-
src_devとsrc_manageのようにソースを分けると、どちらが正か分からなくなる - 成果物を早く作りすぎると、設計が定まる前に運用だけ増える
特に「実装したい日」と「構造を見直したい日」では、Codexに期待する人格がかなり違います。
実装の日は、既存コードに沿って小さく直してほしいです。レビューの日は、命名、責務、共通化、保守性を遠慮なく見てほしいです。この2つを同じ入口に混ぜると、けっこうしんどい。。。。
やったこと
まず、Codexが読むものを3種類に分けて考えました。
| 種類 | 役割 | 置く内容 |
|---|---|---|
| 共通レイヤー | どの作業でも守ること | プロジェクト概要、禁止事項、共通コマンド |
| devレイヤー | 実装するときの作法 | 小さく変更、既存規約優先、テスト追加 |
| manageレイヤー | レビュー・設計整理 | 命名、責務分離、共通化候補、保守性 |
そのうえで、ソースは1つだけにして、入口だけを分けることにしました。Windowsなら Junction を使うと、dev/src と manage/src から同じ python/src を見られます。
補足：検討過程や却下案
検討した中で、いくつかの案はやめました。
1つ目は、親ディレクトリに全部置いて、子ディレクトリで作業する構成です。これは一見きれいですが、親の AGENTS.md や Skills が常に混ざりやすく、開発用と管理用の文脈を切りにくいです。
2つ目は、src_dev と src_manage のようにソースを物理的に分ける構成です。これはすぐ破綻しそうでした。どちらが正なのか、どちらに反映済みなのかを人間が管理する必要が出ます。
3つ目は、Skillsを大量に作って、全部をCodexに見せる構成です。Skillsは便利ですが、description が曖昧だと必要ない場面でも候補に上がります。スキルは「増やす」より「発動条件を細くする」ほうが効きます。
Codexの読み方としては、作業ディレクトリに近い AGENTS.md ほど具体的な指示として効く、という前提で考えると整理しやすいです。なので、作業入口を dev と manage に分けるのはかなり相性がいいです。
最終形
最終形はこうです。
python/
├── .codex/
│ ├── config.toml
│ └── skills/
│ └── common-project-guide/
│ └── SKILL.md
├── AGENTS.md
├── src/
│ └── ...
├── dev/
│ ├── .codex/
│ │ ├── config.toml
│ │ └── skills/
│ │ ├── implement-small-change/
│ │ ├── add-unit-test/
│ │ └── refactor-local-code/
│ ├── AGENTS.md
│ └── src/ -> ../src
└── manage/
├── .codex/
│ ├── config.toml
│ └── skills/
│ ├── review-naming-rule/
│ ├── find-commonization-candidates/
│ └── review-maintainability/
├── AGENTS.md
└── src/ -> ../src
使い方はシンプルです。
- 実装するときは
python/devを開く - レビューや設計整理をするときは
python/manageを開く - 共通ルールは
python/AGENTS.mdに置く - 入口ごとのルールは
dev/AGENTS.mdとmanage/AGENTS.mdに置く - 手順化できる作業は Skills に逃がす
補足：構成・手順・注意点
Junction は、Windowsならこんな感じで作れます。
cd C:\work\python
mklink /J .\dev\src C:\work\python\src
mklink /J .\manage\src C:\work\python\src
Junctionは見た目はフォルダですが、中身は同じ実体を指しています。なので、dev/src/main.py を編集すれば、実際には python/src/main.py が編集されます。
削除だけは少し注意です。
rmdir .\dev\src
これは Junction の入口だけを消す用途です。一方で、del .\dev\src\main.py のように中のファイルを消すと、本体の python/src/main.py が消えます。ここは本当に気をつけたいところです。
Gitで管理するなら、入口側の src は .gitignore に入れておくと安心です。
/dev/src
/manage/src
AGENTS.md の分け方は、たとえばこうです。
# AGENTS.md
このリポジトリ全体の共通ルールです。
- 既存の設計を優先してください
- 秘密情報を出力しないでください
- 変更後は必要なテストを実行してください
# dev/AGENTS.md
ここでは実装作業を行います。
- 変更は小さく保ってください
- 既存コードの流儀を優先してください
- テストを追加または更新してください
# manage/AGENTS.md
ここではレビュー、設計整理、保守性確認を行います。
- 命名、責務、重複、共通化候補を見てください
- すぐに編集せず、まず観点を整理してください
- 大きな変更は提案として分けてください
まとめ
Codexを強くするには、指示をどんどん足すより、どの作業でどの文脈を読ませるかを決めるほうが効きます。
自分の中では、AGENTS.md は常時ルール、Skillsは必要時の手順書、dev / manage は作業モードの入口、という整理になりました。
まずはこの形にしておくと、あとからSkillsやレビュー観点を増やしても、プロジェクト全体がぐちゃっとしにくいです。