zsh-path-skill

Zsh の PATH 管理スキル

このスキルでは、zsh の PATH 環境変数を管理するための包括的なガイダンスを提供します。コマンドが見つからない場合のトラブルシューティング、新しいツールの追加、シェル設定の整理などが含まれます。

このスキルを使用する場面

次のような場合にこのスキルを使用します：

• インストール済みのツールで「command not found」エラーが発生する場合
• 新しいツールを PATH に追加する場合（bun、nvm、cargo、go、Python venv など）
• 現在の PATH エントリを検証、監査する場合
• .zshrc と .zshrc.local の間で PATH 設定を整理する場合
• PATH に関連するシェル起動時の問題をトラブルシューティングする場合
• バージョン管理ツール（nvm、pyenv、rbenv）をセットアップする場合

診断コマンド

現在の PATH を確認する

# List all PATH entries
echo $PATH | tr ':' '\n'

# Check if specific command is in PATH
which bun 2>/dev/null || echo "bun not found in PATH"

# Find where a command is installed
command -v node
type -a python

PATH エントリを検証する

# Check for broken/non-existent PATH entries
echo $PATH | tr ':' '\n' | while read p; do
  [[ -d "$p" ]] || echo "MISSING: $p"
done

# Check for duplicate PATH entries
echo $PATH | tr ':' '\n' | sort | uniq -d

よく使われるツールの PATH 設定

Bun（JavaScript ランタイム）

# Add to .zshrc
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

デフォルトの場所：~/.bun/bin/bun

NVM（Node バージョン管理ツール）

# Add to .zshrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

デフォルトの場所：~/.nvm/

注： NVM はバイナリではなく、シェル関数です。有効な Node バージョンを指すように PATH を動的に変更します。

Python 仮想環境

# Add to .zshrc for global tools venv
export PATH="$HOME/.venv/tools3/bin:$PATH"

# For pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Rust/Cargo

# Add to .zshrc
export PATH="$HOME/.cargo/bin:$PATH"

Go

# Add to .zshrc
export GOPATH="$HOME/go"
export PATH="$GOPATH/bin:$PATH"

Homebrew（macOS）

# Intel Mac
export PATH="/usr/local/bin:$PATH"

# Apple Silicon Mac
export PATH="/opt/homebrew/bin:$PATH"
eval "$(/opt/homebrew/bin/brew shellenv)"

ローカルの bin ディレクトリ

# User-local binaries
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

ファイル整理のベストプラクティス

.zshrc（チーム／共有設定）

次の設定は .zshrc に記述します：

• Oh My Zsh の設定
• チーム共通のエイリアス
• 標準的な PATH の追加（homebrew、local bin）
• プラグインの設定

# ===== ZSH-TOOL MANAGED SECTION BEGIN =====
# Team-wide PATH modifications
export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/bin:$PATH"

# Bun
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

# NVM
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
# ===== ZSH-TOOL MANAGED SECTION END =====

# Load local customizations
[[ -f ~/.zshrc.local ]] && source ~/.zshrc.local

.zshrc.local（個人／マシン固有の設定）

次の設定は .zshrc.local に記述します：

• マシン固有の PATH エントリ
• 個人用ツールの設定
• 実験的な設定
• キーバインドを上書きする可能性があるインテグレーション

# Machine-specific tools
export PATH="/opt/custom-tool/bin:$PATH"

# Personal integrations
if command -v atuin >/dev/null 2>&1; then
  eval "$(atuin init zsh)"
fi

PATH の順序は重要です

PATH は左から右に検索されます。最初に一致したものが使用されます。

# This order means ~/.local/bin takes priority over system bins
export PATH="$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin"

推奨される PATH の順序

1. プロジェクト固有の bin（direnv によって追加）
2. ユーザーのローカル bin（~/.local/bin、~/bin）
3. 言語のバージョン管理ツール（nvm、pyenv、rbenv）
4. パッケージマネージャー（homebrew、cargo）
5. システムパス（/usr/local/bin、/usr/bin）

トラブルシューティング

インストール後にコマンドが見つからない

# 1. Find where tool was installed
ls -la ~/.bun/bin/bun 2>/dev/null
ls -la ~/.cargo/bin/rustc 2>/dev/null
ls -la ~/.nvm/versions/node/*/bin/node 2>/dev/null

# 2. Check if PATH includes the directory
echo $PATH | tr ':' '\n' | grep -E "(bun|cargo|nvm)"

# 3. Add missing PATH entry to .zshrc

# 4. Reload shell
source ~/.zshrc
# or
exec $SHELL

PATH の変更が反映されない

# Check which file sets the variable
grep -r "export PATH" ~/.zshrc ~/.zshrc.local ~/.zprofile 2>/dev/null

# Source the correct file
source ~/.zshrc

# Or start fresh shell
exec $SHELL

起動フックのエラー

よくある原因：

• フックで使用するツールの PATH エントリがない
• 存在しないディレクトリへの参照が壊れている
• バージョン管理ツールが想定されたバージョンを見つけられない

# Debug startup
zsh -x 2>&1 | head -100

# Check for errors in specific config
bash -n ~/.zshrc

PATH エントリの重複

# Remove duplicates (add to .zshrc)
typeset -U PATH path

確認コマンド

PATH を変更した後に実行します：

# Reload configuration
source ~/.zshrc

# Verify tool is accessible
which bun && bun --version
which node && node --version
command -v nvm && nvm --version

# Verify PATH includes new entries
echo $PATH | tr ':' '\n' | grep -E "(bun|nvm|venv)"

クイックリファレンス

ツール	PATH エントリ	確認コマンド
bun	$HOME/.bun/bin	bun --version
nvm	$NVM_DIR/versions/node/*/bin	nvm --version
cargo	$HOME/.cargo/bin	cargo --version
go	$GOPATH/bin	go version
pyenv	$PYENV_ROOT/bin	pyenv --version
brew（ARM）	/opt/homebrew/bin	brew --version
brew（Intel）	/usr/local/bin	brew --version

よく使われるパターン

条件付き PATH 追加

# Only add if directory exists
[[ -d "$HOME/.bun/bin" ]] && export PATH="$HOME/.bun/bin:$PATH"

# Only add if command not already available
command -v bun >/dev/null || export PATH="$HOME/.bun/bin:$PATH"

起動を高速化する遅延読み込み

# Lazy load nvm (faster shell startup)
lazy_load_nvm() {
  unset -f nvm node npm npx
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
}
nvm() { lazy_load_nvm && nvm "$@"; }
node() { lazy_load_nvm && node "$@"; }
npm() { lazy_load_nvm && npm "$@"; }
npx() { lazy_load_nvm && npx "$@"; }