はじめに
本稿は 現状共有編の続編 です。
第1回はこちら：
前回は「課題を読む／ブランチを切る／デザインを探す／PR 下書きを作る」という儀式を、Backlog MCP と Figma MCP にまとめ、チケット番号ひとつで「課題取得→要約→タスク分解→作業手順→PR 草案」まで自動で回すところまで作りました。
ただし設計は Claude code 前提でした。巨大な md を入れ子で呼び出す構成だったため、codex CLI に持ち込んだ途端、運用が重くなりました。
この記事では、
- Claude code 前提設計のつらみ
- codex CLI 前提に作り直したときの落とし所
- prompts / skills を実際どこに置いてどう書いたか（最低限の設定含む）
をまとめています。
Claude code 前提設計のままではつらかったところ
-
スラッシュコマンドの入れ子前提
.claude/commands/dev-backlog.md などが、さらに別コマンドを呼ぶ設計
→ codex CLI では同じノリで自動実行できない -
巨大 md の増築
dev-backlog.md に「計画生成〜PR作成」まで全部入り
→ 修正のたびに複数ファイルへコピペ -
/commit や /test をプロンプトから自動実行したい野望
→ CLI は安全設計でユーザー確認必須、設計が破綻
結果として、
文章は立派、動作は人力
みたいな状態に陥りました。
codex CLI を前提にしたときの整理
やったことはシンプルです。
- 入れ子実行の発想を捨てる
- 共通処理を skills に集約する
つまり、
- prompt →「台本」（段取りを書く）
- skill →「中身」（具体手順を書く）
という役割分担に切り替えました。
prompts と skills の置き場所について（今回の構成）
今回の運用では、あえて場所を分けています。
-
prompts
→~/.codex/prompts/（ホームディレクトリ配下・CLIの共通置き場） -
skills
→ 各プロジェクトのリポジトリ直下 に.codex/skills/を置く
こうすることで、
- 台本（prompts）は共通化しやすい
- 具体手順（skills）はプロジェクトごとに変えられる
という住み分けができました。
「CLI に載せたい“進行台本”はホーム配下」
「プロジェクト依存のノウハウはリポジトリ配下」
という整理です。
prompts と skills の役割分担をどう決めたか
prompts（~/.codex/prompts/）
- フェーズごとの“進行台本”
- 例：dev-backlog.md、worktree-management.md
skills（<project-root>/.codex/skills/）
- 再利用可能な共通手順（ただしプロジェクト依存OK）
- 例：backlog-fetch、plan-generate、worktree-setup
台本には「順番と段取り」だけを書き、
具体的なコマンドや詳細説明は skills 側に寄せています。
実際の構成（今回の実ファイル配置）
ホームディレクトリ（共通 prompts）
~/.codex/
- prompts/
- dev-backlog.md
- dev-issue.md
- worktree-management.md
- test-runner.md
- commit.md
- pr-workflow.md
各プロジェクトのリポジトリ直下（skills）
<project-root>/.codex/
- skills/
- backlog-fetch/SKILL.md
- figma-fetch/SKILL.md
- plan-generate/SKILL.md
- worktree-setup/SKILL.md
- testing/SKILL.md
- pr-draft/SKILL.md
「prompts は共通」「skills はプロジェクトローカル」
という二層構成になっています。
prompt（台本）側はどう書いているか
例：~/.codex/prompts/dev-backlog.md
- ゴールを書く
- 進め方を書く
- 使う skills の名前を書く
書いているのは 段取りだけ です。
具体的な git / yarn コマンドは書きません。
skill（処理詳細）側はどう書いているか
例：<project-root>/.codex/skills/worktree-setup/SKILL.md
worktree-setup
目的
- チケットIDごとに git worktree を作成する
- feature ブランチを同時に作成する
実施内容
- ./ticket/{ID} に作業ディレクトリを作成
- base branch から feature/{ID} を作成
実行例
- git fetch
- git worktree add ./ticket/{ID} origin/develop -b feature/{ID}
ここでは
- なにをするスキルか
- どういうポリシーで作業するか
- 実行例（実行判断は人間）
という粒度にしています。
その代替としてやっている運用
-
prompts は ホーム配下に置く
→ CLI からどのリポジトリでも共通で呼べる -
skills は プロジェクト配下に置く
→ そのプロジェクトの事情に合わせて書き換えられる -
フェーズで分ける
- dev-backlog → 計画 & 環境準備
- 実装
- test-runner / commit / pr-workflow
というバトン渡し方式にしています。
チケット番号 1 つから始める、いまの開発フロー
-
/dev-backlog YORISO-1234
- backlog-fetch → 課題要約
- figma-fetch → 必要ならデザイン概要
- plan-generate → 3〜7 ステップ作成
- worktree-setup → 作業用 worktree 作成
-
実装は計画に沿って手動で進める
-
必要に応じて
- /test-runner unit
- /test-runner e2e
-
まとまったら
- /commit YORISO-1234
-
最後に
- /pr-workflow YORISO-1234
という流れです。
codex CLI ならではの制約にハマった具体例
- スラッシュコマンドの入れ子が動かない
- コマンド結果の自動受け渡しが難しい
- git / yarn を勝手に叩くのは危険
なので、
- 全自動はあきらめる
- 代わりに 判断コストを最小化する
という設計に舵を切りました。
巨大プロンプトからの脱出とメンテ性
以前
- dev-backlog.md に全部入り
- 共通処理を各所にコピペ
- 変更のたびに地獄
いま
- prompts はホーム配下の「流れだけ」
- skills はリポジトリ配下に集約
結果として
- 修正箇所が1つにまとまる
- 初見メンバーでも追いやすい
- プロンプトが痩せて読みやすい
というところまでは持っていけました。
実際にかかったコストと得られた効果
コスト
- 既存巨大 md の分割
- skills への移動
- 整合性の見直し
効果
- 何をすればいいか迷わない
- メンテが一気に楽になった
- 開発前の儀式が軽くなった
まとめ（次に手を入れたいところ）
-
skills の粒度をさらにそろえる
例：lint / e2e / VRT 専用化 -
情報引き継ぎのテンプレ化
計画ステップ / テスト結果 など
やってみた → 壊れた → 直した
という流れの中で、一番大変だったのは
入れ子依存を断ち切ること
でした。
それでも、
codex CLI で回せる “現実解”
には到達できたかな、という感触です。