feat: unify Claude Code, Codex, and Cursor harness configuration

[tanimon]

2026-09-16 改訂: 本 spec は ADR 0005(docs/adr/0005-harness-sync-scoped-to-instructions-until-second-runtime.md)に基づき、当初の 3 製品 Semantic Sync(permissions / hooks / MCP / Skill を含む 50 story)を指示文の共有のみに縮小したもの。当初本文は本 issue の編集履歴に残る。縮小の根拠(rulesync 一次ソース調査、実利用状況、単一 Target Owner との衝突)は ADR 0005 と docs/research/2026-09-16-rulesync-vs-harness-308.md を参照。

Problem Statement

Claude Code のハーネス(グローバル指示・rules・permissions・hooks)は chezmoi が Source として成熟しているが、Codex のグローバル指示 ~/.codex/AGENTS.md は chezmoi 管理外の手コピーで、Claude 側の古い英語版のまま存在しないルール置き場を指している。今後 Codex / Cursor を本格的に使い始めたとき、「Claude と同じ行動指針を読んでいるか」を確かめる手段が無く、指示文を直すたびに 2 箇所を手で揃える必要がある。

一方で、当初の #308 は permissions・hooks・MCP・Skill まで含む 3 製品の意味的同期を掲げたが、Codex / Cursor はまだ日常利用されておらず、翻訳先の無い翻訳規則(Enforcement Grade、tighten-only、Portable Hook)を先回りで設計することが未着手 13 チケットの重さになっていた。

Solution

範囲を指示文(Content Module)の共有に限定する。Codex / Cursor に保証するのは「Claude と同じ Content Module を読む」ことだけで、permissions / hooks / sandbox は各製品ネイティブの設定のまま触らない。

グローバル指示は chezmoi テンプレートで合成する: 共有本文を製品名の付かない共有テンプレートに置き、~/.claude/CLAUDE.md と ~/.codex/AGENTS.md はそれぞれ製品別の前置き(Runtime Extension)+ 共有本文 + 共有 rules から生成される。Target Owner は両方とも chezmoi の 1 つで、既存の harness/ compose adapter は Managed Project(リポジトリ内 CLAUDE.md / AGENTS.md / .cursor/rules)専用に据え置く。APM は MCP のみの Dependency Plane を維持する。

最初の slice は ~/.codex/AGENTS.md の drift 解消(#311 の書き換え版)。

User Stories

1. As a dotfiles maintainer, I want グローバルの行動指針を 1 つの Source に置きたい, so that Claude と Codex の指示文を 2 箇所で手で揃えなくてよい。
2. As a Codex user, I want ~/.codex/AGENTS.md が Claude の ~/.claude/CLAUDE.md と同じ共有本文から生成されてほしい, so that 存在しないルール置き場を指す古い指示を読まされない。
3. As a Codex user, I want Claude の ~/.claude/rules/common/* に相当する共通ルールが ~/.codex/AGENTS.md に畳み込まれてほしい, so that Codex に rules ディレクトリ相当が無くても同じルールを読める。
4. As a Claude Code user, I want 現在の ~/.claude/CLAUDE.md の内容と挙動が保たれてほしい, so that この変更で成熟した Claude ハーネスが退行しない。
5. As a Claude Code user, I want Claude 専用ツール(AskUserQuestion)への言及が Claude 用前置きに残ってほしい, so that 共有化で Claude 固有の使い方が失われない。
6. As a Codex user, I want 「選択肢は番号付きで提示する」という製品非依存の意図だけを読みたい, so that Codex に存在しないツール名で混乱しない。
7. As a dotfiles maintainer, I want 製品別の前置きは「その製品にしかない機能」に限ってほしい, so that 共有本文に入るべき意図が製品別に分散しない。
8. As a dotfiles maintainer, I want ~/.claude/CLAUDE.md と ~/.codex/AGENTS.md の Target Owner が chezmoi 1 つであってほしい, so that 2 つの仕組みが同じファイルを書き合う drift ループが起きない。
9. As a dotfiles maintainer, I want ~/.claude/settings.json を従来どおり chezmoi の 1 テンプレートで所有し続けたい, so that permissions のコメント・順序・テンプレート変数(.ghOrg)が失われない。
10. As a dotfiles maintainer, I want 共有 rules の Source を現在の置き場のまま使いたい, so that 製品が 2 つの段階でファイル数を倍にしない。
11. As a Codex user, I want 生成された ~/.codex/AGENTS.md が Codex の既定 32 KiB 切り捨て未満であることを検査してほしい, so that 末尾のルールが黙って読み飛ばされない。
12. As a dotfiles maintainer, I want マシン固有の仕事用ルール(~/.claude/rules/ に symlink で差し込まれるもの)をグローバル Target に含めないでほしい, so that public リポジトリの Source に仕事側の内容や名前が入らない。
13. As a CI maintainer, I want 共有本文が両 Target に含まれることをテンプレートのレンダリング結果で検査してほしい, so that 片方だけ直した drift の再発が CI で止まる。
14. As a CI maintainer, I want 既存の check-templates / bats の流儀でテストが書かれてほしい, so that 新しいテスト基盤を持ち込まない。
15. As a new-machine user, I want chezmoi apply だけで ~/.codex/AGENTS.md が配置されてほしい, so that Codex のセットアップ手順を別に覚えなくてよい。
16. As a Cursor user, I want Cursor のグローバル User Rules 非公開ストレージには触れないでほしい, so that ADR 0004 の決定が守られる(Cursor は Managed Project 内の AGENTS.md で共有内容を受け取る)。
17. As a dotfiles maintainer, I want 根拠を失った当初チケット(permissions / hooks 翻訳、Enforcement Grade、APM Skill、apply 統合)を決定コメント付きで close したい, so that backlog そのものが重さにならない。
18. As a future maintainer, I want 再開条件(その製品を日常利用している事実)が ADR に残ってほしい, so that 同じ議論を証拠なしに繰り返さない。
19. As a dotfiles maintainer, I want このリポジトリの CLAUDE.md / AGENTS.md(Managed Project 側)は従来どおり harness/ compose で生成され続けてほしい, so that feat(harness): synchronize this repository's project instructions #310 で出荷済みの経路が変わらない。
20. As a dotfiles maintainer, I want このリポジトリの生成 CLAUDE.md の Key Patterns にグローバル指示の合成方式が追記されてほしい, so that 次に触るエージェントが ~/.codex/AGENTS.md を手で直さない。

Implementation Decisions

• 範囲: 指示文の共有のみ。permissions / hooks / sandbox / MCP の製品間翻訳は行わない。単一 Target Owner だけを不変条件として残し、tighten-only・Enforcement Grade 同等以上写像・Portable Hook は要件から外す(ADR 0005)。
• 合成機構: chezmoi テンプレート。共有本文は .chezmoitemplates/ 配下の製品名を含まない名前のテンプレートに置き、{{ template }} で取り込む(gitignore-common と同じ既存パターン)。共有 rules は現在の Claude 向け Source をそのまま {{ include }} で読む(移動しない)。
• Target と Owner: ~/.claude/CLAUDE.md はテンプレート化(前置き + 共有本文)、~/.codex/AGENTS.md は新規テンプレート(Codex 前置き → 共有本文 → 共有 rules を連結)。両方の Owner は chezmoi。harness/manifest.json の targets は空のまま、harness/ はこのリポジトリの Managed Project Target 専用。
• 前置きの線引き: Runtime Extension は「その製品にしかない機能」に限る(ADR 0004 と同じ)。AskUserQuestion の段落は共有本文では「選択肢を求めるときは番号付きの選択肢で提示する」とし、ツール名は Claude 前置きへ。
• Codex 前置きの内容: Codex が読む場所とサイズ制約に関する事実のみ。permissions / hooks に関する記述は入れない(ネイティブのまま)。
• 仕事用ルール: symlink 由来の rules はグローバル Target に含めない。プロジェクト側 AGENTS.md の責務(本 spec のスコープ外)。
• ~/.codex/config.toml / ~/.codex/hooks.json / ~/.cursor/*: 触らない。Runtime State が大半で、宣言的な行も製品ネイティブのまま。
• APM: target: claude の MCP のみ。Skill 配布は再開しない。
• チケット: feat(harness): distribute collision-free standalone Skills through APM #313 refactor(harness): expand Claude permissions into shared Risk Tier policy #314 feat(harness): enforce shared Risk Tier policy in Codex #315 feat(harness): enforce shared Risk Tier policy in Cursor #316 refactor(harness): contract legacy permission ownership #317 feat(harness): verify Isolation Boundaries and credential handling #318 feat(harness): deliver notifications through one Portable Hook #319 feat(harness): share post-edit formatting and secret checks #320 feat(harness): unify the self-improvement lifecycle across runtimes #321 feat(harness): make APM dependency updates reviewable #323 feat(harness): integrate atomic global synchronization with chezmoi apply #324 test(harness): enforce the full three-runtime Semantic Sync release gate #325 を wontfix + 決定コメントで close。feat(harness): ~/.codex/AGENTS.md を Claude と同じ共有本文から chezmoi テンプレートで生成する #311 は本 spec の slice として書き換え。feat(harness): MCP の配布先に codex を追加し、未使用の codex MCP サーバーを削除する #312(MCP の Codex / Cursor 配布)と feat(harness): enroll a new Managed Project explicitly #322(Managed Project の明示登録)は残す。
• 用語: CONTEXT.md から Safety Invariant / Enforcement Grade / Portable Hook / Credential Reference を削除。Harness Manifest は「製品検査条件 + Target 一覧」に定義を狭める。Capability Probe / Atomic Sync は実装が現存するため残す。
• ADR: ADR 0005 を追加し、ADR 0001 の該当部分を保留とする。docs/research/ の rulesync 調査は ADR が引用するため同じコミットに含める。

Testing Decisions

• seam は 1 つ: chezmoi execute-template --config <test toml> --source <repo> によるレンダリング結果。テンプレートの内部構造(.chezmoitemplates の分割、include の書き方)は検査しない。
• 検査項目: (1) 共有本文が CLAUDE.md と AGENTS.md の両出力に含まれる、(2) 共有 rules の全ファイル内容が AGENTS.md に含まれる、(3) AskUserQuestion は CLAUDE.md の出力にだけ現れる、(4) AGENTS.md の出力が 32 KiB 未満、(5) chezmoi managed --source <repo> に .codex/AGENTS.md が現れる。
• 先行事例: test/harness-instructions.bats(外部コマンドだけを呼び、出力を検査する流儀)と justfile の check-templates(test toml に [data] を置いて --config / --source で render する手順。--source を付けないと main worktree の Source を読んで空振りで通る点に注意)。
• 既存の網: just check-templates が render 失敗と JSON 妥当性を、just scan-sensitive が仕事側の org 名・アカウント名の混入を検出する。新テストはこれらと重複しない内容検査に絞る。
• 回帰基準: 変更前の ~/.claude/CLAUDE.md のレンダリング結果と変更後を比較し、AskUserQuestion 段落の言い換え以外に差分が無いことを実装 PR で示す。

Out of Scope

• permissions / hooks / sandbox / Approval Gate の製品間翻訳と、その Enforcement Grade 比較。
• ~/.codex/config.toml、~/.codex/hooks.json、~/.cursor/* の管理。
• Cursor グローバル User Rules(非公開ストレージ)への書き込み。
• APM による Skill 配布、APM lock の更新レビュー、chezmoi apply への harness sync 統合。
• 双方向同期、Runtime State の取り込み。
• 仕事用ルール(symlink 由来)のグローバル配布。
• rulesync の採用(却下理由は ADR 0005)。

Further Notes

• 当初の 3 製品 Semantic Sync 構想は ADR 0001 に、縮小の判断と rulesync 却下理由は ADR 0005 に記録されている。再開条件は「第 2 の製品が日常利用されている事実」。
• 現在の ~/.codex/AGENTS.md(chezmoi 管理外)は 570 バイトの英語版で ~/.Codex/rules/ という存在しないパスを指す。本 spec の最初の slice で置き換わる。
• 共有本文 + 共有 rules の合計は約 10 KB で、Codex の project_doc_max_bytes 既定 32 KiB に対して余裕がある。