agent-package-manager

Agent Package Manager

手順

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

1. リポジトリのルートで、apm.yml、apm.lock.yaml、.github/、.claude/、.codex/、.cursor/、.gemini/、.grok/、.opencode/、.windsurf/、.kiro/、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/web-ai-agent-skills/skills/webmcp のような、リポジトリの省略形式 owner/repo/path をデフォルトとして使用し、明示的な path、ref、alias は必要な場合にのみ保持します。
5. 再現性が自動的な変更より重要な共有チーム用パッケージでは、固定した参照を使用します。
6. ローカルパスの依存関係は、開発中のみ使用します。バンドル配布を推奨する前に、リモート参照に置き換えます。
7. 依頼にスクリプトが含まれる場合は、scripts の下に定義し、各スクリプトを apm list、apm preview、または apm run でプレビューまたは実行できることを確認します。 ステップ 3: 推測ではなく検証によって依存関係を管理する
8. リポジトリにインストール済みのパッケージがある場合は、リスクの高い変更を行う前に apm install --dry-run、apm uninstall --dry-run、または apm prune --dry-run でプレビューします。
9. 要求された範囲に応じて、apm install、apm install <package>、apm install --update、または apm deps update でパッケージをインストールまたは更新します。
10. apm install --update または apm deps update の実行後、ロックファイルの resolved_commit が実際に変更されたことを確認します。古いキャッシュからパッケージが提供された場合は、references/troubleshooting.md の「Stale packages after update」ワークフローに従います。
11. リポジトリから単一のスキルをインストールする依頼の場合は、曖昧なリポジトリのみのプレースホルダーではなく、次の例のようにスキルディレクトリまでのパッケージパスを指定します：apm install webmaxru/web-ai-agent-skills/skills/webmcp。
12. 依存関係の変更後は、apm deps list、apm deps tree、または apm deps info <package> で解決済みの状態を確認します。
13. 解決済みコミットとデプロイ済みファイルの正しい情報源として apm.lock.yaml を扱います。チームや CI での再現性を確保するため、コミットするよう推奨します。
14. リポジトリで MCP の検出または選択が必要な場合は、MCP エントリを手動で編集する前に apm mcp list、apm mcp search <query>、apm mcp show <server> を使用します。
15. インストールの出力に競合やスキップされたファイルが報告された場合は、強制オプションを使って再試行する前に references/troubleshooting.md を読みます。
16. リポジトリが自身のパッケージを使用する場合（自己参照依存関係）、APM が取得する前に変更をコミットしてプッシュする必要があることをユーザーに伝えます。references/troubleshooting.md の「Self-referencing dependencies」セクションを読みます。
17. apm install はデプロイ前に、隠し Unicode やコンテンツハッシュの検証を含め、パッケージのセキュリティ上の脅威をスキャンすることに留意してください。また、dependencies.mcp で明示的に宣言されているか、信頼済みでない限り、推移的 MCP サーバーをデフォルトでブロックします。オプトインは不要です。スキャンで警告が出たりインストールがブロックされたりした場合は、チェックを回避するのではなく、指摘されたコンテンツに対処します。
18. リポジトリが apm-policy.yml を適用する組織に属している場合、インストール時にポリシーが適用され、デフォルトの推移的 MCP ブロックに加えて、依存関係のソース制限などの追加制限が課されることがあります。ポリシーによってインストールがブロックされた場合は、ポリシーファイルを確認するか、組織の管理者に問い合わせます。強制措置を回避しようとしてはいけません。

ステップ 4: 価値がある場合にのみコンパイルと検証を行う

1. コンパイル戦略やターゲットの選択を変更する前に、references/command-workflows.md を読みます。
2. 目的が出力の生成ではなく正確性の確認である場合は、apm compile --validate を使用してプリミティブを検証します。
3. 大規模なコンパイル変更を行う前、または配置の判断を確認する際は、apm compile --dry-run を使用します。
4. サポート対象のツールでは、apm install がプロンプト、エージェント、スキル、フック、MCP 統合をすでにデプロイすることを説明します。apm compile は主に AGENTS.md や CLAUDE.md などの指示ファイルを生成するためのものです。
5. リポジトリが複数のランタイムまたはツールファミリーに対応する場合は、明示的なターゲットを指定します。
6. コンパイルで生成済みの出力が再スキャンされないよう、compilation.exclude をビルドディレクトリおよび依存関係ディレクトリに合わせます。
7. 作成中に継続的な再生成が必要な場合は、単発の検証手順に問題がないことを確認してから apm compile --watch を使用します。 ステップ 5：スクリプト、ランタイム、配布フローを適切に運用する
8. スクリプトを実行する前に、apm list でプロジェクトのスクリプトを一覧表示します。
9. 自動化またはデバッグのワークフローで apm run <script> -p key=value を使用する前に、プロンプト駆動型スクリプトを apm preview <script> -p key=value でプレビューします。
10. リポジトリが APM 管理ランタイムに依存している場合は、apm runtime status、apm runtime list、apm runtime setup <runtime> を使用します。
11. 目的が CI のファンアウト、エアギャップ環境への配布、またはリリースの追跡可能性である場合は、references/command-workflows.md を読み、インストールが正常に完了して apm.lock.yaml とデプロイ済みファイルが生成された後に限り apm pack を使用します。
12. apm unpack は、以前にパックしたバンドルを追加抽出する場合にのみ使用します。依存関係の定義に代わるものとして紹介しないでください。
13. インストールの繰り返しによって CI コストやネットワークリスクが不要に増加する場合は、apm-action またはビルド済みバンドルを推奨します。

エラー処理

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