Codex と Claude Code の global instruction をそろえるために、最初は rule.md を正本にして配るところから始めました。これで「同じことを2ファイルへ手で書く」問題はかなり減りました。

ただ、しばらく運用すると別の問題が出てきます。rule.md に何でも入れたくなるんですよね。作業方針、応答方針、ローカル知識への入口、端末ごとのパス、個人用の補足、プロジェクト固有の注意点。便利だからと足していくと、global instructionがまた重くなります。

そこで、自分の中では source / generated / local override を分けて見るようにしました。この記事は、その線引きのメモです。

まず、3つに分けて見る

sourceは人間が編集する正本

sourceは、人間が編集する正本です。自分の場合は rule.md のようなファイルを想定しています。

ここに置くのは、複数のAIエージェントや複数端末で共通して効かせたいルールです。

  • 応答方針
  • 安全方針
  • 作業前にrepoを読むこと
  • secretやprivate情報を出さないこと
  • 共有ブランチへ直接commitしないこと

つまり、「どの端末でも、どのエージェントでも、毎回守ってほしい前提」です。

sourceに置く内容は、できるだけ公開しても困らない粒度にします。ここにprivateなパスやsecretの置き場所を入れ始めると、source of truthとして扱いづらくなります。

generatedは配布先の生成物

generatedは、sourceから作られて配布されるファイルです。

たとえば、次のようなファイルです。

~/.codex/AGENTS.md
~/.claude/CLAUDE.md

この2つは実際には各ツールが読む重要なファイルですが、自分の運用では人間が直接育てる場所ではありません。rule.md から配布される生成物として扱います。

generatedを直接編集し始めると、どちらが正しいのか分からなくなります。Codex側だけ新しい、Claude Code側だけ古い、別端末だけ違う、みたいな状態が起きます。

なので、generatedに差分が出たら、まずsourceへ戻します。

直したいことがある
  ↓
generatedを直接編集しない
  ↓
sourceを直す
  ↓
deployしてgeneratedを作り直す

これを守るだけで、だいぶ追いやすくなります。

local overrideは端末ごとの差分

local overrideは、端末ごとの事情を置く場所です。

たとえば、次のような情報です。

  • この端末でだけ使う作業ディレクトリ
  • ローカルの知識索引への入口
  • 端末ごとのprofile名
  • private repositoryの配置場所
  • 実secretではなく、secret storeへの参照方針

これらは便利ですが、sourceへ混ぜると一気に扱いづらくなります。端末Aでは正しいけれど端末Bでは違う、という情報だからです。

自分は、こういう情報はsourceに直書きせず、private overlayや端末local設定へ逃がすほうが楽だと思っています。

sourceに入れるもの

毎回読ませたい方針

sourceには、毎回読ませたい方針だけを置きます。

## 安全方針

- secret、token、private URLを出さない
- 破壊的変更の前には確認する
- 変更は小さくreviewしやすくする

## 開発方針

- 変更前にlocal projectを読む
- 既存projectの規約を優先する
- mainへ直接commitしない

このくらいなら、CodexにもClaude Codeにも同じ意味で読ませられます。端末が違っても、プロジェクトが違っても、基本的には変わりません。

判断基準として残したいもの

sourceに向いているのは、細かい作業手順よりも判断基準です。

  • 何を公開してよいか
  • 何を人間承認にするか
  • どの単位でPRにするか
  • どの情報源を優先するか

こういう基準は、毎回の作業で効きます。逆に、長いコマンド例やプロジェクト固有の手順は、global instructionへ入れると重くなりがちです。

generatedにだけ出るもの

ツールごとの入口

generated側には、ツールごとの都合が出ることがあります。

Codexが読むファイル名、Claude Codeが読むファイル名、呼び出し方、見出しの名前。そういう差分はgeneratedに出ても構いません。

ただし、意味のあるルール差分をgenerated側にだけ持たせないようにします。

OK:
  Codex用の出力先がAGENTS.md
  Claude Code用の出力先がCLAUDE.md

避けたい:
  Codexだけ安全方針が古い
  Claude Codeだけ別の禁止事項がある

generatedは、ツールが読む形に変換された結果です。人間が判断する場所ではなく、sourceの反映結果として見るのがよさそうです。

直接修正したくなったらsourceへ戻る

generatedを見ていて「ここ直したいな」と思うことはあります。そのときに、配布先を直接直さないのが大事です。

# 配布先を直接編集しない
$EDITOR ~/.codex/AGENTS.md

# sourceを編集してからdeployする
$EDITOR rule.md
./deploy.sh

直接直すと、その端末だけ直ったように見えます。でも、次のdeployで消えます。あるいは、別端末には反映されません。

短期的には早いけれど、あとで追えなくなるので、ここはsourceへ戻すようにしています。

local overrideに逃がすもの

端末固有の知識入口

端末固有の情報はlocal overrideへ逃がします。

## Local Knowledge Index

- session log index: <local note index>
- book index: <local book index>
- project root: <local workspace root>

ここでは実パスを書かずに例示していますが、実運用では端末ごとの設定に具体値を持たせます。source側には「local knowledge indexを読む」という方針だけを置く。具体的な場所はlocal overrideに置く。こう分けると、公開できるsourceを短く保てます。

privateな情報をsourceに寄せない

privateな情報そのものは、sourceに寄せません。

  • secret値
  • token
  • private URL
  • 顧客名
  • raw log
  • private repositoryの本文

これらは、global instructionの便利さとは相性が悪いです。常時読ませるファイルにprivate情報を入れると、コピー、引用、PR、ログ保存のたびに気を使うことになります。

必要なのは、値そのものではなく扱い方です。

- secretはGitに置かない
- secret storeやCI secret storeを使う
- raw logをそのまま公開repoへ貼らない

この方針だけsourceに置けば十分です。

肥大化しそうなときの判断

これは毎回読むべきか

global instructionに何か足したくなったら、まずこれを見ます。

これは毎回読むべきか？

毎回読むべきならsource候補です。特定の作業でだけ使うなら、skill、README、project docs、Issue、PR templateのほうが向いています。

特に、長い手順書やレビュー観点をglobal instructionに入れると、すぐに重くなります。常時読む前提は短く、必要なときだけ呼ぶ手順は外に出す。この分け方が効きます。

端末が変わっても同じか

次に見るのはこれです。

端末が変わっても同じか？

同じならsourceに置けます。端末ごとに変わるならlocal overrideです。

たとえば「mainへ直接commitしない」はsourceでよいです。一方で「この端末のObsidian indexはここにある」はlocal overrideです。混ぜると、sourceの再利用性が落ちます。

公開repoに置けるか

最後に、公開repoに置けるかを見ます。

公開repoに置けないなら、sourceに入れない。これはかなり分かりやすい基準です。sourceをpublic-safeに保っておくと、あとからagent-config-coreのような再利用可能なrepoへ切り出しやすくなります。

自分用の分け方

3層で考える

今の自分の整理は、だいたいこうです。

source
  人間が編集する正本。
  共通ルール、安全方針、判断基準を置く。

generated
  sourceから配布される生成物。
  CodexやClaude Codeが読むファイル。

local override
  端末ごとの差分。
  privateな知識入口やlocal pathを置く。

この3層に分けると、「どこを直せばよいか」がかなり見えやすくなります。

短く保つのは、後から効く

global instructionは、長くするほど強くなるわけではありません。むしろ長くなるほど、どの指示が効いているのか分かりにくくなります。

自分が毎回効かせたいのは、細かい手順よりも判断基準です。安全側に倒す、repoを読む、既存規約を優先する、小さくPRにする、公開できないものを混ぜない。そういう前提だけをsourceに置く。

細かい手順は、必要なときにskillやdocsから呼ぶ。端末固有の話はlocal overrideに置く。generatedは直接育てない。

このくらいに分けておくと、CodexとClaude Codeを両方使っていても、設定の見通しが崩れにくくなります。