agent-dotfiles

Claude Code、OpenAI Codex CLI、GitHub Copilot CLI、Gemini CLI、Oracle CLI の設定ファイルと AI Agent 向け skill を Git リポジトリで管理するための個人運用ツール。 秘匿情報とホームディレクトリ依存を取り除いた repo view を作り、別マシンへ必要な設定だけを戻せるようにする。

関連ページ

扱う設定

基本のデータフロー

flowchart LR
        home["Home directories
~/.claude / ~/.codex / ~/.copilot / ~/.gemini / ~/.oracle"]
        export["agent-dotfiles export"]
        repo["agent-dotfiles repo
sanitized repo view"]
        review["review-orchestrator
issue / PR review gates"]
        import["agent-dotfiles import"]
        target["Target machine
restored local settings"]

        home --> export --> repo
        repo --> review
        repo --> import --> target
        target --> home
      

サニタイズと復元

export では設定ファイルを service ごとの構造に合わせて読み、秘匿値とホームディレクトリ依存を repo に置ける形へ正規化する。 import では既存のローカル設定を preseed し、管理対象だけを上書きする。これにより認証情報、履歴、cache、runtime state は保持される。 import の一時データは ~/.cache/agent-dotfiles/import/ に置き、処理後に削除する。反映先と、その隣に作る .import-old バックアップへの書き込み権限は別途必要になる。

変換ルール

• 環境変数名に TOKEN、SECRET、PASSWORD、CREDENTIAL、_KEY を含む値はプレースホルダ化する。
• コマンド、引数、環境変数内のホームディレクトリパスは {{HOME}} に置き換える。
• Claude の mcpServers、Codex の TOML、Copilot / Gemini の JSON、Oracle の JSON5 は構造を保ったまま処理する。
• 履歴、セッション、cache、認証 token、runtime DB は管理対象から外す。

Claude の日本語応答

Claude の Stop hook に登録した japanese-response-guard は、現在のターンの英語 text block を検出すると日本語での書き直しを求める。code、URL、path は判定から除外する。 stop_hook_active が true の場合、transcript を読めない場合、Agent SDK や claude -p の session では block しない。他の runtime には登録しない。

主要コマンド

git clone https://github.com/TomoakiMizuno/agent-dotfiles.git
cd agent-dotfiles
make install

agent-dotfiles status
agent-dotfiles diff
agent-dotfiles export --target codex/config.toml
agent-dotfiles import --target claude/skills/multi-review

新規環境では、先に dotfiles 側で secret substrate と PATH を整える。agent-dotfiles は AI Agent 固有の構造化設定と 同期ロジックを扱い、shell や OS の基本セットアップは dotfiles 側の責務として分ける。

通常 docs

CLI の使い方、同期仕様、review 運用の詳細は docs-site 内の通常 docs index から読む。 skill reference は別 scope で移植するため、このページでは通常 Markdown docs への導線だけを扱う。

target 指定

export、import、status、diff は repo display path を基準に --target で対象を絞れる。service root、管理対象ファイル、管理対象ディレクトリだけを許可し、 対象外のファイルや runtime state を巻き込まない。

• claude、codex、copilot、gemini、oracle の service target。
• codex/config.toml、gemini/settings.json、oracle/config.json のような file target。
• claude/skills/<skill>、claude/agents、codex/hooks のような directory target。
• codex/memories は PC 移行や明示 backup 用の opt-in target として扱う。

実装 workflow の既定

開発と日本語文面の共通基準

dev-standards は、変更範囲と repo の契約に応じて Unit、Integration、E2E の必要範囲を決める。全変更へ同じ test 数や coverage を一律に課さず、明示された selector と必須 gate は維持する。Go の lint と race 検査も repo の手順と変更の影響範囲から選び、Codex の allowlist は編集する時だけ専用の基準を読む。 writing-norms と stop-ai-slop-jp は、Issue、PR、技術文書の事実、数値、検証結果、未確認範囲を残したまま日本語を整える。コードコメントには repo 固有の規約を使う。

skills 直下の synced/ と各階層の .DS_Store は管理対象から外し、import 時も保持する。 subagent のモデルと推論量は provider ごとに指定する。Codex 用の codex block が無ければセッションから継承し、Claude のモデル名から推論量を導出しない。 compact-plus の要約 backend は Claude Opus 5.5 / medium、fallback は GPT-6 Luna / medium。対象モデルが使えるかは配布前に Codex CLI で確認する。

判断の確認と Issue 本文

Issue 化や plan 作成前に高影響の未確定事項が残る場合は、decision-doc で推奨案と影響範囲を HTML にまとめ、ユーザーの回答を packet に記録する。 Issue 本文は確定材料だけを専用 writer に渡して起草し、要点・背景・Design doc を常時表示、受け入れ条件と実装契約を折りたたみに置く。 親 packet から子 Issue を作る flow では、子ごとの task-research bind-issue と discover を確認する。

review-orchestrator の役割

review-orchestrator は review 系 skill の実行本体で、Issue 作業開始前の claim gate、 checkpoint 付き implementation gate、multi-review、Copilot bot review 待機、inline thread close、adversarial review prompt の生成を担う。 外側の AI Agent は自然言語の判断だけで完了扱いにせず、stdout JSON、evidence manifest、report を根拠に次の action を決める。 review-only post=pending は finding を投稿者本人の pending review に置くだけで submit しない。agent-team-run は worker の model / effort と fix-github-issue の review・E2E option を queue に保存して worker へ渡し、integration は検証 command を指定した時だけ有効にする。 標準規模の Issue 実装では、追加するファイルや処理を implementation-plan.v1 で受け入れ条件と契約へ紐付ける。Issue 起票時は 変更してはいけない契約 の直後に 追加してはいけない挙動 を置き、non-goal と fallback の回答を具体的な禁止事項として残す。Issue 本文は 要点、背景、Design doc を常時表示し、受け入れ条件と実装契約を <details> に折りたたむ。本文は確定材料だけを受け取る専用 writer が起草する。 Issue 作成や local plan の前に残った high-impact な未確定事項は、個別質問を連続で出さず decision-doc の HTML レビューで確定し、packet-out.json のユーザー判断を前提へ転記する。 作業途中で仕様が訂正された場合は、Issue / plan、実装、テスト、コメント、PR 説明のうち今回触れた箇所へ新しい条件を反映し、未反映と対象外を分けて残す。drift check が検出した余剰な追加物は report-only で記録し、採否は既存の action record へ残す。 fix-code-comments は明示実行専用で、fix-github-issue、implement-from-plan、agent-team-run の実装 workflow からは自動実行しない。実装 workflow は PR 前 simplify commit 後に、非 test・非 generated Go の追加 hunk を comment intent self-check で確認し、必要なコメントを理由、制約、外部契約に分類して report-only で記録する。完了可否は stateless な completion-check を標準入口とし、必要な mode、commit、validation、simplify、review、CI、E2E の canonical artifact を現在の repository / HEAD / PR と照合する。completion-check は fix-code-comments の run record と comment intent record も照合し、いずれも report-only の観測として保存する。 手元検証は pr-publication run-validation で transcript 化し、sanitizer 適用済みの public artifact を PR 本文から参照する。 host profile の companion PR を遅延生成する場合は、pending event を追記し、元 PR の merge 後に host-profile-pending batch で未処理分を 1 本へまとめる。予約済み event 集合から同じ batch を復元するため、中断後の再実行でも重複 PR を作らない。 stacked な sibling 実装や明示 auto stack では、publication intent と凍結順を repo-scoped state に保存する。publication gate と closing Issue gate は required で動き、coordinator が lease と effective tail を確定して finalization を再開する。親 Issue の表が変わった場合は未公開 intent の相対順を再確認し、並び替えや row 消失を検知すると publication_order_stale で branch 変更前に停止する。prepare 後に HEAD が進んだ場合は stack-renew --head-oid で intent の head を更新してから完了させる。false stop や順序違反などが観測された場合だけ report-only へ戻す。 design doc を公開した Issue 作成 flow は repo-scoped binding record を保存し、published family の completion で Issue との紐付け evidence を確認する。

レビューと同期の追加操作

local reviewer を使う PR review は、checkout の HEAD が PR head と一致していることを起動前に確認する。 review-only post=pending は finding を自分の下書き review に保存し、公開は人間が GitHub 上で行う。pending review が残る間は、返信による submit で finding も公開される点に注意する。 bot が始めた thread に viewer 本人の AI attribution 付き返信だけが続く場合は bot thread と同じ承認判定を使う。marker の無い人間の投稿や取得不能な投稿者があれば承認評価へ戻る。 post-merge-sync は未マージ PR も扱い、CI と最新 HEAD、merge 状態を確認してから squash merge と指定範囲のローカル反映へ進む。

Claude reviewer の transport は CLI 明示値、host-local な agent-runtime.json、default headless の順で決まる。 transport failure 時は別 transport へ黙って fallback せず、stderr summary、artifact path、次 action を evidence に残す。 review-orchestrator agent-runtime doctor --format json は review 系 workflow から Codex CLI reviewer を呼ぶための最小 allow rule coverage を検査し、不足 rule を JSON で報告する。host-local file は編集しない。 実行時のモデル指定は明示引数、既存の repo / cwd / XDG 設定、CLI 既定値の順で解決する。Codex の推論量は low|medium|high|xhigh|max|ultra を受け付け、共通 resolver と PR 本文生成で同じ許可値を使う。通常 review の履歴を再利用する場合は model settings の digest も照合し、異なるモデルや推論量の結果を流用しない。

非管理データ

agent-dotfiles は CLI 設定の同期ツールであり、各 Agent が実行時に作る履歴や cache を repo に集めない。 Claude の projects、Codex の sessions、Copilot の trusted folders、Gemini の認証・履歴などは環境固有の状態として保持される。

運用境界

参照元

• README.md
• docs-site 通常 docs index
• CLI 利用方法
• 同期仕様
• review 運用