AI new
Codexによる並列開発を目指したディレクトリ構造の準備
はじめに
お久しぶりです。ヨシです。AI活用ブログ記事シリーズの第三弾です。
昨今、Codexなどの生成AIのCLIツールを利用した並列開発が流行っていますが、今回は並列開発に向けた準備として行っていることについて語りたいと思います。本格的な並列開発についてはとある事情からまだ行えていませんが、その準備として何をやっているかについて解説します。
なお、今回対象とするプロジェクトは非モノレポ（ポリレポ）構成における並列開発を前提としています。
また、そのような流れからCLIやターミナル周りの仕組みを強化するモチベーションが湧いており、今回の記事では、私が行っているCodexを活用したプロジェクトのドキュメント運用についてまとめ、ディレクトリの分割思想やターミナルマルチプレクサ／lazygitとの連携などについても解説します。
プロジェクトディレクトリの全体構造
まず、プロジェクト全体のディレクトリ構造について語りたいと思います。現在私がアサインされているプロジェクトでは複数のリポジトリが存在しており、それらをまとめて一つのディレクトリに配置することにしています。
以下のように、ルート直下に各リポジトリを包むラッパーディレクトリを配置し、その中ではgit worktreeで並列展開できるようにしています。
.
├── AGENTS.md # プロジェクト全体についてのAGENTS.md
├── docs # ドキュメント専用リポジトリ
├── proj-1-repos # 配下に同一のリポジトリのworktree展開
│ ├── proj-1-main
│ ├── proj-1-sub
│ └── proj-1-third
├── proj-2-repos
└── proj-3-repos
このような配置では以下のような目的のもとで運用を行っています。
- 人間とCodexが同時に作業しても衝突しづらいよう、
*-repos配下に*-mainと*-subなどを用意して必要分だけworktreeを増設できます - ルートから横並びの構造にしているため、tmuxやZellijでタブを切り替えるだけで関連リポジトリへ即アクセスできます
それでは、このディレクトリの運用についていくつかの観点で詳しく解説していきたいと思います。
Codex生成ドキュメントの管理
まず、Codexを使う上では特にドキュメントを多く生成させるようにしています。ソースコードの変更後に何をどのような目的で修正したかや、既存のコードベースのパターンの解析などを行わせて知識層として蓄えさせて、人間側もこれらの知識層にアクセスして読み込み、共同でドキュメントの開発・保守をできるようにさせています。
また、運用しているドキュメントのディレクトリは docs という名前で単体でリポジトリとして管理するようにしています。これによってどのポイントでどのような差分が作成されたかを確認しつつ管理できるようになります。ソースリポジトリと分離しているので、リポジトリを横断してCodexが生成する分析メモやADRを安全に共有できます。
このドキュメントリポジトリには他に以下のような特徴があります。
- ドキュメントリポジトリ内部には
analysis/,problems/,specs/など用途別ディレクトリを用意し、Codexが出力したMarkdownには必ずYAMLフロントマターを付けて履歴と責任者を明記します。 - ドキュメントはルート直下から常に同じパスで参照できるため、複数のworktreeやセッションから同じ文書にアクセスして差分を比較しやすいです。
git worktreeでの並列開発パターン
次に、少し前から話題になっている git worktree での並列開発を目指して以下のようにソースコードのリポジトリを運用することにしました。 worktree用にディレクトリを以下のような構造としています。
.
├── proj-1-repos # 配下に同一のリポジトリのworktree展開
│ ├── proj-1-main
│ ├── proj-1-sub
│ └── proj-1-third
- ベースリポジトリを
*-mainに固定し、安定版のブランチを保持します。 - Codexや別メンバーが試験的な変更を行う際は
*-subのような追加worktreeを生やし、同一ブランチや別ブランチを柔軟に切り替えます。
実は後で語るlazygitを使うことでworktreeの作成や切り替えを非常に楽に行うことができます。
ZellijとCodexの連携
Codexそのもの起動についてですが、CodexはZellijというツールのペイン上で稼働させています。Zellijのレイアウトを通じて、左ペインでCodex CLI、右ペインでdocsやproj-mainの編集を並列表示できます。ウィンドウを即座に分割・リサイズできるため、長時間の生成タスクを走らせつつ別タスクのログやビルド状態を観察するのが楽です。また、デフォルトでセッションを保持したまま再起動時に引き継げる点なども、並列開発と相性が良いです。
Zellijについては以前に以下の記事で解説しました。CLI系ツールを使っていく上では初学者にはtmuxよりも使いやすくオススメです。
https://nextat.co.jp/staff/archives/380
lazygitによる差分確認フロー
少し触れましたが、ターミナルを離れずにdocsの差分を確認できるよう、ZellijのタブにlazygitというTUIのgitクライアントツールを常駐させています。 lazygitを使うことで以下のような利点があります。
- Codexが出力したMarkdownは即座にステージングして、プレビューやdiffをワンキーで見直せる
- リポジトリ切り替えもキーバインドだけで行えるので、
proj-mainで実装を確認→docsでドキュメント修正→再びコード側に戻る、というサイクルが速い
現在の問題点
現状の問題点として、git worktreeで例えば複数の proj-1-repos を立ち上げたままDocker環境を並列稼働させようとすると、ホスト側のポート競合が頻発します。proj-1-repos/proj-1-main/docker-compose.yml では nginx、mysql、minio などがすべて静的にマッピングされており、環境変数一つでポート帯を切り替える仕組みがありません。そのため、別worktree用にポートをずらしたい場合は compose ファイルを直接書き換えるか、複数の .env を手動で差し替えるしかなく、CI設定やCodexの再生成時にも差分が出てしまいます。
一つの案としては PORT_OFFSET のような単一の環境変数を定義し、ポートを 13306 → ${PORT_OFFSET:-0}+13306 といった形でまとめて制御できると、Zellijで複数セッションを並列に走らせても衝突なく運用できるかもしれません。他には、ポート番号を都度調整するよりもIPや環境ごと隔離を行わせる方法もありえるかと思います。
現状はそこが整備できていないため、「worktreeは複数用意できるがDocker Composeは1系統しか同時起動できない」というジレンマが残っている状況です。
今後、このあたりについての方針・仕組みを整備していき、より効率的な並列開発の環境を作っていきたいと思います。
