「教材を開いた初日、コードを書く前に環境構築で1時間溶けた」——プログラミングを始めた人がよく通る場所です。しかも詰まるのは大抵、まだ何も書いていない段階。ターミナルに赤い文字が出ただけで手が止まってしまう。

ここで効くのが「エラー文をそのままAIに投げる」ではなく、自分のPCの状況ごとAIに渡すという動き方です。AIは目の前のあなたのPCを見ていないので、症状だけ渡しても的外れな回答が返ってきます。逆に状況を正確に渡せれば、環境構築の詰まりはかなりの確率で突破できます。

この記事が扱うのは、アプリを実行して出るコードのエラーではなく、その手前の**「自分のPCでNode.jsやClaude Codeを動かせるようにするまで」に絞ったトラブル**です。未経験が最初に高確率で詰まる5つを「症状 → なぜ起きる → AIにこう投げる → 最小の直し方」の型で並べます。コピペして使えるプロンプトも各項に置いておきます。

前提：AIに渡す前に取っておく「自分のPCの状態」

どのエラーでも共通して効くのが、まず現状を数行で取ること。これをAIへの質問にそのまま貼ると精度が跳ね上がります。

# OSと環境の基本情報（Mac/Linux）
uname -a
node -v        # 入っていなければ command not found でOK
npm -v
which node
echo $PATH

Windows(PowerShell)なら:

node -v
npm -v
where.exe node
$env:Path

この出力を丸ごとコピーしておきます。以降のプロンプトはこの出力を貼る前提です。

1. `node: command not found` — そもそもNodeが見つからない

症状

$ node -v
zsh: command not found: node

なぜ起きる

Node.js自体をまだインストールしていない、もしくは入れたのにパスが通っていないため、ターミナルがnodeという命令を探せていない。未経験が一番最初に踏む定番です。

AIにこう投げる

Mac(zsh)でnode -vを打つと command not found になります。
Node.jsは未経験なので入れ方から知りたいです。
以下は今の環境です。この状態から、複数バージョンを切り替えられる形で
Node.jsを入れる手順をコマンド単位で教えてください。

$ uname -a
（uname -aの出力を貼る）
$ which node
node not found

最小の直し方

未経験ならバージョン管理ツール（Mac/Linuxはnvm）経由が後々ラク。

# nvmを入れる
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# ターミナルを開き直してから
nvm install --lts
node -v

2. `EACCES: permission denied` — npm installで権限エラー

症状

$ npm install -g some-tool
npm ERR! code EACCES
npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

なぜ起きる

システム領域（/usr/localなど）へ書き込もうとして権限で弾かれている。ここでsudoを付けて無理やり通すと後で別の権限地獄にハマるので、まず状況をAIに渡すのが正解です。

AIにこう投げる

npm install -g で EACCES: permission denied が出ます。
sudoを使わずに直したいです。エラー全文と環境を貼るので、
権限を壊さない直し方を教えてください。

（エラー全文）
$ which node
（which nodeの出力）

最小の直し方

nvmで入れたNodeなら/usr/localではなくホーム配下を使うので、そもそもこのエラーが出にくくなります。すでに踏んでいる場合は、グローバルインストール先をホームに向ける（~は展開されないので絶対パスで指定するのがポイント）:

mkdir "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
# PATHに追記（zshの例。exportの ~ はシェルが展開するのでOK）
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

3. Nodeのバージョン不一致で`npm install`が警告・失敗する

症状

$ npm install
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   required: { node: '>=20.0.0' },
npm warn EBADENGINE   current: { node: 'v16.20.2' }

なぜ起きる

教材やライブラリが要求するNodeのバージョンと、自分のPCに入っているバージョンが違う。EBADENGINE自体は警告ですが、Next.jsなど新しめのツールはNode 18や20以上を前提にしているため、古いNodeのままだとこの後のビルドや起動で実際に落ちることがあります。

AIにこう投げる

npm installで EBADENGINE、required node >=20 と出ます。
今の私のバージョンは v16.20.2 です。
教材はNext.jsを使います。安全に20系へ上げる手順と、
上げても他プロジェクトが壊れないかの注意点を教えてください。

最小の直し方

nvm install 20
nvm use 20
node -v        # v20.x になっていることを確認
rm -rf node_modules package-lock.json
npm install

プロジェクトに.nvmrc（例: 20と書くだけ）を置いておくと、次回nvm useだけで揃います。

4. パスは通したはずなのに`command not found`が消えない

症状

.zshrcに追記したのに、ターミナルを開き直すとまたcommand not foundに戻る。

なぜ起きる

追記先のファイルが実際に読み込まれていない（.bash_profileに書いたのに使っているのはzshだった、等）、または追記行のパスが間違っている。目視では気づきにくい詰まりです。

AIにこう投げる

ここは「設定ファイルの中身ごと」渡すのがポイント。

zshを使っています。PATHにNodeを追加したのに、
ターミナル再起動後もcommand not foundに戻ります。
今のシェルと設定ファイルの中身を貼るので、
どこが読み込まれていないか特定してください。

$ echo $SHELL
（出力）
$ cat ~/.zshrc | grep -i path
（出力）
$ echo $PATH
（出力）

最小の直し方

echo $SHELL          # /bin/zsh なら設定は ~/.zshrc に書く
source ~/.zshrc      # 追記後は必ず読み込み直す

5. Claude Codeの起動でハマる（インストールしたのに動かない）

症状

$ claude
zsh: command not found: claude

または起動してもNode.js version is not supportedのような表示。

なぜ起きる

Claude CodeはNode製のツールなので、Nodeが正しく入っていることが前提。1〜4のどれかが未解決だと、Claude Code側で症状が出ます。つまりこれは単独のエラーというより、環境の総合テストです。

AIにこう投げる

Claude Codeを入れたのですが claude command not found になります。
未経験で、Nodeまわりが正しいか自信がありません。
下の出力を見て、Node側とClaude Code側どちらが原因か切り分けてください。

$ node -v
（出力）
$ npm -v
（出力）
$ npm list -g --depth=0
（出力）

最小の直し方

Nodeが対応バージョン（20系など新しめ）で通っていることを確認してから入れ直す:

node -v                              # v20.x 以上を確認
npm install -g @anthropic-ai/claude-code
claude --version

この記事の裏テーマ：「AIに状況を渡す力」そのものがスキル

5つ全部に共通するのは、エラー文だけでなくnode -vやecho $PATHの出力を一緒に渡すという動きでした。これは環境構築に限らず、この先ずっと効く技術です。

AIは自分のPCを見ていない → だから状況を言語化して渡す
返ってきたコマンドを鵜呑みにせず、sudoを無闇に足していないか等を一度自分の目で確認する

この「状況を渡す力」と「AIの出力をレビューする目」は、プログラミングそのものと同時に身につけていくべきスキルです。環境構築の詰まりは、その最初の練習台としてちょうどいい題材でもあります。

※この記事は未経験〜駆け出し向けの基礎トラブルシュートです。中上級の方には物足りないので、社内研修・後輩育成・知り合いへの紹介にどうぞ。
未経験から Next.js + Supabase + Claude Code でWebアプリを作って公開するまでを全20セッションで体系化した教材を作っています。

無料で試す（未経験向け体験版）→ https://github.com/ayies128/next-ai-camp-trial
教材完全版＋チャットサポート（月5,500円・面談なし）→ https://menta.work/plan/20251?ref=qiita
AI×開発ニュースを毎日発信 → YouTube『AIエンジニア情報局』（別運営チャンネル）