environment-awareness

環境の把握

概要

AI エージェントで最もよくある失敗は、Windows で Linux コマンドを実行すること、プロジェクトが pnpm を使っているのに npm を使うこと、有効な仮想環境を無視することです。誤ったコマンドを実行するたびに時間を浪費し、実際の損害につながることもあります。

基本原則： シェルコマンドを実行する前に、必ず環境を検出してください。最初に一度確認するだけで、その後のコマンドが何度も失敗するのを防げます。

例外なし。回避策なし。近道なし。

最優先の指示

NO SHELL COMMANDS WITHOUT KNOWING THE TARGET ENVIRONMENT

OS、シェル、パッケージマネージャーを確認していない場合、コマンドを実行する権限はありません。

実施するタイミング

セッション開始時に必須です：

• 新しい会話での最初のやり取り
• 別のプロジェクトまたはリポジトリへの切り替え時
• コンテナー、VM、またはリモートマシンに入った後

次の場合にも必要です：

• コマンドが「not found」または「not recognized」で失敗したとき
• 依存関係のインストール時、またはビルドスクリプトの実行時
• プラットフォーム固有のコード（ファイルパス、プロセス管理、ネットワーク）を書くとき
• 「自分のマシンでは動く」問題を診断するとき

次の場合も省略しないでください：

• 環境を把握しているつもりのとき（推測せず、確認してください）
• ユーザーが OS について何気なく言及したとき（シェルとツールチェーンも確認してください）
• CI/CD で作業するとき（ランナーの環境はローカルマシンと異なります）

開始時の手順

BEFORE running any shell command:

1. PLATFORM: Have you confirmed OS and architecture?
2. SHELL: Do you know which shell is interpreting your commands?
3. PACKAGE MANAGER: Have you checked for lockfiles?
4. RUNTIMES: Do you know which language runtimes are available?
5. VIRTUAL ENV: Are there active virtual environments or version managers?

If any answer is NO: probe first, command second.

検出フローチャート

digraph env_detect {
    rankdir=TB;
    node [shape=box, style=filled, fillcolor="#e8e8e8"];

    start [label="Session Start", shape=oval, fillcolor="#ccffcc"];
    os [label="1. Detect OS\nprocess.platform\nor uname", shape=diamond, fillcolor="#ffffcc"];
    shell [label="2. Detect Shell\n$SHELL / $PSVersionTable\n/ COMSPEC", shape=diamond, fillcolor="#ffffcc"];
    pkg [label="3. Detect Package Manager\nCheck lockfiles\nin project root", shape=diamond, fillcolor="#ffffcc"];
    runtime [label="4. Detect Runtimes\nnode/python/go\n--version", shape=diamond, fillcolor="#ffffcc"];
    venv [label="5. Check Virtual Envs\nVIRTUAL_ENV / CONDA\nnvm / rbenv", shape=diamond, fillcolor="#ffffcc"];
    container [label="6. Container Check\n/.dockerenv\nor cgroup", shape=diamond, fillcolor="#ffffcc"];
    ready [label="Environment Known\nProceed with\ncorrect commands", shape=oval, fillcolor="#ccffcc"];

    start -> os -> shell -> pkg -> runtime -> venv -> container -> ready;
}

検出チェックリスト

この手順をセッションごとに一度実行します。検出結果は、その後のすべてのコマンドに反映してください。

1. オペレーティングシステム

方法	対応環境	コマンド
環境変数	Claude Code ／ Node	ツールコンテキストで process.platform を確認
uname	Linux、macOS、Git Bash	uname -s
システム情報	Windows（任意のシェル）	systeminfo または ver

主な識別点：

• win32 = Windows（32 ビット／64 ビットを問わない）
• darwin = macOS
• linux = Linux または WSL（WSL かどうかは grep -i microsoft /proc/version でさらに確認）

2. シェル

bash だと決めつけないでください。 Windows には CMD、PowerShell、Git Bash、WSL があります。

確認項目	コマンド	判明する内容
シェル変数	echo $SHELL	デフォルトのシェル（Unix）
PowerShell の確認	$PSVersionTable	PowerShell のバージョン
プロセス名	echo $0	現在のシェル（Unix）
COMSPEC	echo %COMSPEC%	CMD のパス（Windows）

重要： Windows では、Claude Code ／ AI エージェントのシェルコンテキストは Git Bash であることが多い一方、ユーザーのターミナルは PowerShell の場合があります。ユーザーがコピーして実行するコマンドを提示する際は、ユーザーが使っているシェルに合わせてください。

3. パッケージマネージャー

検出の優先順位――まずロックファイルを確認します：

ロックファイル	パッケージマネージャー
bun.lockb または bun.lock	bun
pnpm-lock.yaml	pnpm
yarn.lock	yarn
package-lock.json	npm

ロックファイルが見つからない場合：

1. package.json の packageManager フィールドを確認
2. グローバルインストールを確認：which pnpm || which yarn || which bun
3. 最後の手段としてのみ npm を使用

JavaScript 以外のプロジェクトの場合：

ファイル	パッケージマネージャー
Pipfile.lock	pipenv
poetry.lock	poetry
uv.lock	uv
requirements.txt	pip
go.sum	go modules
Cargo.lock	cargo
Gemfile.lock	bundler

4. ランタイムのバージョン

先回りして調べず、初めて使うときに確認します。プロジェクトで実際に必要なものだけを確認してください。

node --version      # Node.js
python3 --version   # Python (use python3, not python, on macOS/Linux)
go version          # Go
rustc --version     # Rust
java --version      # Java
ruby --version      # Ruby

5. 仮想環境

手がかり	示す内容
$VIRTUAL_ENV が設定されている	Python の venv／virtualenv が有効
$CONDA_DEFAULT_ENV が設定されている	Conda 環境が有効
.python-version ファイル	pyenv のバージョンが固定されている
.nvmrc または .node-version ファイル	Node のバージョンが固定されている
.ruby-version ファイル	rbenv／rvm のバージョンが固定されている
.tool-versions ファイル	asdf バージョンマネージャー

バージョンマネージャーが検出された場合： グローバルのランタイムが正しいと決めつけず、マネージャーのコマンド（nvm use、pyenv shell）を使用してください。

6. コンテナーの検出

チェック	コンテナー内か？
/.dockerenv が存在する	Docker
grep -q container /proc/1/cgroup 2>/dev/null	Docker/Podman
$container 環境変数が設定されている	Podman
printenv KUBERNETES_SERVICE_HOST	Kubernetes ポッド

システムのインベントリー

プラットフォームとシェルを確認したら、ユーザーがインストールしているツール、データベース、クラウド CLI、サービスを調べます。このインベントリーは計画に直接活用されます。たとえば、ユーザーが PostgreSQL ではなく SQLite を使っている場合や、Podman ではなく Docker を使っている場合、deployment-advisor や task-planning などの後続スキルは推測に頼らず、より的確な提案ができます。

実行するタイミング

• 常に： Git、GitHub CLI（多くの GodMode スキルで必要です）
• プロジェクトがデータを扱う場合： データベース CLI
• プロジェクトをデプロイする場合： クラウドおよびコンテナーツール
• プロジェクトがメディアや構造化データを処理する場合： ffmpeg、jq、curl
• リスト全体を無条件に実行しないでください。 プロジェクトの種類に応じてチェック項目を選びます。静的サイトに MongoDB のチェックは不要です。

インベントリーチェック

該当するチェックをそれぞれ実行し、標準エラー出力をリダイレクトして、ツールが見つからなくても余計な出力が出ないようにします。

データベース：

ツール	チェック	備考
PostgreSQL	psql --version 2>/dev/null	バックアップが重要な場合は、pg_dump も確認します
MySQL / MariaDB	mysql --version 2>/dev/null	バージョン文字列で MariaDB と識別できます
SQLite	sqlite3 --version 2>/dev/null	macOS と Linux にはあらかじめインストールされていることがよくあります
MongoDB	mongod --version 2>/dev/null	最新のシェルについては mongosh も確認します
Redis	redis-server --version 2>/dev/null	redis-cli も確認します

クラウドおよびホスティング CLI：

ツール	チェック
AWS CLI	aws --version 2>/dev/null
Google Cloud	gcloud --version 2>/dev/null
Azure CLI	az --version 2>/dev/null
Vercel	vercel --version 2>/dev/null
Supabase	supabase --version 2>/dev/null
Fly.io	fly version 2>/dev/null
Netlify	netlify --version 2>/dev/null
Railway	railway --version 2>/dev/null

コンテナーツール：

ツール	チェック
Docker	docker --version 2>/dev/null
Docker Compose	docker compose version 2>/dev/null
Podman	podman --version 2>/dev/null

開発ツール：

ツール	チェック
Git	git --version 2>/dev/null
GitHub CLI	gh --version 2>/dev/null
curl	curl --version 2>/dev/null
jq	jq --version 2>/dev/null
ffmpeg	ffmpeg -version 2>/dev/null

報告形式

調査結果は簡潔に報告します。バージョン出力をそのまま表示せず、バージョン番号を取り出して要約します。

Available: PostgreSQL 16.2, Docker 27.1, gh 2.45, SQLite 3.43
Not found: Redis, AWS CLI, Podman

原則

1. エラーを非表示にし、終了コードを 0 にします。 バージョンチェックを連結する場合は、必ず標準エラー出力を /dev/null にリダイレクトし、末尾に ; true を追加します。ツールが見つからないと終了コードが 0 以外になり、Claude Code で赤いエラーとして表示されます。ツールが見つからないことは情報であり、失敗ではありません。出力に赤いエラーが表示されてはいけません。

   # WRONG: last missing tool causes exit 127 (red error in Claude Code)
   psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null
   
   # RIGHT: force clean exit regardless of which tools are missing
   psql --version 2>/dev/null; redis-server --version 2>/dev/null; mongod --version 2>/dev/null; true
   

2. プロジェクトに範囲を絞ります。 コードベースに関連するカテゴリだけを確認します。プロジェクトの設定ファイル、Dockerfile、CI 設定、デプロイメントマニフェストを読み、何が必要かを判断します。
3. 確認は一度だけ行い、何度も参照します。 結果は作業コンテキストに保存します。ユーザーが新たに何かをインストールしない限り、セッション中に再確認しません。
4. 後続スキルに結果を引き継ぎます。 インベントリーの結果は、deployment-advisor（何にデプロイできるか）、task-planning（どのような制約があるか）、project-bootstrap（何をインストールする必要があるか）に直接役立ちます。

プラットフォーム固有のコマンド対応表

検出した環境に応じて、正しいコマンドを使用します。

操作	Linux/macOS	Windows CMD	Windows PowerShell	Windows 上の Git Bash
ファイル一覧の表示	ls -la	dir	Get-ChildItem	ls -la
プロセスの検索	ps aux | grep	tasklist	Get-Process	ps aux | grep
環境変数の設定	export VAR=val	set VAR=val	$env:VAR = "val"	export VAR=val
ヌルデバイス	/dev/null	NUL	$null	/dev/null
パス区切り文字	:	;	;	:
ファイルの削除	rm file	del file	Remove-Item file	rm file
ファイルの検索	find . -name	dir /s /b	Get-ChildItem -Recurse	find . -name
ポートの確認	lsof -i :PORT	netstat -an	Get-NetTCPConnection	netstat -an

検出するか、前提とするか

カテゴリ	アクション	理由
OS	必ず検出	すべてのコマンドの構文に影響します
シェル	必ず検出	引用符、パイプ、リダイレクトを左右します
パッケージマネージャー	必ず検出	誤ったマネージャーを使うとロックファイルが破損します
ランタイムのバージョン	初回使用時に検出	そのランタイムを実行するときのみ重要です
仮想環境	関連する場合に検出	誤った環境では、インストール先も誤ります
コンテナー	動作が予期しない場合に検出	コンテナーにはホストのツールが多数ありません

認知上の落とし穴

合理化	実際のところ
「たぶん Linux だろう」	開発者の30％は Windows を使用しています。macOS もさらに25％です。まず検出しましょう。
「bash はどこでも使える」	Windows CMD と PowerShell の構文は根本的に異なります。Git Bash もありますが、使えるとは限りません。
「npm がデフォルトだ」	pnpm のプロジェクトで npm を使うと、ロックファイルが破損し、CI が失敗します。
「コマンドが失敗したら修正すればいい」	パス構文を誤った rm -rf が失敗しても、データを削除する可能性があります。インストールに失敗すると、壊れた状態が残ります。
「ユーザーが Windows と言ったので、PowerShell だ」	CMD、Git Bash、WSL、Cygwin の可能性があります。OS だけでなくシェルを確認してください。
「CI とローカル環境は同じだ」	CI ランナーでは、OS、シェル、ツールのバージョンが異なります。そちらも検出してください。

ガードレール -- 停止して検出する

次のいずれかに気づいたら、停止して検出を実行してください。

• シェルが ls に対応しているか分からない状態で実行する
• Unix 系のシェルであることを確認せずに /dev/null を使用する
• 他のロックファイルがないか確認せずに npm install を実行する
• バージョンを確認せずに python3 ではなく python を使用する
• ~ が正しく展開されると思い込む（CMD では展開されません）
• OS を確認せずに / を使ったパス文字列を書く
• GNU 版か BSD 版か確認せずに grep のフラグを使用する
• シェルが | に対応しているか分からない状態でコマンドをパイプする

このリストの項目に該当したら、コマンドの実行を停止してください。まず検出しましょう。

統合

関連するスキル：

• godmode:project-bootstrap -- プロジェクトのセットアップ中に環境を検出します
• godmode:fault-diagnosis -- 環境の不一致は、原因不明の障害のよくある根本原因です
• godmode:workspace-isolation -- Worktree とコンテナーのセットアップには、適切なプラットフォームコマンドが必要です
• godmode:deployment-advisor -- システムインベントリーの結果は、デプロイの推奨事項とプラットフォームの選択に直接反映されます

要点

One detection probe now > ten failed commands later

OS を把握する。シェルを把握する。パッケージマネージャーを把握する。最初のコマンドを実行する前に。セッションのたびに必ず。