Codex と Claude Code を併用した開発構成

2つのコーディングエージェントを行き来して開発するとき、会話は共有されません。GitHubのmainだけを引継ぎ媒体にし、ルールを1ファイルに集約した運用を書きます。

1つのアプリを、ChatGPT Codex と Claude Code の両方で開発しています。やってみると、片方で決めたことがもう片方に伝わらないという問題に真っ先にぶつかります。

会話履歴は共有されません。「さっき話した方針」は、もう一方のツールには存在しません。

引継ぎ媒体を1つに決める

そこで、次の一文を運用の前提に置きました。

引継ぎ媒体は GitHub の main だけ。リポジトリだけから状態を復元できる状態を保つ。

会話に依存した情報を作らない、という決め事です。方針、制約、決定事項は、すべてリポジトリの中のファイルに書きます。

この前提を置くと、次のことが自動的に決まります。

Codex は AGENTS.md を、Claude Code は CLAUDE.md を自動で読みます。両方にルールを書くと、必ず片方が古くなります。

そこで CLAUDE.md は実質的に転送だけにしました。

# CLAUDE.md

作業ルールは ChatGPT Codex と共通で、`AGENTS.md` にまとめてある。
**ルールを足すときも直すときも、このファイルではなく `AGENTS.md` を編集すること。**

@AGENTS.md

@AGENTS.md の記法で中身を取り込めるので、実体は1ファイルで済みます。 「ここが唯一の正」と書いておくのが要点です。書いておかないと、片方のツールが親切心で CLAUDE.md に追記してしまいます。

ルールファイルに書く価値があるのは、コードを読んでも分からない決定です。

実際に書いているのは、たとえば次のようなことです。

どちらも、コードを読んでも「なぜそうなっているか」は分かりません。書いていないと、エージェントは良かれと思って前提を壊す提案をしてきます。

「バックエンドを立てればもっと速くできます」という提案は、技術的には正しいのにこのプロジェクトでは的外れです。却下の理由を毎回説明するより、一度書いておくほうが安いという判断です。

もう1つ効いているのが、測って失敗した変更をそのまま残しておくことです。

たとえば「読み取りの思考量を下げてはいけない」という項目には、なぜ駄目だったのか（精度も速度も悪化した）まで書いてあります。

理由なしに禁止事項だけ並べると、次のエージェントが同じ最適化を思いつきます。理屈としては正しく見える手なので、なぜ駄目だったかを測定結果つきで残す必要があります。

複数のエージェントが触るので、品質の基準を人間の裁量に任せると揺れます。コマンド列を固定して、これを全部通してからpushする決まりにしました。

npm test && npm run typecheck && npm run build && git diff --check

さらに、デプロイ経路も固定しています。 main へpush → CIとホスティング側が検証 → 通った版だけが自動で配信される形です。手動デプロイのコマンドは、障害時の緊急経路としてのみ残しています。

テストが落ちた版は配信されないという状態を作っておくと、どちらのツールで作業していても最低限の品質が揃います。

技術的なコミットログとは別に、利用者に見える変更だけを書く履歴を用意しています。

エージェントへの指示は「利用者に見える変更は履歴の先頭へ追記する。技術的な言い回しは避け、何ができるようになったかだけを書く」。

これは利用者のためでもありますが、次に作業を再開するときの現在地の確認にも使えます。コミットログは粒度が細かすぎて、何が変わったのかを掴むのに向きません。