はじめに

AIコーディング支援ツールの活用が開発現場で話題になる中、私たちのチームもあるシステムの移行プロジェクトを契機にAIを本格的に開発へ取り入れました。

コード生成・レビュー・ドキュメント作成など幅広い場面で主にGitHub Copilotを活用し、一定の成果を感じはじめた頃、「AIが意図しないコードを生成する」という問題に直面するようになりました。チームのコーディング規約や設計方針に沿わない実装が混入することがあり、レビューコストが増える場面が出てきたのです。

この問題への対処として、ナレッジ（AGENTS.md、SKILL.md）を整備し、「チームとしてAIに何をどう伝えるか」を明文化する取り組みを始めました。その過程で、今度は別の課題が見えてきました。整備したナレッジを複数のリポジトリーへ展開しようとしたとき、手作業でコピーして回る運用では更新管理が煩雑になると気づいたのです。

この記事では、AIの挙動をチームで制御するためのナレッジ整備の実践と、そのナレッジを一元管理・配布するための仕組みとしてAgent Package Manager（APM）を活用した取り組みを紹介します。

活用への課題

チームでAIの活用を進めていく中で、各々が上手くいったこと・困ったことを共有する時間を設けるようになりました。その中で挙がったのが、主に2つの課題です。1つは、独自のコーディング規約（改行ルールや1行あたりの文字数など）がAIに反映されず、人が修正する箇所が残ること。もう1つは、AIへのレビュー指示が曖昧だと正確な結果が返ってこず、有効に活用できないことでした。

根本的な原因は、プロジェクト固有のルールをAIが知らないことです。都度プロンプトで伝えるという手段はありますが、毎回手間がかかる上にチーム内での統一も難しく、本質的な解決にはなりません。

ナレッジ整備

そこで、AIエージェントが自動で読み込むナレッジ（AGENTS.md、SKILL.md）を整備し、この課題への対処を試みました。AGENTS.mdには独自のコーディング規約や設計方針を、SKILL.mdにはレビューの観点と出力フォーマットを明文化しました。一度書いておけばセッションをまたいでも有効で、チーム全体で共通の行動指針として共有できます。

製造工程では、コーディング規約に沿った書式やコメントがAGENTS.mdの指示通りに生成されるようになり、人が修正する箇所が減りました。レビューでは、SKILL.mdで定義した観点と出力フォーマットに従って結果が返ってくるようになり、有効に活用できるようになりました。

共通ルールをセッションをまたいで継続的に参照させることで、AIの出力が安定し、レビューコストの低減につながりました。

展開への課題

こうした取り組みにより各工程での手応えを実感し始めたことで、整備したナレッジをほかのシステムにも展開したいと考えました。AGENTS.mdは各システムの事情に限られた内容を記しているのに対して、SKILL.mdには私たちの開発全般における作業手順などが記載されており再利用が効くと考えたためです。最初に思いつく方法は単純で、整備したナレッジを各リポジトリーへコピーして使うというものです。実際、はじめのうちはこれで問題なく動きます。

ただし、ナレッジは一度書いて終わりではありません。実際の開発を通じて「この指示は曖昧だった」「こういうケースが考慮できていなかった」という気づきが生まれ、そのフィードバックを反映させながら改善していくことで、効果をより高めていくことができます。ナレッジ整備の価値は、こうした「使う→改善」のサイクルを継続して回せることにあります。

問題は、コピペ運用ではそのサイクルのコストが一気に上がることでした。1か所を改善したとき、同じ内容を管理するすべてのリポジトリーへ手作業でコピーしなければなりません。この手間は、改善を検討するたびに重くのしかかっていき、「直したいが、全リポジトリーに反映する作業を考えるとなかなか踏み切れない」というジレンマが生まれ、フィードバックループが自然と止まりやすくなってしまいます。

加えて、AIモデルのバージョンアップがナレッジの見直しを迫ることもあります。たとえば、2026年4月に公開されたClaude Opus 4.7ではトークナイザーの変更が行われたことで、それまでのナレッジが意図通りに解釈されなくなってしまうという話もありました¹。

能動的な改善であるにしろ受動的な対応であるにしろ、すべてのリポジトリーへコピーして回る運用は、繰り返すたびに負担が積み重なっていきます。

こうした経緯から、ナレッジを1か所で管理して必要なリポジトリーへ配布する仕組みを模索しました。GitHub CLIのgh skillコマンドがまず候補に挙がりましたが、どうやらナレッジの取得元として指定できるのはGitHubリポジトリーに限られているようでした。私たちはself-hosted GitLabを使っているので、そこにナレッジを置いても直接参照できません。任意のGitホストに対応するツールを探した結果、次に紹介するAgent Package Manager（APM）にたどり着きました。

Agent Package Manager

Agent Package Manager ⧉（APM）は、マイクロソフトが公開しているオープンソースのパッケージマネージャーです。これまで整備してきたAGENTS.mdやSKILL.mdといったナレッジを、npmやpipと同じ感覚で配布・管理できます。

ナレッジの取り込み

使い方はシンプルです。リポジトリーにapm.ymlを置き、導入したいナレッジパッケージを宣言します（以下は最小限の記述例です）。

1
name: my-project
2
version: 1.0.0
3
dependencies:
4
  apm:
5
    - myorg/agent-standards#v1.0.0

あとはapm installを実行するだけです。チームメンバーも同じコマンドひとつで同じナレッジ構成を再現できます。ロックファイル（apm.lock.yaml）にコミットSHAとコンテンツハッシュが記録されるため、バージョン管理と再現性も確保されます。

また、GitHubやGitLabなど任意のGitホストをそのまま参照できます。セルフホスト環境にも対応しており、apm.ymlにHTTPSまたはSSHのURLを直接記述することで、self-hosted GitLabなど、プライベートなGitホストでの運用も可能です。

1
dependencies:
2
  apm:
3
    - https://gitlab.internal/myorg/agent-standards.git#v1.0.0

パッケージの作成と配布

私たちのナレッジをパッケージとして公開することも簡単に行えます。apm.ymlと.apm/ディレクトリーを配置した場所がパッケージとして認識されるため、1つのリポジトリーに複数のパッケージを収めることもでき、私たちはナレッジ管理専用のリポジトリーにpackages/ディレクトリーを設けて複数パッケージを一元管理しています。

1
agent-knowledge/
2
└── packages/
3
    ├── package-a/
4
    │   ├── apm.yml
5
    │   └── .apm/
6
    │       ├── instructions/
7
    │       └── skills/
8
    └── package-b/
9
        ├── apm.yml
10
        └── .apm/
11
            └── skills/

パッケージ側のapm.ymlはパッケージのメタデータと内容を定義するためのもので、利用側のapm.ymlはどのパッケージを取り込むかを依存関係として宣言するためのものです。同じファイル名ですが役割が異なります。

利用側では、git:とpath:でリポジトリー内のサブディレクトリーを指定することで、パッケージを参照できます。

1
dependencies:
2
  apm:
3
    - git: https://gitlab.internal/myorg/agent-knowledge.git
4
      path: packages/package-a
5
      ref: v1.0.0

ナレッジを改善したときは、管理側のapm.ymlのバージョンを更新し管理リポジトリーにプッシュ、各リポジトリーでapm updateを実行します。これだけで全リポジトリーへの反映が完了します。

APMを試す

動作環境

Dev Container環境への導入

私たちの開発環境ではDebian系のOSイメージを使ってDev Containerを構築しており、APMをそこへ導入するところから始めました。

まず公式の案内に従い、インストールスクリプトを実行してみました。スクリプト自体はDev Container環境を検知して警告を出してくれるのですが、バイナリのテストに失敗しました。

1
$ curl -sSL https://aka.ms/apm-unix | sh
2
...
3
[!] Container/Dev Container environment detected
4
Note: PyInstaller binaries may have compatibility issues in containers.
5
If installation fails, consider using: pip install --user apm-cli
6
...
7
[PYI-xxxx:ERROR] Failed to load Python shared library '...libpython3.12.so.1.0':
8
  /lib/x86_64-linux-gnu/libm.so.6: version `GLIBC_2.38' not found

APMのバイナリはPyInstallerでビルドされており、コンテナのlibc6バージョンが古い環境では動作しませんでした。そこで、インストールスクリプトの案内に従いpipでの導入を試みましたが、今度はPEP 668によってOSのパッケージ管理システムで管理されている環境へのインストールが制限されており、こちらも失敗しました。

1
$ pip install apm-cli
2
error: externally-managed-environment
3

4
× This environment is externally managed
5
╰─> To install Python packages system-wide, try apt install
6
    python3-xyz, where xyz is the package you are trying to
7
    install.
8
...
9
    If you wish to install a non-Debian packaged Python application,
10
    it may be easiest to use pipx install xyz, which will manage a
11
    virtual environment for you. Make sure you have pipx installed.
12
...
13
hint: See PEP 668 for the detailed specification.

今度は、エラーメッセージでpipxが推奨されていたので試したところ、インストールが通りました。

1
$ pipx install apm-cli
2
  installed package apm-cli 0.14.0, installed using Python 3.11.2
3
  These apps are now globally available
4
    - apm
5
done! ✨ 🌟 ✨

これでAPMを利用する準備が完了しました。

pipxを利用してAPMを導入した場合、バイナリを更新するコマンドapm self-updateが実行できませんでした。理由は同コマンドがpipを使って最新のバイナリに更新しようとするためです。ただし、pipx側の更新コマンドであるpipx upgrade apm-cliを使うことで回避できたため、現時点で困ったことにはなっていません。

パッケージの適用

続いて、リポジトリーにapm.ymlを作成して導入したいパッケージを宣言し、apm installを実行します。

1
name: my-project
2
version: 1.0.0
3
targets:
4
  - copilot
5
dependencies:
6
  apm:
7
  - git: https://gitlab.internal/myorg/agent-knowledge.git
8
    path: packages/package-b
9
    ref: main

1
$ apm --version
2
Agent Package Manager (APM) CLI version 0.14.0
3
$ apm install
4
[>] Installing dependencies from apm.yml...
5
[i] Targets: copilot  (source: apm.yml)
6
  [+] gitlab.internal/myorg/agent-knowledge/packages/package-b#main #main @123abcd (cached)
7
  |-- 2 skill(s) integrated -> .agents/skills/
8

9
[*] Installed 1 APM dependency in 1.8s.

apm.ymlに宣言したパッケージが.agents/skills/へ展開され、GitHub Copilotがスキルを参照できる状態になりました。

おわりに

この記事では、AIエージェントが参照するナレッジ（AGENTS.md、SKILL.md）を整備してAIのふるまいをチームで制御する取り組みと、そのナレッジをAPMで一元管理・配布する仕組みを紹介しました。

ナレッジを整備することで、プロジェクト固有のルールや設計方針を、セッションをまたいでAIに伝え続けられます。APMを活用することで、そのナレッジの改善サイクルを止めずに複数リポジトリーへ展開する運用を、実際に試すことができました。「AIのふるまいを整える」「そのナレッジ自体を継続的に改善できる仕組みにする」という2つをセットで考えることが、チームでAIを安定して活用していくうえで大切だと感じています。

ナレッジを複数のリポジトリーで共有・管理したいと考えている方は、ぜひAPMを試してみてください。

参考

• Agent Package Manager（APM）- GitHub ⧉
• APM 公式ドキュメント ⧉