- はじめに
- APM とは
- やりたかったこと
- インストール
- 1リポジトリで複数パッケージを管理する
- パッケージの中身を作る
- 利用者側でインストールしてみる
- 複数パッケージを入れるとどうなる
- アップデート
- 使ってみた所感
- まとめ
はじめに
こんにちは。アプリケーションサービス本部ディベロップメントサービス3課の北出です。
業務で Claude Code を使うことがあるのですが、プロジェクトごとに「MCPサーバの設定」や「便利なスキル」「共通のルール（CLAUDE.md）」をそれぞれセットアップしているのが気になっていました。また、これらの仕組みを使いこなすための技術ハードルも感じることがあります。誰かが良い設定を作っても、それを横展開する仕組みがなく、「この設定をコピペしてください」と共有するくらいしか方法がありません。
そんな中、Microsoft が公開している microsoft/apm（Agent Package Manager）というツールを見つけました。一言でいうと「AIエージェント設定のためのパッケージマネージャ」で、package.json や requirements.txt のエージェント設定版です。
今回はこの APM を使って、Claude Code の設定（MCPサーバ・スキル・エージェント・共通ルール）を配布する仕組みを実際に作ってみたので共有します。
APM とは
APM は AIエージェントの設定をパッケージとして管理・配布できるツールです。公式では3つの特徴が挙げられています。
- マニフェストで再現できる（Portable by manifest） —
apm.yml一つでエージェント設定を記述し、apm installでどこでも再現できる - デフォルトで安全（Secure by default） — インストール時にコンテンツをスキャンし、ロックファイルで整合性を担保する
- ポリシーで統制できる（Governed by policy） — 組織ポリシーで「許可するソース・スコープ」を制御できる
対応クライアントは GitHub Copilot / Claude Code / Cursor / OpenCode / Codex / Gemini / Windsurf と幅広く、同じ apm.yml から各クライアント向けの設定を生成してくれます。今回は Claude Code を対象に進めます。
やりたかったこと
今回のゴールは以下です。
- 社内の GitHub に配布用リポジトリを 1つ 作る（リポジトリの乱立は避けたい）
- そのリポジトリから、Claude Code 向けに以下を配布する
- MCPサーバ設定（AWS公式ドキュメントを参照できる AWS MCP）
- 共通ルール（AWS情報は必ずMCPで最新情報を確認する、という利用原則）
- スキル（AWS技術質問に最新情報で答える）
- エージェント（ファイルがAWSセキュリティベストプラクティスに沿っているかレビューする）
インストール
まずは APM CLI をインストールします。
# macOS / Linux brew install microsoft/apm/apm
# 確認 apm --version
1リポジトリで複数パッケージを管理する
最初に気になったのが「パッケージごとにリポジトリを分けないといけないのか？」という点でした。これだとパッケージが増えるたびにリポジトリが乱立してしまいます。
調べたところ、APM はサブディレクトリを個別パッケージとして参照できる モノレポ構成 を公式にサポートしていました。これなら1リポジトリで複数のパッケージを管理できます。
今回作ったリポジトリの構成は以下です。
apm-packages/ ← 配布用リポジトリ（1つだけ）
└── packages/
└── aws-mcp/ ← AWS MCP 関連をまとめたパッケージ
├── apm.yml ← パッケージマニフェスト
├── README.md
└── .apm/
├── instructions/
│ └── aws-mcp.instructions.md ← 共通ルール
├── skills/
│ └── aws-qa/
│ └── SKILL.md ← スキル
└── agents/
└── aws-security-reviewer.agent.md ← エージェント
将来的に packages/github-mcp/ のように別パッケージを追加していけるので、リポジトリは1つで済みます。
パッケージの中身を作る
APM では、配布する設定の一つひとつ（instructions / skills / agents / MCPサーバなど）を「primitive（プリミティブ）」と呼びます。以降ではこの呼び方を使います。
各ファイルを作る前に、配布側（.apm/）に置いた primitive が、利用者側（.claude/）のどこに展開されるのかを先に整理しておきます。これを頭に入れておくと、以降の各ファイルの説明が掴みやすいと思います。
配布側（.apm/） |
利用者側（.claude/） |
|---|---|
.apm/instructions/<name>.instructions.md |
.claude/rules/<name>.md |
.apm/skills/<name>/SKILL.md |
.claude/skills/<name>/SKILL.md |
.apm/agents/<name>.agent.md |
.claude/agents/<name>.md |
apm.yml の dependencies.mcp |
.mcp.json の mcpServers |
それぞれ作っていきます。
apm.yml（マニフェスト）
パッケージの心臓部です。ここに MCPサーバの定義を書きます。
name: aws-mcp version: 1.0.0 description: AWS MCP サーバの設定・利用原則を Claude Code へ配布する author: your-org license: UNLICENSED includes: auto targets: - claude dependencies: apm: [] mcp: - name: aws-mcp registry: false transport: stdio command: uvx args: - mcp-proxy-for-aws@latest - https://aws-mcp.us-east-1.api.aws/mcp - --metadata - AWS_REGION=ap-northeast-1 scripts: {}
instructions（共通ルール）
.apm/instructions/aws-mcp.instructions.md に、AWS情報を扱う際の利用原則を書きます。冒頭の description は必須です。
--- description: AWS MCP サーバを使った情報確認の利用原則 --- ## AWS情報の確認 AWS関連の質問・要求があった場合、**必ずMCPツールで最新情報を確認**してから回答する。 ### 使用するMCPツール | ツール | 用途 | |---|---| | `mcp__aws-mcp__aws___search_documentation` | AWS公式ドキュメント検索（topicsパラメータ指定可） | | `mcp__aws-mcp__aws___read_documentation` | 特定ドキュメントページの読み込み | | `mcp__aws-mcp__aws___recommend` | 関連ドキュメントの推薦 | | `mcp__aws-mcp__aws___get_regional_availability` | リージョン別サービス可用性確認 | ### topicsパラメータ - `cdk_docs` — CDKドキュメント - `cloudformation` — CloudFormationドキュメント - `cdk_constructs` — CDKコードサンプル - `general` — ベストプラクティス・アーキテクチャガイド ### 例外（MCP使用を省略してよい場合） - 一般的な概念の説明（「クラウドとは」等） - AWS以外の技術質問 - 既にMCPで確認済みの情報の再利用
skills（スキル）
.apm/skills/aws-qa/SKILL.md に、AWS技術質問に答えるスキルを定義します。スキルはディレクトリ名と name を揃える必要があります。
スキルの内容は以下です。冒頭の description でトリガー条件を、本文で具体的な手順とルールを書く構成です。
今回は APM の利用が主目的のため、スキルやエージェントは簡素なものにします。
--- name: aws-qa description: AWSのサービス・機能・設定・アーキテクチャ・ベストプラクティスに関する技術的な質問を受けたときに使用する。aws-mcp を通じてAWS公式ドキュメントから最新情報を取得して回答する。 --- # AWS技術質問回答スキル AWS関連の技術的な質問に対して、aws-mcpツールで最新の公式ドキュメントを参照し、正確な情報を回答する。 ## 手順 1. 質問を分析し、関連するAWSサービス・機能を特定する 2. `mcp__aws-mcp__aws___search_documentation` で関連ドキュメントを検索する 3. `mcp__aws-mcp__aws___read_documentation` で該当ページの詳細を確認する 4. 必要に応じて `mcp__aws-mcp__aws___recommend` で関連ドキュメントも参照する 5. リージョン固有の質問には `mcp__aws-mcp__aws___get_regional_availability` を使用する 6. 取得した情報をもとに回答を構成し、参照URLを必ず提示する ## 回答品質ルール - 学習データのみに基づいた回答はしない。必ずMCPで公式ドキュメントを参照してから回答する - 不確実な情報は「不確実」と明示する - 公式ドキュメントのURLを可能な限り提示する - 古い情報や廃止された機能を提案しない ## 例外（MCP省略可） - 一般的な概念の説明（「クラウドとは」等） - AWS以外の技術質問 - 既にMCPで確認済みの情報の再利用
description は「どういうときに使うか」を書くのがポイントです。Claude Code はこの description を読んで、質問に応じてスキルを自動で選択してくれます。本文は普段使っている指示をそのまま書けるので、自分のドメインのルールに置き換えるイメージが湧きやすいと思います。
agents（エージェント）
.apm/agents/aws-security-reviewer.agent.md に、AWSセキュリティレビュー用のサブエージェントを定義します。
--- name: aws-security-reviewer description: 対象ファイル（CDK・CloudFormation・Terraform・ポリシードキュメント等）がAWSセキュリティベストプラクティスに沿っているかレビューしたいときに使用する。構造化されたマークダウンのレビュー結果を出力する。 model: claude-opus-4-7 tools: - Read - Glob - Grep - Write - mcp__aws-mcp__aws___search_documentation - mcp__aws-mcp__aws___read_documentation - mcp__aws-mcp__aws___recommend - mcp__aws-mcp__aws___get_regional_availability --- # AWSセキュリティレビューエージェント 対象ファイルをAWSセキュリティベストプラクティスに基づいてレビューし、 マークダウン形式でレビュー結果を出力する。 （以下、レビュー観点や出力フォーマットを記載）
エージェントでは model で使用モデルを固定したり、tools で使えるツールを絞り込めます。今回はレビューに必要な読み取り系ツールと AWS MCP のツールだけを許可しています。
なお model に指定する値は Claude Code のモデル指定形式（opus などのエイリアス、またはフルのモデル名）に従います。利用する環境で使えるモデル名に合わせてください。
利用者側でインストールしてみる
ここまでで配布側の準備ができたので、利用者の立場で動作確認をします。別のディレクトリを作ってインストールしてみます。
apm install your-org/apm-packages/packages/aws-mcp --target claude
your-org の部分は配布リポジトリを置いた GitHub Organization 名に読み替えてください。
--target claude を付けているのは、まだ .claude/ ディレクトリがないプロジェクトだとクライアントが自動検出されず、以下のように案内が出るためです。
[x] No harness detected
.claude/ があるプロジェクトなら自動で Claude Code 向けに展開されます。
何がどこに展開されるか
インストール後、利用者側のディレクトリを確認すると、以下のように展開されていました。
プロジェクトルート/
├── apm.yml ← インストールしたパッケージが追記された
├── apm.lock.yaml ← 解決したバージョンを固定
├── .gitignore ← apm_modules/ が自動追加された
├── apm_modules/ ← パッケージのキャッシュ（取得元）
├── .mcp.json ← MCPサーバ設定が追記された
└── .claude/
├── rules/
│ └── aws-mcp.md ← instructions が展開された
├── skills/
│ └── aws-qa/
│ └── SKILL.md ← skill が展開された
└── agents/
└── aws-security-reviewer.md ← agent が展開された
primitive 4種類（instructions / skills / agents / MCP）は先に整理したマッピングの通り想定どおりの場所に展開され、加えて apm.yml・apm.lock.yaml・.gitignore・apm_modules/ といった管理用のファイルも生成されていました。
apm_modules/ について補足すると、これは npm でいう node_modules/ に相当するパッケージのキャッシュで、GitHub から取得したパッケージの実体がここにクローンされます。そこから各ファイルが .claude/ や .mcp.json に展開（hoist）される、という流れです。実際に Claude Code が読むのは .claude/ 側で、apm_modules/ はあくまで取得元のキャッシュになります。
この apm_modules/ は apm install 時に自動で .gitignore へ追加してくれます（ログにも Added apm_modules/ to .gitignore と出ていました）。なのでコミット対象になるのは apm.yml と apm.lock.yaml だけで、この点も npm と同じ感覚です。
一つ発見だったのが、instructions の展開先です。てっきり .claude/CLAUDE.md に追記されるのかと思っていたのですが、実際には .claude/rules/aws-mcp.md という独立したファイルとして配置されていました。
余談ですが、rules 内のファイルに paths を指定しない場合は、起動時に CLAUDE.md と同様にコンテキストへ読み込まれます。なので CLAUDE.md に直接追記されなくても、共通ルールとして効く形になります。
.mcp.json の中身もちゃんと変換されていました。
{ "mcpServers": { "aws-mcp": { "type": "stdio", "command": "uvx", "args": [ "mcp-proxy-for-aws@latest", "https://aws-mcp.us-east-1.api.aws/mcp", "--metadata", "AWS_REGION=ap-northeast-1" ] } } }
複数パッケージを入れるとどうなる
ここまでは aws-mcp パッケージ1つだけでしたが、実運用ではパッケージが増えていくはずです。複数入れたときに既存の設定が壊れたりしないか気になったので、2つ目のパッケージを追加して挙動を確認してみました。
題材として、GitHub MCP を配布する github-mcp パッケージを別途用意し、aws-mcp が入っている状態で追加インストールしてみます。
apm install your-org/apm-packages/packages/github-mcp --target claude
インストールログを見ると、MCPサーバが2つ認識され、既存の aws-mcp はスキップしつつ github だけが新しく追加されていました。
+- MCP Servers (2) | [+] aws-mcp (already configured) | [>] github (self-defined, stdio) | +- Configuring for Claude... | [+] github -> Claude (configured)
結果として、各ファイルは以下のように共存していました。
.mcp.json…aws-mcpとgithubの2サーバが追記マージされた（既存は維持される）.claude/rules/…aws-mcp.mdとgithub-mcp.mdが別ファイルで共存apm.yml…dependencies.apmに2パッケージが並んで記録されるapm.lock.yaml… 2パッケージそれぞれの解決済みコミットが記録される（これをコミットしておけば、他のメンバーも同じバージョンで揃う）
参考までに、利用者側の apm.yml は以下のようになっていました。インストールしたパッケージが dependencies.apm に追記されていく形です。
name: apm-test version: 1.0.0 description: APM project for apm-test author: your-handle dependencies: apm: - your-org/apm-packages/packages/aws-mcp - your-org/apm-packages/packages/github-mcp mcp: [] includes: auto scripts: {}
{ "mcpServers": { "aws-mcp": { "type": "stdio", "command": "uvx", "args": [ "..." ] }, "github": { "type": "stdio", "command": "docker", "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}" }, "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ] } } }
展開先のファイル名が、パッケージ内の定義名（rules なら <name>.md、MCPサーバなら name フィールド）ベースになっているため、名前が被らない限り衝突せずに足していけます。npm でパッケージを追加していくのと同じ感覚です。
逆に言うと、別パッケージで同じ名前のスキルやMCPサーバを定義してしまうと衝突する可能性があるので、パッケージをまたいで命名は揃えない方が安全そうです。
アップデート
特定のパッケージだけ更新したい場合は、apm install に --update を付けます。
apm install your-org/apm-packages/packages/aws-mcp --target claude --update
インストール済みのパッケージをまとめて更新したい場合は apm update が使えます。apm.yml に書かれた全依存を一括で最新に再解決してくれます（npm の npm update と同じ感覚です）。
apm update
apm update は適用前に「追加・更新・削除・変更なし」の変更プランを表示してくれて、デフォルトでは確認プロンプトで止まります。CI など非対話で流したい場合は --yes、変更内容だけ見たい場合は --dry-run が使えます。
なお、更新があるかどうかだけ確認したい場合は apm outdated も用意されています。一度インストールするとキャッシュされるので、配布側を更新した後に利用者側へ反映するときは --update か apm update が必要、という点は覚えておくとよさそうです。
使ってみた所感
メリット
apm.yml一つで MCP・スキル・エージェント・ルールをまとめて配布できる- 1リポジトリで複数パッケージを管理でき、リポジトリが乱立しない
- 利用者は
apm install一発でセットアップが完了する - ロックファイルで全員が同じバージョンを使えるので、設定のばらつきがなくなる
- Claude Code 以外（Copilot や Cursor）にも同じ定義から展開できる拡張性がある
デメリット・注意点
- 利用者側に
uvx（uv）や Docker など、MCPサーバの実行環境が別途必要 - パッケージをまたいで同名のスキル・MCPサーバを定義すると衝突しうるので、命名ルールを決めておく必要がある
- 配布側を更新しても利用者側には自動反映されず、
--updateを明示的に叩いてもらう必要がある（オプトインなので周知が要る） apm-policy.ymlによるガバナンス（許可ソースの制限など）はまだ試せていないので、組織展開時はこの辺りの検証が別途必要そう
まとめ
Microsoft APM を使って、社内向けに Claude Code の設定を配布する仕組みを作ってみました。
これまで手作業でやっていた MCP・スキル・エージェントのセットアップが、apm install 一発で揃うのはかなり快適だと感じました。特に「良い設定を作った人がいたら、パッケージとして追加して全員に展開する」という流れが自然に作れるのが良いです。
社内でAIエージェントの設定を標準化したいけど良い方法がない、という方は一度触ってみると良いと思います。今後はパッケージの種類を増やしたり、組織ポリシー（apm-policy.yml）でガバナンスをかける部分も試してみたいと思います。
