Claude Code で nvm/pyenv/asdf が認識されない - シェル初期化の仕組みと4つの解決策

「npm run dev を実行させたら node: command not found と返ってきた」——Claude Code を使い始めたとき、私が最初にぶつかった壁のひとつです。

ローカルのターミナルでは問題なく動くのに、Claude Code 経由だと突然バージョンマネージャーが効かなくなります。nvm で管理している Node.js が「見えない」、pyenv で設定した Python バージョンが使われありません。この問題に数時間溶かした経験がある方は少なくないはずです。

2014年からアプリ開発を続けてきた中で、環境変数まわりのトラブルは何度も経験してきました。その経験から言えることは「原因を理解すれば確実に再現しなくなる」ということです。このエラーにも同じことが言えます。

なぜ Claude Code でバージョンマネージャーが使えなくなるのか

Claude Code が Bash ツールでコマンドを実行するとき、ログインシェルの初期化スクリプト（.bashrc、.zshrc、.bash_profile）を自動的に読み込みません。

通常、ターミナルを開くと次の順番で初期化が走ります：

~/.zprofile → ~/.zshrc → (nvm/pyenv/asdf の初期化コード) → PATH に追加される

nvm を例にとると、.zshrc か .bash_profile の中に次のような行があります：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

これがシェルを開くたびに実行されて、nvm コマンドと、指定したバージョンの Node.js が PATH に追加されます。

ところが Claude Code のサブプロセスは「ノンインタラクティブな非ログインシェル」として起動するため、これらの初期化コードが走りません。そのため、node や python（バージョン管理されたもの）がどこにあるかを知らないまま実行しようとして command not found になります。

まず自分の環境を診断する

実際に何が起きているか確認する方法を最初に示します。Claude Code に次のコマンドを実行させてみてください：

# Claude Code のサブプロセスから見えているPATHと実行ファイルの場所
echo "PATH: $PATH"
which node 2>/dev/null || echo "node: not found"
which python3 2>/dev/null || echo "python3: not found"
node --version 2>/dev/null || echo "node version: unknown"
python3 --version 2>/dev/null || echo "python3 version: unknown"

ローカルのターミナルで同じコマンドを実行し、出力を比べてください。PATH が大きく異なっていたり、/home/user/.nvm/versions/node/v20.x.x/bin のようなパスがない場合、これが原因です。

解決策1：絶対パスで実行する（即効性あり）

最もシンプルな方法は、コマンドを実行するとき絶対パスを指定することです。

nvm の場合：

# ~/.nvm 以下の実際のパスを確認
ls ~/.nvm/versions/node/
 
# 確認したパスを使って実行（例：v20.x.x）
~/.nvm/versions/node/v20.11.0/bin/node --version
~/.nvm/versions/node/v20.11.0/bin/npm install

pyenv の場合：

# pyenv で管理しているバージョンを確認
ls ~/.pyenv/versions/
 
# 絶対パスで実行
~/.pyenv/versions/3.11.8/bin/python3 -m pip install requests

この方法の欠点は、バージョンが変わるたびにパスを更新しなければならないことです。一時的な対処としては有効ですが、恒久的な解決には次の方法をお勧めします。

解決策2：CLAUDE.md にパスを明示する

プロジェクトルートの CLAUDE.md（なければ作成）に、使用するツールのパスを明示します。

## 開発環境
 
このプロジェクトは以下の環境を使用しています。
 
- Node.js: v20.11.0 (nvm管理)
  - `node` = `~/.nvm/versions/node/v20.11.0/bin/node`
  - `npm` = `~/.nvm/versions/node/v20.11.0/bin/npm`
- Python: 3.11.8 (pyenv管理)
  - `python3` = `~/.pyenv/versions/3.11.8/bin/python3`
 
コマンド実行時は上記の絶対パスを使用するか、以下のコマンドで事前に環境をロードしてください：
```bash
export PATH="$HOME/.nvm/versions/node/v20.11.0/bin:$HOME/.pyenv/versions/3.11.8/bin:$PATH"


CLAUDE.md に書くことで、Claude Code はプロジェクト開始時にこの情報を読み込み、以降の操作で自動的に正しいパスを使うようになります。

## 解決策3：bash -l でログインシェルとして実行する

特定のコマンドをどうしてもログインシェル経由で実行したい場合、`bash -l` でラップします：

```bash
# ログインシェルとして node を実行
bash -l -c "node --version"
bash -l -c "npm run dev"

# zshの場合
zsh -l -c "python3 --version"

ただし、これはすべての bash コマンドブロックに適用されるわけではありません。Claude Code の Bash ツールは各コマンドを個別のプロセスで実行するため、実行するたびに bash -l -c "..." で包む必要があります。頻繁に使う場合は次の方法が現実的です。

解決策4：volta や mise への移行を検討する

根本的な解決策は、シェルの初期化に依存しないバージョンマネージャーへの移行です。

volta と mise（旧 rtx）は、シェルの初期化スクリプトに頼らずプロセスレベルで正しいバージョンを提供します。特に volta は、package.json に次のように書くだけで、どの環境でも自動的に正しい Node.js バージョンが使われます：

{
  "volta": {
    "node": "20.11.0",
    "npm": "10.2.4"
  }
}

mise は Node.js だけでなく Python、Go、Ruby など複数の言語を一元管理でき、.tool-versions ファイルでバージョンを固定できます。Claude Code との相性も良く、プロセス起動時に自動的に正しいバージョンを提供します。

移行コストはかかりますが、チーム開発でも同じ問題が起きにくくなるメリットがあります。私自身、壁紙アプリや引き寄せ系アプリの開発で複数の Node.js バージョンを切り替える必要があったとき、volta に移行してから同様の問題で時間を無駄にすることがなくなりました。

状況別の推奨アプローチ

今すぐ動かしたい: 解決策1（絶対パス指定）
特定プロジェクトで安定して使いたい: 解決策2（CLAUDE.md への明示）
チームで使っている・長期的に解決したい: 解決策4（volta/mise への移行）

bash -l を多用する方法（解決策3）は手軽ですが、毎回の記述が増えるのと、Claude Code の Bash ツールが期待通りにラップしてくれるかが不安定なため、補助的な位置づけが適切です。

まず解決策2（CLAUDE.md への記載）を試してみてください。5分もかからず設定でき、プロジェクトに関わる全員が同じ恩恵を受けられます。チームの CLAUDE.md に「この環境で開発するにはこのパスを使う」と書いておくだけで、似たような問題で新しいメンバーがつまずくことも防げます。