お疲れ様です！IT業界で働くアライグマです！
これまで個人開発のコーディングは、ほぼClaude Code一本に絞って開発を進めてきました。プロジェクトルールやカスタムスキルを作り込み、快適な自動化環境が出来上がっていたのですが、GoogleのAIエージェントであるGemini（AGY / Antigravity CLI）も併用してみようと思い立ったのが今回の発端です。
軽い気持ちで「AGY側にも同じスキルをコピペして動かせばいいや」と始めたところ、あっという間に運用が崩壊しかけました。今回は、その失敗とポインタ方式によるSSOT（Single Source of Truth）化の設計判断についてお話しします。
Claude Code専用だった開発環境に、Gemini（AGY）を迎えた日
個人開発しているDevPickなどのリポジトリでは、日常の開発作業をClaude Codeに任せるフローを構築していました。リポジトリ固有のルールは CLAUDE.md にまとめ、定型業務はカスタムスキルとして .claude/skills/ 配下に配置する構成です。
たとえば、Issueのトリアージとラベル付けを行う issue-triage や、要件定義から実装・テストまでを一気通貫で進める issue-work、コミット前のセルフチェックを機械的に走らせる selfreview など、開発の各工程をスキルで固めていました。CLAUDE.mdでプロジェクト知識を整備するガイド で整理したように、リポジトリの暗黙知をファイルに書き出し、CLIから呼び出す仕組みが快適に機能していたのです。
そんな中、GoogleのAIエージェントであるGemini（AGY / Antigravity CLI）も並行して活用する方針を決めました。巨大なドキュメントの読み込みや、Claudeとは異なる視点でのコード分析など、モデルの得意領域に合わせて使い分けるのが狙いでした。
「すでにClaude Code向けにスキルやルールを作り込んであるのだから、それをGemini側でもそのまま読み込ませればすぐに動くだろう」と、このときは非常に軽く考えていました。
IT女子 アラ美
ITアライグマ「とりあえずスキルを複製」で始まった二重管理の悪夢
Gemini（AGY）やCodexなどのエージェントツールは、リポジトリスコープのスキルを .agents/skills/ から読み込みます。一方、Claude Codeが読み込むのは .claude/skills/ です。
ディレクトリ構造が異なるため、私は深く考えずに「早くGemini側でもスキルを使いたい」という一心で、.claude/skills/ にあるMarkdownファイルをまるごと .agents/skills/ へコピーしました。
最初は問題なく動いているように見えましたが、破綻はすぐにやってきました。
開発を続けていると、スキルの手順やチェックリストは頻繁に改善されます。「テスト実行の前にマイグレーション確認を挟もう」「コミットメッセージのプレフィックス判定を厳密にしよう」といった細かな改善をClaude Codeで作業している最中に思いつき、.claude/skills/ 側のファイルを書き換えます。
しかし、その修正を .agents/skills/ 側へ反映するのをすっかり忘れてしまうのです。逆にGemini側で作業しているときに気付いて直した微修正も、Claude側には反映されません。
わずか数日経った頃には、次のような惨状が待っていました。
- 手順の乖離：Claudeで実行したときとGeminiで実行したときで、チェックリストの項目数や検証順序が微妙に異なる
- 正本不明の混乱：「あれ、どっちに書いた手順が最新だっけ？」と毎回diffを眺めて思い出す無駄な時間が発生する
- 修正漏れによる事故：片方だけで修正したはずのバグ防止ガードが、もう片方のエージェント経由で再発する
コードの重複はDRY原則（Don’t Repeat Yourself）で徹底的に排除するのに、AI向けの設定やスキルでは真っ先にコピペ重複を犯してしまっていたのです。
IT女子 アラ美ITアライグマ手順はコピペしない─ポインタ方式とSSOTへの移行
二重管理による破綻を止めるために下した決断はシンプルでした。「手順そのものは絶対に複製しない」というルールの徹底です。
具体的には、手順の正本（Single Source of Truth：SSOT）を .claude/skills/ に集約し、Gemini（AGY）やCodexが参照する .agents/skills/ には手順本文を書かず、正本へのポインタ（参照指示）と環境差分の読み替え表だけを置く構成へと舵を切りました。
実際のポインタファイルは、以下のような簡潔な構造にしています。
---
name: issue-work
description: "Issue番号を受け取って調査・ブランチ作成・実装・テストまで進める"
---
# Agent Bridge
このリポジトリではClaude側のSkillを正本として共有します。
作業前に以下のファイルを最初から最後まで読み、その手順と禁止事項に従ってください。
`.claude/skills/issue-work/SKILL.md`
## 環境別の読み替え
- 開発ブランチの作成やコマンド実行は、各エージェントの標準ツールを使用する
- ブラウザでの実機確認は、AGYでは /browser やブラウザ操作ツールを使用する
この方式に移行したことで、得られたメリットは絶大でした。
日常の開発で「テスト手順を見直したい」「コミット前のチェック項目を増やしたい」と思ったら、正本である .claude/skills/ 側のファイルを1回修正するだけで完了します。
Gemini（AGY）がこのスキルを呼び出した際、まずポインタファイルの指示に従って正本ファイルを読みに行きます。その結果、常に最新かつ共通の手順に基づいて動作するようになり、エージェント間での手順乖離が完全にゼロになりました。
IT女子 アラ美ITアライグマ環境差分をどう吸収したか（セッションID・ルール認識・ブラウザ確認）
ポインタ方式で手順の正本を一本化したとはいえ、実際に動かしてみると「エージェントツールごとの仕様の違い」という次の壁にぶつかりました。
各ツールにはそれぞれ固有の作法があります。これらを場当たり的に処理せず、以下の3つの工夫で吸収しました。
ルールファイルはシンボリックリンクで一本化
Claude Codeはリポジトリ直下の CLAUDE.md を自動的に読み込んでプロジェクトの制約を把握します。一方、Codexは AGENTS.md、Gemini（AGY）は GEMINI.md や AGENTS.md を参照する仕様になっています。
これらもファイルとして別々に作ってしまうと、プロジェクトルールの二重管理が再発します。そこで、リポジトリ直下にシンボリックリンクを配置しました。
# CLAUDE.md を正本とし、他ツール向けのファイルをシンボリックリンクにする
ln -s CLAUDE.md AGENTS.md
ln -s CLAUDE.md GEMINI.md
これにより、プロジェクトルール自体のSSOTも完全に維持できるようになりました。
セッションIDの環境変数差分をスクリプトで吸収
Issueトリアージを自動化する監査スクリプトでは、実行中のAIエージェントのセッションIDを取得して作業ログに記録する仕組みを入れていました。
しかし、参照すべき環境変数がツールごとに異なっていました。Codex環境では CODEX_SESSION_ID ですが、Gemini（AGY）環境では ANTIGRAVITY_CONVERSATION_ID という名前で渡されます。
スクリプト側で両方の環境変数を順次フォールバックして解決できるように改修し、さらにテストコードを追加して型安全と動作を機械的に保証しました。
def resolve_session_id() -> str:
"""AGY（Gemini）とCodexの両環境でセッションIDを安全に取得する"""
return (
os.getenv("ANTIGRAVITY_CONVERSATION_ID")
or os.getenv("CODEX_SESSION_ID")
or ""
)
ブラウザ確認などツールごとの手段の違いを読み替え表に明記
コミット前の自己レビューを行う selfreview スキルでは、実装した画面のブラウザ実機確認ステップがあります。
Claude Codeでは手動確認やローカル確認が中心でしたが、Codexには直接ブラウザを操作する対話機能がありません。一方、Gemini（AGY）にはブラウザツールや /browser コマンドが用意されています。
こうした「手順の目的は同じだが、ツールごとに取れる実行手段が異なる」ケースについては、ポインタファイルの「環境別の読み替え表」に対替手段（AGYならブラウザツール、CodexならPlaywright E2Eテストなど）を具体的に指定することで、どのエージェントが動いても迷わず同じ検証水準を担保できるようにしました。
IT女子 アラ美ITアライグマまとめ
今回、Claude Codeの開発環境にGemini（AGY）を導入したことで、改めて「AIエージェント向けの設定やスキルも、プロダクトコードと同じくSSOT（信頼できる唯一の情報源）で管理しなければならない」と痛感しました。
ツールごとにファイルをコピペして管理しようとすると、あっという間に手順の乖離や更新漏れが起きて二重管理の泥沼にはまります。
- 手順の正本は1箇所（Claude側）に集約する
- 他エージェント向けにはポインタ指示と環境別の読み替え表だけを置く
- ルールファイルはシンボリックリンクで一本化し、スクリプトやテストで環境差分を吸収する
この3点を徹底したことで、エージェントが増えても手順の更新コストを最小限に抑え、どのツールからでも同じ品質で作業を進められる土台が整いました。
AIコーディングツールの選択肢はこれからも増え続けていきます。ツールが変わるたびに設定を作り直すのではなく、ポインタ方式とSSOTで柔軟に使い回せる環境を作っておくのが、中長期で一番ラクなアプローチだと感じています。
IT女子 アラ美ITアライグマ
