パッケージマネージャー設定：自動検出とカスタマイズ

このレッスンで学べること

• ✅ 現在のプロジェクトで使用しているパッケージマネージャー（npm/pnpm/yarn/bun）を自動検出
• ✅ 6層の検出優先度メカニズムを理解
• ✅ グローバルおよびプロジェクトレベルでパッケージマネージャーを設定
• ✅ /setup-pm コマンドで素早くセットアップ
• ✅ 複数プロジェクト環境で異なるパッケージマネージャーを扱うシナリオに対応

今あなたが抱えている問題

プロジェクトが増えてきて、npm を使うもの、pnpm を使うもの、yarn や bun を使うものが混在しています。Claude Code でコマンドを入力するたびに、こう考えてしまいます：

• このプロジェクトは npm install それとも pnpm install？
• npx、pnpm dlx、それとも bunx を使うべき？
• スクリプトは npm run dev、pnpm dev、それとも bun run dev？

一度間違えるとコマンドがエラーになり、時間の無駄です。

このテクニックを使うタイミング

• 新規プロジェクト開始時：使用するパッケージマネージャーを決めたらすぐに設定
• プロジェクト切り替え時：現在の検出が正しいか確認
• チーム開発時：全メンバーが同じコマンドスタイルを使用することを保証
• 複数パッケージマネージャー環境：グローバル設定 + プロジェクト上書きで柔軟に管理

なぜパッケージマネージャーの設定が必要？

Everything Claude Code の hooks と agents は、パッケージマネージャー関連のコマンドを自動生成します。検出が間違っていると、すべてのコマンドが誤ったツールを使用し、操作が失敗します。

🎒 始める前の準備

前提条件の確認

このレッスンを始める前に、インストールガイドを完了し、プラグインが Claude Code に正しくインストールされていることを確認してください。

システムにパッケージマネージャーがインストールされているか確認しましょう：

# インストール済みのパッケージマネージャーを確認
which npm pnpm yarn bun

# または Windows (PowerShell) の場合
Get-Command npm, pnpm, yarn, bun -ErrorAction SilentlyContinue

以下のような出力が表示されれば、インストール済みです：

/usr/local/bin/npm
/usr/local/bin/pnpm

パッケージマネージャーが見つからない場合は、先にインストールが必要です（このレッスンではインストール手順は扱いません）。

基本的な考え方

Everything Claude Code はスマート検出メカニズムを使用し、6層の優先度に従ってパッケージマネージャーを自動選択します。最適な場所で一度設定するだけで、すべてのシナリオで正しく動作します。

検出優先度（高い順）

1. 環境変数 CLAUDE_PACKAGE_MANAGER  ─── 最高優先度、一時的な上書き
2. プロジェクト設定 .claude/package-manager.json  ─── プロジェクトレベルの上書き
3. package.json の packageManager フィールド  ─── プロジェクト標準
4. Lock ファイル（pnpm-lock.yaml など）  ─── 自動検出
5. グローバル設定 ~/.claude/package-manager.json  ─── グローバルデフォルト
6. フォールバック：順番に最初に利用可能なものを探す  ─── 最終手段

なぜこの順序なのか？

• 環境変数が最高：一時的な切り替えに便利（CI/CD 環境など）
• プロジェクト設定が次：同一プロジェクト内で強制的に統一
• package.json フィールド：Node.js の標準仕様
• Lock ファイル：プロジェクトで実際に使用されているファイル
• グローバル設定：個人のデフォルト設定
• フォールバック：常に利用可能なツールを確保

実践してみよう

ステップ 1：現在の設定を確認

なぜ まず現在の検出状況を把握し、手動設定が必要かどうかを確認します。

# 現在のパッケージマネージャーを検出
node scripts/setup-package-manager.js --detect

期待される出力：

=== Package Manager Detection ===

Current selection:
  Package Manager: pnpm
  Source: lock-file

Detection results:
  From package.json: not specified
  From lock file: pnpm
  Environment var: not set

Available package managers:
  ✓ npm
  ✓ pnpm (current)
  ✗ yarn
  ✓ bun

Commands:
  Install: pnpm install
  Run script: pnpm [script-name]
  Execute binary: pnpm dlx [binary-name]

表示されたパッケージマネージャーが期待通りであれば、検出は正しく、手動設定は不要です。

ステップ 2：グローバルデフォルトのパッケージマネージャーを設定

なぜ すべてのプロジェクトにグローバルデフォルトを設定し、繰り返しの設定を減らします。

# グローバルデフォルトを pnpm に設定
node scripts/setup-package-manager.js --global pnpm

期待される出力：

✓ Global preference set to: pnpm
  Saved to: ~/.claude/package-manager.json

生成された設定ファイルを確認：

cat ~/.claude/package-manager.json

期待される出力：

{
  "packageManager": "pnpm",
  "setAt": "2026-01-25T12:00:00.000Z"
}

ステップ 3：プロジェクトレベルのパッケージマネージャーを設定

なぜ 特定のプロジェクトでは特定のパッケージマネージャーが必要な場合があります（特定機能への依存など）。プロジェクトレベルの設定はグローバル設定を上書きします。

# 現在のプロジェクトに bun を設定
node scripts/setup-package-manager.js --project bun

期待される出力：

✓ Project preference set to: bun
  Saved to: .claude/package-manager.json

生成された設定ファイルを確認：

cat .claude/package-manager.json

期待される出力：

{
  "packageManager": "bun",
  "setAt": "2026-01-25T12:00:00.000Z"
}

プロジェクトレベル vs グローバル設定

• グローバル設定：~/.claude/package-manager.json、すべてのプロジェクトに影響
• プロジェクト設定：.claude/package-manager.json、現在のプロジェクトのみに影響、優先度が高い

ステップ 4：/setup-pm コマンドを使用（オプション）

なぜ スクリプトを手動で実行したくない場合は、Claude Code でスラッシュコマンドを直接使用できます。

Claude Code で以下を入力：

/setup-pm

Claude Code がスクリプトを呼び出し、インタラクティブなオプションを表示します。

期待される出力（例）：

[PackageManager] Available package managers:
  - npm
  - pnpm (current)
  - bun

To set your preferred package manager:
  - Global: Set CLAUDE_PACKAGE_MANAGER environment variable
  - Or add to ~/.claude/package-manager.json: {"packageManager": "pnpm"}
  - Or add to package.json: {"packageManager": "pnpm@8"}

ステップ 5：検出ロジックを検証

なぜ 検出優先度を理解すれば、さまざまな状況での結果を予測できます。

いくつかのシナリオをテストしてみましょう：

シナリオ 1：Lock ファイル検出

# プロジェクト設定を削除
rm .claude/package-manager.json

# 検出
node scripts/setup-package-manager.js --detect

期待される出力 Source: lock-file（lock ファイルが存在する場合）

シナリオ 2：package.json フィールド

# package.json に追加
cat >> package.json << 'EOF'
  "packageManager": "[email protected]"
EOF

# 検出
node scripts/setup-package-manager.js --detect

期待される出力 From package.json: [email protected]

シナリオ 3：環境変数による上書き

# 環境変数を一時的に設定
export CLAUDE_PACKAGE_MANAGER=yarn

# 検出
node scripts/setup-package-manager.js --detect

期待される出力 Source: environment と Package Manager: yarn

# 環境変数をクリア
unset CLAUDE_PACKAGE_MANAGER

チェックポイント ✅

以下のチェックポイントがすべてパスしていることを確認：

• [ ] --detect コマンドで現在のパッケージマネージャーが正しく識別される
• [ ] グローバル設定ファイルが作成されている：~/.claude/package-manager.json
• [ ] プロジェクト設定ファイルが作成されている（必要な場合）：.claude/package-manager.json
• [ ] 異なる優先度の上書き関係が期待通りに動作する
• [ ] 表示される利用可能なパッケージマネージャーが実際にインストールされているものと一致

よくある落とし穴

❌ エラー 1：設定したのに反映されない

症状：pnpm を設定したのに、検出では npm と表示される。

原因：

• Lock ファイルの優先度がグローバル設定より高い（lock ファイルが存在する場合）
• package.json の packageManager フィールドの優先度もグローバル設定より高い

解決策：

# 検出ソースを確認
node scripts/setup-package-manager.js --detect

# lock file または package.json の場合、これらのファイルを確認
ls -la | grep -E "(package-lock|yarn.lock|pnpm-lock|bun.lockb)"
cat package.json | grep packageManager

❌ エラー 2：存在しないパッケージマネージャーを設定

症状：bun を設定したが、システムにインストールされていない。

検出結果の表示：

Available package managers:
  ✓ npm
  ✗ bun (current)  ← 注意：current と表示されているが、未インストール

解決策：先にパッケージマネージャーをインストールするか、インストール済みの別のものを設定。

# 利用可能なパッケージマネージャーを検出
node scripts/setup-package-manager.js --list

# インストール済みのものに切り替え
node scripts/setup-package-manager.js --global npm

❌ エラー 3：Windows パス問題

症状：Windows でスクリプトを実行するとファイルが見つからないエラー。

原因：Node.js スクリプトのパス区切り文字の問題（ソースコードでは対処済みですが、正しいコマンドを使用する必要があります）。

解決策：PowerShell または Git Bash を使用し、パスが正しいことを確認：

# PowerShell
node scripts\setup-package-manager.js --detect

❌ エラー 4：プロジェクト設定が他のプロジェクトに影響

症状：プロジェクト A で bun を設定したが、プロジェクト B に切り替えても bun が使用される。

原因：プロジェクト設定は現在のプロジェクトディレクトリでのみ有効で、ディレクトリを切り替えると再検出されます。

解決策：これは正常な動作です。プロジェクト設定は現在のプロジェクトにのみ影響し、他のプロジェクトには影響しません。

このレッスンのまとめ

Everything Claude Code のパッケージマネージャー検出メカニズムは非常にスマートです：

• 6層の優先度：環境変数 > プロジェクト設定 > package.json > lock ファイル > グローバル設定 > フォールバック
• 柔軟な設定：グローバルデフォルトとプロジェクト上書きをサポート
• 自動検出：ほとんどの場合、手動設定は不要
• コマンドの統一：設定後、すべての hooks と agents が正しいコマンドを使用

推奨設定戦略：

1. 最もよく使うパッケージマネージャーをグローバルに設定（例：pnpm）
2. 特殊なプロジェクトはプロジェクトレベルで上書き（例：bun のパフォーマンスに依存する場合）
3. その他の状況は自動検出に任せる

次のレッスン予告

次のレッスンでは MCP サーバー設定 を学びます。

学べること：

• 15以上のプリセット MCP サーバーの設定方法
• MCP サーバーが Claude Code の機能をどのように拡張するか
• MCP サーバーの有効化状態とトークン使用量の管理方法

---

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日：2026-01-25

機能	ファイルパス	行番号
パッケージマネージャー検出コアロジック	scripts/lib/package-manager.js	157-236
Lock ファイル検出	scripts/lib/package-manager.js	92-102
package.json 検出	scripts/lib/package-manager.js	107-126
パッケージマネージャー定義（設定）	scripts/lib/package-manager.js	13-54
検出優先度定義	scripts/lib/package-manager.js	57
グローバル設定保存	scripts/lib/package-manager.js	241-252
プロジェクト設定保存	scripts/lib/package-manager.js	257-272
コマンドラインスクリプトエントリ	scripts/setup-package-manager.js	158-206
検出コマンド実装	scripts/setup-package-manager.js	62-95

主要な定数：

• PACKAGE_MANAGERS：サポートされるパッケージマネージャーとそのコマンド設定（13-54行目）
• DETECTION_PRIORITY：検出優先度順序 ['pnpm', 'bun', 'yarn', 'npm']（57行目）

主要な関数：

• getPackageManager()：コア検出ロジック、優先度に従ってパッケージマネージャーを返す（157-236行目）
• detectFromLockFile()：lock ファイルからパッケージマネージャーを検出（92-102行目）
• detectFromPackageJson()：package.json からパッケージマネージャーを検出（107-126行目）
• setPreferredPackageManager()：グローバル設定を保存（241-252行目）
• setProjectPackageManager()：プロジェクト設定を保存（257-272行目）

検出優先度の実装（ソースコード 157-236行目）：

function getPackageManager(options = {}) {
  // 1. 環境変数（最高優先度）
  if (envPm && PACKAGE_MANAGERS[envPm]) { return { name: envPm, source: 'environment' }; }

  // 2. プロジェクト設定
  if (projectConfig) { return { name: config.packageManager, source: 'project-config' }; }

  // 3. package.json フィールド
  if (fromPackageJson) { return { name: fromPackageJson, source: 'package.json' }; }

  // 4. Lock ファイル
  if (fromLockFile) { return { name: fromLockFile, source: 'lock-file' }; }

  // 5. グローバル設定
  if (globalConfig) { return { name: globalConfig.packageManager, source: 'global-config' }; }

  // 6. フォールバック：優先度順に最初に利用可能なものを探す
  for (const pmName of fallbackOrder) {
    if (available.includes(pmName)) { return { name: pmName, source: 'fallback' }; }
  }

  // デフォルト npm
  return { name: 'npm', source: 'default' };
}