agent-package-manager

Agent Package Manager

手順

ステップ 1：リポジトリと、求められている APM の成果を評価する

1. リポジトリのルートで、apm.yml、apm.lock.yaml、.github/、.claude/、.cursor/、.opencode/、apm_modules/ を確認します。
2. apm --version と apm config を実行し、インストール済みの CLI と現在の設定を確認します。
3. apm.yml が存在する場合、依存関係、スクリプト、コンパイル設定を変更する前に references/manifest-and-lockfile.md を読みます。
4. パッケージのインストール、更新、整理、削除に関する依頼の場合、APM コマンドを実行する前に references/command-workflows.md を読みます。
5. apm.yml が存在せず、ユーザーがリポジトリで APM を使いたい場合は、apm init または apm init --yes でプロジェクトを初期化します。
6. リポジトリがすでに別のエージェント設定フローを使用しており、ユーザーから移行を求められていない場合は、既存の設定を置き換えず、依頼された APM の範囲に変更を限定します。

ステップ 2：マニフェストを慎重に整備または修復する

1. リポジトリに新規または修復済みのマニフェスト構造が必要な場合は、assets/apm.yml.template を読みます。
2. name と version をトップレベルに必ず記述します。これらは必須の契約フィールドとして扱います。
3. APM パッケージの依存関係は dependencies.apm に、MCP サーバーは dependencies.mcp に追加します。
4. インストール後は、apm.yml で正規の依存関係形式を優先します。GitHub でホストされているスキルやパッケージには、たとえば webmaxru/agent-skills/skills/webmcp のように、リポジトリで使われている省略形式 owner/repo/path をデフォルトで使用し、明示的な path、ref、alias は必要な場合にのみ保持します。
5. 再現性を自動的な変更の追従より重視する場合は、チームで共有するパッケージに固定 ref を使用します。
6. ローカルパス依存関係は、ローカルで開発を続けている間だけ使用します。バンドル配布を推奨する前に、リモート参照に置き換えます。
7. 依頼にスクリプトが含まれる場合は、scripts の下に定義し、各スクリプトを apm list、apm preview、または apm run でプレビューまたは実行できることを確認します。

ステップ 3：推測ではなく検証に基づいて依存関係を管理する

1. リポジトリにすでにインストール済みのパッケージがある場合、リスクのある変更は apm install --dry-run、apm uninstall --dry-run、または apm prune --dry-run で事前に確認します。
2. 依頼の範囲に応じて、apm install、apm install <package>、apm install --update、または apm deps update でパッケージをインストールまたは更新します。
3. apm install --update または apm deps update の実行後、ロックファイルの resolved_commit が実際に変更されたことを確認します。古いキャッシュからパッケージが提供された場合は、references/troubleshooting.md の「Stale packages after update」ワークフローに従います。
4. リポジトリから単一のスキルをインストールする依頼の場合は、あいまいなリポジトリのみのプレースホルダーではなく、たとえば apm install webmaxru/agent-skills/skills/webmcp のように、そのスキルのディレクトリまで指定したパッケージパスを提示します。
5. 依存関係の変更後は、apm deps list、apm deps tree、または apm deps info <package> で解決済みの状態を確認します。
6. apm.lock.yaml は、解決済みのコミットとデプロイ済みファイルの信頼できる情報源として扱います。チームや CI での再現性を確保するため、コミットを推奨します。
7. リポジトリで MCP の検出または選択が必要な場合は、MCP のエントリーを手動で編集する前に、apm mcp list、apm mcp search <query>、apm mcp show <server> を使用します。
8. インストール時の出力に競合やスキップされたファイルが示された場合は、強制オプションで再試行する前に references/troubleshooting.md を読みます。
9. リポジトリが自身のパッケージを使用する（自己参照依存関係）場合、APM が取得するには変更をコミットしてプッシュする必要があることをユーザーに伝えます。references/troubleshooting.md の「Self-referencing dependencies」セクションを読みます。 ステップ 4：価値がある場合にのみコンパイルと検証を行う
10. コンパイル戦略やターゲットの選択を変更する前に、references/command-workflows.md を読んでください。
11. 目的が出力の生成ではなく正確性の確認である場合は、プリミティブを検証するために apm compile --validate を使用してください。
12. 大規模なコンパイル変更を行う前、または配置の判断を確認する際は、apm compile --dry-run を使用してください。
13. 対応ツールでは apm install によってプロンプト、エージェント、スキル、フック、MCP 統合がすでにデプロイされることを説明してください。apm compile は主に AGENTS.md や CLAUDE.md などの指示ファイルを生成するためのものです。
14. リポジトリが複数のランタイムやツール群に対応する場合は、明示的なターゲットを使用してください。
15. コンパイルで生成済みの出力を再スキャンしないよう、compilation.exclude をビルドディレクトリや依存関係ディレクトリに合わせてください。
16. 作成中に継続的な再生成が必要な場合は、単発の検証手順が問題なく完了した後にのみ apm compile --watch を使用してください。

ステップ 5：スクリプト、ランタイム、配布のフローを適切に運用する

1. スクリプトを実行する前に、apm list でプロジェクトのスクリプトを一覧表示してください。
2. 自動化やデバッグのワークフローで apm run <script> -p key=value を使用する前に、apm preview <script> -p key=value でプロンプト駆動型スクリプトをプレビューしてください。
3. リポジトリが APM 管理のランタイムに依存する場合は、apm runtime status、apm runtime list、apm runtime setup <runtime> を使用してください。
4. CI の並列実行、エアギャップ環境への配布、リリースの追跡可能性が目的の場合は、references/command-workflows.md を読み、インストールが正常に完了して apm.lock.yaml とデプロイ済みファイルが生成された後にのみ apm pack を使用してください。
5. 以前にパックしたバンドルを追加で展開する場合にのみ apm unpack を使用してください。依存関係の作成に代わるものとして提示しないでください。
6. インストールを繰り返すことで、回避可能な CI コストやネットワークリスクが生じる場合は、apm-action またはビルド済みバンドルを推奨してください。

エラー処理

• apm が見つからない場合は、まずインストールまたは更新し、プロジェクトファイルを編集する前に apm --version で確認してください。
• apm install で認証エラーが報告された場合は、references/troubleshooting.md を読み、再試行する前にホスト認証を修正してください。
• apm install でファイルの競合が報告された場合は、診断の概要を確認し、必要に応じて --verbose を付けて再試行してください。--force を使用するのは、ローカルファイルを上書きすることが明確に意図されている場合に限ってください。
• ユーザーのツールチェーンで apm compile が不要な場合は、無駄な作業として追加せず、より簡潔なインストールのみの手順を優先してください。
• apm.lock.yaml がない、またはデプロイ済みファイルがないために apm pack が失敗した場合は、再試行する前に apm install を再実行してください。
• リポジトリがローカルパスのパッケージに依存する場合は、それらの依存関係をリモート参照に置き換えるまで apm pack を推奨しないでください。