install-missing-tool

不足しているツールのインストール

基本ルール：ソフトウェアを自動的にインストールしてはいけません。必ず事前にユーザーの許可を得てください。

コマンドが「command not found」「not recognized」などのエラーで失敗した場合、エージェントは不足しているツールをパッケージマネージャー経由でインストールしなければなりません。ただし、ユーザーから明示的な許可を得た後に限ります。

使用する状況

• 必要なコマンドに対して、シェルが command not found ／ not recognized ／ no such file or directory を返す
• スクリプトまたはツールが、インストールされていない依存関係を必要とする
• 不足しているユーティリティによってタスクの実行が妨げられている

不要なケース： プロジェクト内での Python／Node.js のインポート（これらは requirements.txt、package.json などに追加します）。

手順

1. 不足しているツールを特定する

失敗したコマンドを実行するか、エラーメッセージを確認して、必要な正確なバイナリ名を特定します。

2. ツールをパッケージ名に対応付ける

以下の表で適切なパッケージを確認します。ツールが記載されていない場合は、推奨されるパッケージマネージャー（brew search <tool>、apt search <tool> など）で検索します。

コマンド	Homebrew	apt (Debian/Ubuntu)	dnf (Fedora/RHEL)	pacman (Arch)	winget (Windows)
jq	jq	jq	jq	jq	jqlang.jq
fzf	fzf	fzf	fzf	fzf	junegunn.fzf
rg (ripgrep)	ripgrep	ripgrep	ripgrep	ripgrep	BurntSushi.ripgrep
fd	fd	fd-find	fd-find	fd	sharkdp.fd
bat	bat	bat	bat	bat	sharkdp.bat
tree	tree	tree	tree	tree	GNUWin32.Tree
httpie	httpie	httpie	httpie	httpie	httpie.httpie
curl	curl	curl	curl	curl	curl.curl
wget	wget	wget	wget	wget	GNU.Wget
tmux	tmux	tmux	tmux	tmux	tmux.tmux
neofetch	neofetch	neofetch	neofetch	neofetch	—
htop	htop	htop	htop	htop	—
yq	yq	yq	yq	yq	—
diff-so-fancy	diff-so-fancy	—	—	—	—
shellcheck	shellcheck	shellcheck	ShellCheck	shellcheck	—
pandoc	pandoc	pandoc	pandoc	pandoc	—

言語固有のツール：

ツール	パッケージ／コマンド
Python パッケージ	uv tool install <package>（推奨）、またはプロジェクトローカルの場合は uv add <package>
Node.js パッケージ	npm install -g <package>
Rust ツール	cargo install <package>
Go ツール	go install <package>@latest

3. 利用可能なパッケージマネージャーを確認する

次の優先順位で確認します。

1. Homebrew（brew --version）— macOS および Linux
2. OS 標準のもの：
   • Debian/Ubuntu：dpkg --version → apt ／ apt-get
   • Fedora/RHEL/CentOS：rpm --version → dnf または yum
   • Arch/Manjaro：pacman --version → pacman
   • openSUSE：zypper --version → zypper
   • Alpine：apk --version → apk
   • Windows：winget --version → winget、または choco --version → chocolatey
3. 言語固有のもの： uv --version、npm --version、cargo --version、go version

4. ユーザーに許可を求める

この手順は必須であり、例外はありません。

ユーザーに以下を提示します。

• ツール名とパッケージマネージャー
• 実行する正確なコマンド
• 管理者権限（sudo、管理者権限）が必要かどうか

I need to install `<tool>` to continue. The command is:
  brew install <package>

This requires user privileges. May I proceed?

sudo が必要な場合：

• ユーザー自身でコマンドを実行するよう依頼する、または
• コマンドを実行するためにパスワードを提供するか、ユーザーに確認する

明示的な許可なく、インストールコマンドを実行してはいけません。「明らかに」必要なツールであっても、--yes フラグを指定する場合であっても同様です。

5. ツールをインストールする

ユーザーの許可を得た後に、インストールコマンドを実行します。

# Homebrew (macOS/Linux)
brew install <package>

# apt (Debian/Ubuntu) — requires sudo
sudo apt install -y <package>

# dnf (Fedora/RHEL) — requires sudo
sudo dnf install -y <package>

# pacman (Arch) — requires sudo
sudo pacman -S <package>

# apk (Alpine) — requires root
apk add <package>

# winget (Windows)
winget install <package>

# chocolatey (Windows, admin)
choco install <package> -y

# Python tools — uv preferred over pip
uv tool install <package>        # global tool (e.g. uv tool install ruff)
uv add <package>                 # project-local dependency

# Node.js tools
npm install -g <package>

# Rust tools
cargo install <package>

# Go tools
go install <package>@latest

6. インストールを確認する

インストール後、ツールが利用可能であることを確認します。

<tool> --version
# or
which <tool>

確認に失敗した場合は、PATH の問題またはインストールエラーを調べます。

フォールバック：カスタムスクリプト

パッケージマネージャーでツールをインストールできない場合に限り、次の手順を実行します。

1. パッケージが見つからなかったことをユーザーに説明します
2. カスタムインストールスクリプト（ダウンロード＋展開＋PATH の設定）を提案します
3. ダウンロードまたはスクリプトの実行前に、明示的な許可を求めます
4. ユーザーによる確認なしに、ダウンロードしたスクリプトを実行してはいけません

注意点

• 自動インストール： 許可なくインストールしてはいけません。必ず先に確認してください。
• uv より pip を優先： Python ツールのインストールでは、必ず pip より uv を優先してください。グローバルツールには uv tool install を、プロジェクトの依存関係には uv add を使用します。uv が利用できない場合に限り、pip install に切り替えてください。
• パッケージ名の間違い： バイナリ名とパッケージ名は異なることがよくあります（fd-find と fd、ripgrep と rg など）。必ず先にパッケージ名を確認してください。
• 許可なく sudo を実行： インストールに sudo が必要な場合、ユーザー自身に実行してもらうか、ユーザーから明示的な許可を得てから実行してください。
• エラーが表示されない失敗： パッケージマネージャーによっては、エラーを表示せずに失敗したり、PATH に含まれない場所にインストールしたりすることがあります。必ず which または <tool> --version で確認してください。
• インストールの中断： インストールが中断された場合は、インストールコマンドを再実行してください。パッケージマネージャーは適切に処理します。

検証

ツールのインストール後、次の点を確認します。

which <tool> && <tool> --version

• ツールのパスがユーザーの $PATH に含まれている
• バージョンコマンドがエラーなく出力を返す
• 同じシェルセッションでツールを使用できる