TL;DR

Claude Code と Codex を併用していたら、MCP・システムプロンプト・スキルの設定が二重管理になり、片方だけ更新されるズレが頻発した
APM（Agent Package Manager）を導入し、apm.yml + .apm/ を唯一の正（SSOT）に。各ツールのネイティブ設定（.mcp.json / AGENTS.md / .claude/rules/ / スキル）はすべて生成物にした
「編集する場所」が2ツール分から1か所になり、CIで生成物のドリフト（再生成し忘れ）を自動検知できるようになった
ハマったのは「ツール間で共有できる設定／できない設定の線引き」。権限・セキュリティ設定は共有せず、ツール個別で管理するのが結論

この記事の対象読者

Claude Code や Codex など、複数のAIコーディングエージェントを併用している方
MCP サーバーの設定をチームで共有・管理したい方
AIエージェントの設定を「Docs as Code」的にバージョン管理・レビュー対象にしたい方

背景：AIエージェントの設定が二重管理になっていた

私たちのチームでは、AIコーディングエージェントとして Claude Code をメイン、Codex をサブで併用しています。
どちらも「MCP サーバー」「システムプロンプト（プロジェクト共通の指示）」「スキル（定型作業のワークフロー）」を設定できますが、設定ファイルの形式がツールごとに違うのが悩みでした。

設定の種類	Claude Code	Codex
MCP サーバー	`.mcp.json`	`.codex/config.toml`
システムプロンプト	`.claude/rules/*.md`（自動読込）	`AGENTS.md`（直接参照）
スキル	`.claude/skills/`	`.agents/skills/`

同じ内容を2つの形式で手書きして同期させる必要があり、次のような問題が起きていました。

MCP サーバーのバージョンを上げたのに、Codex 側の TOML を更新し忘れる
システムプロンプトに「コミットメッセージ規約」を足したが、片方のツールにしか反映されていない
新メンバーが「どっちのファイルが正なの？」と迷う

要するに SSOT（Single Source of Truth）が存在しない状態でした。AIエージェントの設定は、いまやコードと同じくらいチームの生産性を左右します。ここが二重管理なのは看過できませんでした。

技術選定：なぜ APM なのか

解決策として採用したのが、Microsoft が公開している APM（Agent Package Manager） です。

APM とは

APM は、AIエージェントの設定（MCP・インストラクション・スキルなど）をプリミティブ（部品）として一元定義し、そこから各ツールのネイティブ設定を生成・配備するためのツールです。npm がパッケージを管理するように、「エージェント設定」を管理するイメージです。

APM を選んだ3つの理由

1. 「1つの定義 → 複数ツールへ配備」がそのまま実現できる

apm.yml（依存する MCP など）と .apm/（インストラクション・スキルの実体）を書けば、apm install / apm compile で Claude Code 用と Codex 用の設定を両方まとめて生成してくれます。まさに私たちが欲しかった SSOT → 派生の構造です。

2. 生成物をコミットすれば「利用するだけなら CLI 不要」

生成された .mcp.json や AGENTS.md をリポジトリにコミットしておけば、設定を使うだけのメンバーは APM CLI を入れる必要がありません。設定を変更する人だけが CLI を入れて再生成すればよい。導入のハードルが低いのが決め手でした。

3. 設定を「レビュー可能な差分」にできる

すべてがファイルなので、設定変更が Pull Request の差分として現れます。「なぜこの MCP を足したか」をレビューで議論できる。AIエージェント設定を Docs as Code の土俵に乗せられます。

実装：SSOT から各ツール設定を生成する

全体像

ポイントは 「編集するのは左側（SSOT）だけ」「右側（生成物）は触らない」 というルールです。

SSOT の中身

apm.yml に MCP サーバーの依存を宣言します。

# apm.yml（抜粋）
name: my-ai-assistant
version: 1.0.0
targets:
  - claude
  - codex
dependencies:
  mcp:
    - name: apidog-lambda
      transport: stdio
      command: npx
      args:
        - -y
        - apidog-mcp-server@0.0.17   # バージョンは固定（@latest は使わない）
        - --project=XXXXXXX
      env:
        APIDOG_ACCESS_TOKEN: ${APIDOG_ACCESS_TOKEN}  # 実値は環境変数
    - name: atlassian
      transport: stdio
      command: npx
      args:
        - -y
        - mcp-remote@0.1.38
        - https://mcp.atlassian.com/v1/mcp/authv2
includes: auto

システムプロンプトは .apm/instructions/project.instructions.md に Markdown で書きます。これ1ファイルが、Claude Code 用の .claude/rules/project.md と Codex 用の AGENTS.md の両方に展開されます。

スキルは .apm/skills/<name>/SKILL.md に置きます。私たちは PR 作成・差分レビュー・Jira チケット生成・MCP バージョンチェックなどを定義しています。

生成コマンドを Makefile に集約

コマンドを覚えなくていいように、Makefile にまとめています。

# 生成物の再現性のため、CI とローカルで APM バージョンを揃える
APM_VERSION := 0.16.1

apm-install:   # apm.yml/.apm を各ツールへ配備（MCP/skills/rules + lock 生成）
	apm install

apm-compile:   # .apm/instructions から AGENTS.md（Codex 用）を生成
	apm compile -t codex --no-links --single-agents

apm-sync: apm-install apm-compile   # AI 設定を全再生成（.apm を編集したら実行）

apm-verify: apm-sync   # 生成物が SSOT と整合しているか検査（CI と同じ）
	apm audit --ci --no-drift

運用はシンプルです。.apm/ か apm.yml を編集したら make apm-sync を叩くだけ。 これで両ツールの設定が一斉に再生成されます。

CI で「再生成し忘れ」を自動検知する

このワークフローの弱点は「SSOT を編集したのに make apm-sync を忘れる」ことです。すると生成物が古いままコミットされ、SSOT と生成物がズレます。

そこで CI で生成物のドリフトを検知します。CI 上でもう一度生成し、差分が出たら失敗させる仕組みです。

# .github/workflows/ci.yml（抜粋）
jobs:
  apm-verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install APM CLI
        uses: microsoft/apm-action@v1
        with:
          apm-version: "0.16.1"   # ローカルと固定
          setup-only: true

      - name: APM audit (baseline checks)
        run: apm audit --ci --no-drift

      # 再生成し忘れ（make apm-sync 忘れ）を検出
      - name: Verify generated files are in sync
        run: |
          apm install
          apm compile -t codex --no-links --single-agents
          git diff --exit-code -- \
            AGENTS.md .mcp.json .codex .claude/rules .claude/skills .agents/skills

git diff --exit-code で「再生成しても差分が出ない＝同期済み」を保証します。生成物の Build ID はコンテンツハッシュで決まる決定的な値なので、内容が同じなら差分は出ません。

ハマったところと解決策

1. 「共有できる設定」と「できない設定」の線引き

一番の学びがこれです。すべてを共有しようとして失敗しました。

権限・セキュリティ設定（どのコマンドを許可するか等）は、Claude Code では .claude/settings.json、Codex では approval_policy / sandbox_mode と、概念からして噛み合いません。そもそも APM の管理対象外でもあります。

結論として、共有する／しないを次のように割り切りました。

設定の種類	SSOT で共有	備考
MCP サーバー	✅	形式差はあれど内容は同じ
システムプロンプト	✅	Markdown をそのまま両ツールへ
スキル	✅	配備先だけ違う
権限・セキュリティ	❌	ツール個別で管理。概念が異なる

「無理に統一しない」判断も設計のうち、というのが得た教訓でした。

2. TOML のキーにドットが使えない

MCP サーバー名に apidog.lambda のようにドットを入れたら、Codex 用の config.toml 生成で壊れました。TOML ではドットがテーブルの区切りになるためです。**サーバー名はハイフン区切り（apidog-lambda）**に統一して回避しました。

3. AGENTS.md は Codex ターゲットで生成する

apm compile の -t claude で AGENTS.md を作ると、Claude 用には空のスタブが生成されてしまいました。Claude Code はシステムプロンプトを .claude/rules/ から自動で読み込むので AGENTS.md を必要としないためです。

そこで AGENTS.md の生成は -t codex 単体で行うようにしました（apm compile -t codex）。ツールごとに「どの生成物が要るか」を理解して、生成ターゲットを絞るのがコツです。

4. 秘匿情報は生成物に焼き込まない

MCP のアクセストークンなどの秘匿情報は、apm.yml には ${APIDOG_ACCESS_TOKEN} というプレースホルダだけを書きます。実値は各自の ~/.zshrc 等で環境変数として定義します。こうすれば生成される .mcp.json や config.toml にも平文で焼き込まれず、そのままコミットできます。

5. APM のバージョンをローカルと CI で固定する

生成物は APM のバージョンによって微妙に変わり得ます。ローカルでは古い APM、CI では新しい APM、だと永遠に差分が消えない事故が起きます。Makefile と CI の両方で APM_VERSION を明示的に固定して揃えました（記事執筆時点では 0.16.1）。@latest は使いません。

成果：編集は1か所、ズレはCIが弾く

Before / After

項目	Before	After
設定を編集する場所	Claude 用と Codex 用で2系統を手書き同期	`.apm/` + `apm.yml` の1か所
ツール間のズレ	手作業依存で頻発	`make apm-sync` で一斉反映
再生成し忘れ	気づけない	CI が差分検知で失敗させる
新メンバーのオンボード	「どっちが正？」問題	SSOT を見れば分かる／CLI すら不要

数字にしづらい改善ではありますが、体感で一番効いたのは「設定変更の心理的コストが下がった」ことです。1か所直して make apm-sync、あとは CI が守ってくれる。だから MCP のバージョン更新やプロンプト改善を気軽に PR できるようになりました。

まとめ

複数のAIエージェント（Claude Code / Codex）を併用するなら、設定の SSOT 化は投資に見合う
APM で apm.yml + .apm/ を唯一の正にし、各ツールのネイティブ設定は生成物として扱う
生成物をコミットしておけば、利用するだけのメンバーは CLI 不要
CI で再生成ドリフトを検知すれば、「同期し忘れ」を仕組みで防げる
ただし権限・セキュリティ設定は無理に共有せず、ツール個別に。共有できるもの／できないものの線引きが設計の勘所

AIエージェントの設定は、これからますますチームの共有資産になっていきます。「プロンプトも MCP もスキルも、コードと同じようにバージョン管理・レビューする」——その第一歩として、APM は有力な選択肢でした。

参考リンク