Claude Code の PowerShell ツール — Windows ネイティブ開発で WSL を経由しない選択肢

PowerShell ツールが解決する課題

Claude Code を Windows 環境で使う際、これまで以下のような課題がありました。

WSL2 依存の問題点:

• \\wsl$\ 経由のパスで Windows と Linux のファイルシステムが混在し、パス解決でエラーが起きやすい
• Windows レジストリや COM オブジェクトへのアクセスが困難
• PowerShell スクリプト（.ps1）を直接実行できません
• Active Directory・Azure AD との連携に余計なラッパーが必要

PowerShell ツールはこれらの問題を根本から解消し、Windows ネイティブの開発・運用ワークフローを Claude Code から直接操作できるようにします。

前提環境

PowerShell ツールを利用するには、以下の環境が必要です。

• Claude Code v2.1.84 以降
• Windows 10 / 11 または Windows Server 2019 / 2022
• PowerShell 5.1 または PowerShell 7.x（推奨）
• Node.js 18 以降（Claude Code のランタイム）

PowerShell のバージョン確認は以下のコマンドで行えます。

# PowerShell バージョン確認
$PSVersionTable.PSVersion
 
# 出力例
Major  Minor  Build  Revision
-----  -----  -----  --------
7      4      7      0

PowerShell 7.x（PowerShell Core）を使用することを強くおすすめします。クロスプラットフォーム対応が進んでおり、セキュリティ機能も充実しているためです。

PowerShell ツールの有効化手順

PowerShell ツールはオプトイン・プレビューです。有効化は環境変数 CLAUDE_CODE_USE_POWERSHELL_TOOL の1つだけで、UI のトグルを探しても見つかりません。私も最初は /config のメニューを上から下まで眺めて時間を溶かしました。

方法1: settings.json の env に書く（推奨）

~/.claude/settings.json（Windows では %USERPROFILE%\.claude\settings.json）を開き、env ブロックに追加します。

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
  }
}

値は文字列の "1" です。真偽値の true ではありません。保存して Claude Code を起動し直すと反映されます。Windows では段階的な自動有効化の対象になっているため、逆に切りたいときは "0" を指定します。

方法2: 起動前にシェルで環境変数を渡す

一時的に試すだけなら、起動前に環境変数を立てるほうが手軽です。設定ファイルを汚さずに済むので、挙動の比較検証にも向いています。

# 現在のセッションだけで有効化して起動する
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
claude
 
# 恒久化したい場合はユーザー環境変数へ
[Environment]::SetEnvironmentVariable("CLAUDE_CODE_USE_POWERSHELL_TOOL", "1", "User")

PowerShell の実行ファイルは Claude Code が自動判別します。pwsh.exe（PowerShell 7 以降）が優先され、無ければ powershell.exe（5.1）にフォールバックします。バージョンを設定で指定する項目はありません。

有効化しても、まだ PowerShell は使われません

ここが最もつまずきやすい点です。有効化しても Bash ツールは登録されたまま残り、Claude が自分から PowerShell を選ぶわけではありません。明示的に「PowerShell で実行して」と伝えるか、シェルの振り分け設定を入れる必要があります。

hook だけは有効化フラグと独立して動きます。hook は PowerShell を直接起動するためで、「ツール全体はまだ切り替えたくないが、整形フックだけ PowerShell で回したい」という段階的な移行に使えます。私は実際、この hook 単位の切り替えから入りました。

有効化の確認

Claude Code を起動し、次のように入力して PowerShell ツールが使えるか確認しましょう。

Claude Code のツールに PowerShell は含まれていますか？

有効化されていれば、Claude が PowerShell を使ってコマンドを実行できる旨を返答します。

有効化されているかを、読み取りだけで確かめる

「有効化したはずなのに効かない」ときは、どこで値が途切れているかを順に見ていくのが近道です。次のスクリプトは何も書き換えず、4か所の値を並べて表示します（?? を使うため PowerShell 7 で実行してください）。

# 有効化の四点確認（読み取り専用）
$flag = "CLAUDE_CODE_USE_POWERSHELL_TOOL"
$settings = Join-Path $env:USERPROFILE ".claude\settings.json"
 
"プロセス環境変数 : " + ((Get-Item "Env:$flag" -ErrorAction SilentlyContinue).Value ?? "(未設定)")
"ユーザー環境変数 : " + ([Environment]::GetEnvironmentVariable($flag, "User") ?? "(未設定)")
 
if (Test-Path $settings) {
  $json = Get-Content $settings -Raw | ConvertFrom-Json
  "settings.json の env : " + ($json.env.$flag ?? "(未設定)")
} else {
  "settings.json : 見つかりません ($settings)"
}
 
$exe = (Get-Command pwsh -ErrorAction SilentlyContinue) ?? (Get-Command powershell -ErrorAction SilentlyContinue)
"使われそうな実行ファイル : " + ($exe.Source ?? "(見つかりません)")

読み方はシンプルです。ユーザー環境変数にだけ値があってプロセス環境変数が空なら、そのターミナルは設定の前に起動されたものです。VS Code や Cursor のように、親プロセスが古い環境を引き継いでいる場合もここで見つかります。settings.json に値がなければ、方法1の書き込みが保存されていません。

私はこの確認を、設定を疑う前の最初の一手にしています。設定ファイルを何度も開き直すより、四つの値を並べて眺めるほうが、はるかに早く原因に辿り着けました。

基本的な使い方

PowerShell ツールを有効化すると、Claude Code は Bash に加えて PowerShell でもコマンドを実行できるようになります。Windows 環境では適切なツールが自動的に選択されます。

ファイル・ディレクトリ操作

# カレントディレクトリの一覧表示
Get-ChildItem -Path . -Recurse -Filter "*.ts" | Select-Object FullName
 
# ファイルの内容確認
Get-Content .\src\components\Button.tsx
 
# ディレクトリの作成
New-Item -ItemType Directory -Path ".\src\features\auth"
 
# ファイルのコピー（バックアップ）
Copy-Item .\config.json .\config.json.bak

システム情報の取得

# インストール済み Node.js バージョン
node --version
# 出力例: v22.14.0
 
# 利用可能なメモリ
Get-CimInstance Win32_OperatingSystem | Select-Object FreePhysicalMemory, TotalVisibleMemorySize
 
# 環境変数の確認
[System.Environment]::GetEnvironmentVariable("PATH", "User")

パッケージ管理

# npm パッケージの一覧確認
npm list --depth=0
 
# グローバルパッケージの更新
npm update -g
 
# pnpm によるインストール
pnpm install --frozen-lockfile

セキュリティ機能の詳細

PowerShell ツールには、危険なコマンド検出システムと統合されたセキュリティ機能が組み込まれています。以下の4点は v2.1.84 の初出時ではなく、その直後の v2.1.89〜2.1.90（2026年4月1日）で追加された強化です。使い始めの時期によっては入っていない可能性があるので、古いバージョンのまま止まっている方は先に更新をおすすめします。

バックグラウンドジョブ迂回の防止

PowerShell の & 演算子を使ったバックグラウンド実行は、セキュリティチェックを迂回するために悪用されることがあります。Claude Code はコマンド末尾に & が付いている場合、実行前に確認を求めます。

# ❌ この形式は確認プロンプトが表示される
Start-Process notepad.exe &
 
# ✅ 通常の実行（問題なし）
Start-Process notepad.exe

-ErrorAction Break の制御

デバッガーをハングさせる可能性がある -ErrorAction Break パラメーターは、Claude Code によって監視され、予期しない動作が起きないよう処理されます。

アーカイブ展開時の TOCTOU 防止

Expand-Archive などのアーカイブ展開コマンドは、展開先パスの検証を経てから実行されます。Time-of-Check-Time-of-Use（TOCTOU）攻撃パターンへの対策です。

PS 5.1 引数分割の強化

外部コマンドの引数にダブルクォートと空白が両方含まれる場合、PowerShell 5.1 特有の引数分割問題が発生することがあります。Claude Code はこのケースを検出し、自動許可ではなく確認プロンプトを表示します。

# ⚠️ PS 5.1 での注意点（引数にダブルクォートと空白を含む場合）
# Claude Code が確認を求める例:
& "C:\Program Files\MyApp\app.exe" "input file.txt"

Auto Mode 既定化と PowerShell ツールがぶつかる場所

2026年8月14日から、Auto Mode が Pro・Max・Team で既定有効になりました。承認を1手ずつ求める代わりに、分類器が「取り消せない・破壊的・自分の環境の外へ向かう」操作だけで止めるという仕組みです。

ここで Windows 利用者だけが直面する食い違いがあります。PowerShell ツールはまだ Auto Mode に対応していません。つまり既定が変わっても、PowerShell 経由のコマンドは自動承認されず、確認プロンプトが出続けます。Bash 側は静かに進むのに PowerShell 側だけ止まるので、「自分の設定が壊れているのでは」と疑いやすい状況です。

私はこの非対称を、欠陥ではなく当面の設計として受け入れることにしました。そのうえで作業を次のように振り分けています。

3行目は確認プロンプトが出ること自体を利点として扱っています。レジストリやサービスの書き換えは、そもそも一度立ち止まってよい操作です。Auto Mode 非対応という制約が、たまたま慎重に扱いたい領域と重なっているのは、幸運な偶然だと感じています。

なお、Windows のレジストリ書き込みで Auto Mode の確認が出続ける挙動は、claude-code の issue #51916 でも報告されています。プレビューが外れるまでは、この非対称を前提に設計しておくのが安全です。

8月の2日間で、Windows の権限まわりが3回動いた話

この記事を最初に書いた4月以降、Windows の権限チェックには続きがありました。8月13日の v2.1.232 と、翌14日の v2.1.233 です。片方だけを読むと判断を誤るので、並べて整理します。

v2.1.232 で入った修正は、Windows 利用者に直接関係するものが3つありました。

• PowerShell の権限バイパス — 変数へ書き込むパラメーターが $PSDefaultParameterValues を黙って上書きし、後続コマンドのファイルアクセス先を差し替えられる状態でした。PowerShell ツールそのものに関わる修正です
• Git Bash が Cygwin 形式のシンボリックリンクを辿る問題。パス検証からは通常のファイルに見えていました
• ネストした git リポジトリが親ディレクトリの信頼を継承する問題。各リポジトリが個別に信頼確認を求めるようになりました

ところが翌日の v2.1.233 で、このうち2番目の Cygwin シンボリックリンクの変更と、同時に入っていた入力リダイレクト（< file）の権限チェックが差し戻されました。「より絞り込んだ版を後のリリースで戻す」と説明されています。あわせて、v2.1.232 の副作用として cd <dir> && <command> > file のような普通のコマンドで Auto Mode が何度も止まる不具合も修正されています。

つまり8月16日時点で有効なのは次の状態です。

ここから引き出せる実務的な結論は2つあります。ひとつは、v2.1.232 で止まるようになった操作を前提に運用手順を書き換えていた場合、v2.1.233 で再び黙って通るようになっているということです。差し戻された2項目は「後で戻る」と明言されているので、その運用手順は捨てずに置いておくのが良いと思います。

もうひとつは、8月13日から14日にかけて Windows で Auto Mode の確認が異様に増えたと感じた方がいれば、それは設定の問題ではなく v2.1.232 の回帰だったということです。v2.1.233 へ上げれば収まります。

# 手元のバージョンを確認する
claude --version
 
# 更新する
claude update

権限チェックの範囲がこれだけ短い間隔で動くのは、裏を返せば Windows の経路が実際に精査されている証拠でもあります。細かな挙動を暗記するより、claude --version を確認する習慣のほうが役に立つと感じています。

環境変数の永続化と Windows 固有のつまずき

ここまで /config または settings.json での有効化を見てきましたが、現場では「マシンを再起動したら設定が消える」「VS Code から起動したときだけ効かない」「PowerShell の実行ポリシーで弾かれる」といった Windows 固有のつまずきもよくあります。私が実際に複数台の Windows 開発機で運用してきて辿り着いた、3つの永続化パターンを整理します。

パターン1: PowerShell プロファイル（$PROFILE）での永続化（個人開発機向け）

PowerShell 起動時に毎回読み込まれる $PROFILE に環境変数の設定を書いておくのが、最も柔軟で推奨できる方法です。

# プロファイルファイルのパスを確認（存在しなければ作成される）
echo $PROFILE
# 出力例: C:\Users\YourName\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
 
# プロファイルをエディタで開く
notepad $PROFILE

開いたファイルに次の行を追加して保存します。

# Claude Code PowerShell ツールを既定で有効化
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"

新しいターミナルで設定が反映されます。即座に反映したい場合は . $PROFILE を実行してください。

パターン2: Windows のシステム環境変数として設定（チーム配布向け）

複数のターミナルや GUI ツール（VS Code、Cursor 等）から起動するときに毎回有効にしたい場合は、Windows のシステム環境変数として登録します。

1. Windows キー → 「環境変数」と検索 → 「システム環境変数の編集」
2. 「環境変数」ボタンをクリック
3. 「ユーザー環境変数」の「新規」をクリック
4. 変数名: CLAUDE_CODE_USE_POWERSHELL_TOOL、値: 1
5. OK で保存（既存ターミナルは再起動が必要）

この方法は社内配布用のセットアップスクリプトに組み込みやすいので、複数開発者に同じ設定を配布したいときに便利です。

パターン3: VS Code 統合ターミナルから使う場合

VS Code から claude を起動するときは、settings.json でデフォルトターミナルを PowerShell にしておくのが確実です。

{
  "terminal.integrated.defaultProfile.windows": "PowerShell"
}

これで VS Code のターミナルが PowerShell で開き、上のパターン1または2で設定した $env:CLAUDE_CODE_USE_POWERSHELL_TOOL が引き継がれます。

よくあるつまずき: 「PowerShell スクリプトの実行が無効になっています」

Set-ExecutionPolicy で弾かれることが時々あります。組織のセキュリティポリシーによっては変更できないこともあるので、現状を確認してから判断しましょう。

# 現在のポリシーを確認
Get-ExecutionPolicy
 
# 現在のユーザーに対してスクリプト実行を許可（最も穏当な選択）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

RemoteSigned は「ローカルのスクリプトは実行可、ダウンロード元のスクリプトは署名検証必要」という設定で、個人開発から小規模チーム運用まで幅広く使えます。組織の管理対象 PC では IT 管理者と相談してから変更してください。

実践的なワークフロー例

1. Azure リソース管理

# Azure CLI との連携（az コマンド）
az account show --output json | ConvertFrom-Json | Select-Object name, id
 
# Azure リソースグループの一覧
az group list --output table
 
# App Service の起動状態確認
az webapp show --name my-app --resource-group my-rg --query "state" --output tsv

Claude への指示例:

Azure の開発リソースグループに含まれるリソースを一覧表示して、
未使用のリソース（30日以上アクセスのない App Service）を特定してください。

2. Active Directory / Entra ID の操作

# ActiveDirectory モジュールのインポート（Active Directory 環境）
Import-Module ActiveDirectory
 
# ユーザーの所属グループ確認
Get-ADUser -Identity "john.doe" -Properties MemberOf | Select-Object MemberOf
 
# 無効化されたアカウントの一覧
Search-ADAccount -AccountDisabled -UsersOnly | Select-Object Name, SamAccountName

3. Windows イベントログの分析

# 直近24時間のエラーイベント取得
$since = (Get-Date).AddHours(-24)
Get-WinEvent -LogName "Application" -FilterHashtable @{
    Level = 2
    StartTime = $since
} | Select-Object TimeCreated, Id, Message | Format-Table -AutoSize

Claude に「アプリケーションログの異常を分析して」と依頼すると、このスクリプトを実行しながら内容を解釈してくれます。

4. CI/CD パイプライン補助

# ビルド番号の取得とバージョニング
$buildNumber = $env:BUILD_BUILDNUMBER ?? "local"
$version = "1.0.$buildNumber"
Write-Host "##[set-variable name=Version;value=$version]"
 
# テスト実行と結果パース
$testResult = dotnet test --logger trx --results-directory .\TestResults 2>&1
$failed = $testResult | Select-String "Failed: (\d+)" | ForEach-Object { $_.Matches[0].Groups[1].Value }
if ([int]$failed -gt 0) { exit 1 }

/env コマンドとの連携

PowerShell ツールは /env コマンドと統合されています。セッション中に環境変数を設定すると、PowerShell ツールの実行にも反映されます。

/env NODE_ENV=production
/env AZURE_SUBSCRIPTION_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

これにより、CI/CD 環境を模倣したローカルテストが容易になります。

よくあるエラーと対処法

エラー: 「スクリプトの実行が無効になっています」

File C:\...\script.ps1 cannot be loaded because running scripts is disabled on this system.

対処法: PowerShell の実行ポリシーを確認・変更します。

# 現在の実行ポリシー確認
Get-ExecutionPolicy -List
 
# 現在のユーザーのみ RemoteSigned に変更（推奨）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

エラー: 「pwsh が見つかりません」

pwsh.exe が見つからず、powershell.exe（5.1）へのフォールバックも効かない場合に発生します。PowerShell 7 を入れておくのが確実です。

# PowerShell 7 のインストール（winget 使用）
winget install --id Microsoft.PowerShell -e
 
# または公式サイトから MSI をダウンロード
# https://github.com/PowerShell/PowerShell/releases

インストール後、Claude Code を再起動してください。

確認プロンプトが頻繁に出る（これは不具合ではありません）

Get-ChildItem のような無害な取得系でも毎回確認を求められて、設定を間違えたのかと疑う場面があります。これは設定ミスではなく、プレビュー段階の仕様です。PowerShell ツールは Auto Mode に未対応で、PowerShell 経由のコマンドは自動承認の対象になりません。承認をまとめて省く設定は、現時点では存在しないと考えたほうが早いです。

現実的に減らす手は2つあります。ひとつは、プロンプトが出たときに「常に許可」を選ぶことです。/permissions が対応する許可ルールを書き込んでくれるので、取得系だけを手元で積み上げていけます。ルールの書式を自分で調べて書くより確実です。

/permissions

もうひとつは、繰り返し実行する定型処理を hook に逃がすことです。hook の "shell": "powershell" は有効化フラグと独立して動くため、確認を挟みたくない決まりきった処理だけを PowerShell で回せます。私は整形とリンタをこちらに寄せ、対話中のコマンドは確認が出るままにしています。止まる回数そのものより、止まる対象が予測できるかどうかのほうが、結局は疲れにくいと感じています。

切り替え判断でつまずきやすい2点

PowerShell 5.1 と PowerShell 7（pwsh）はどちらを使うべきか

基本は PowerShell 7（pwsh）です。クロスプラットフォーム・パフォーマンス・新しい構文サポートいずれの面でも 5.1 より優れています。例外は ActiveDirectory モジュールなど一部の Windows 専用モジュールが 5.1 のみ対応の場合で、その場合だけ 5.1 を選ぶ運用にしています。

WSL2 はもう不要になるのか

ケースバイケースです。Python ライブラリのビルド、Docker、Linux 固有コマンドが要る場面では、WSL2 がまだ頼りになります。一方、Windows ネイティブの管理タスクや .NET 環境の自動化は PowerShell ツールだけで完結することが増えました。私自身は「Linux 寄りなら WSL2、Windows 寄りなら PowerShell ツール」という大雑把な切り分けで運用しています。

レシピ 1: winget を使ったプロジェクト立ち上げ自動化

新しいリポジトリをクローンしたあとに必要な依存ツールを winget で一括導入する流れは、README に書いてあっても結局手で入れる人が多いと思います。Claude Code に依頼して PowerShell Tool 経由で実行させると、必要な分だけインストールしつつ、すでに入っているツールはスキップしてくれます。

# Claude Codeに「このリポを動かすのに必要なツールをwingetで揃えて」と頼んだときに走るパターン
$tools = @("Microsoft.PowerShell", "GitHub.cli", "Microsoft.DotNet.SDK.9", "Microsoft.VisualStudioCode")
foreach ($id in $tools) {
  if (-not (winget list --id $id -e --accept-source-agreements 2>$null | Select-String $id)) {
    winget install --id $id -e --silent --accept-source-agreements --accept-package-agreements
  } else {
    Write-Host "Skip: $id (already installed)"
  }
}

ポイントは winget list でインストール済みかを確認してから winget install を呼ぶことです。これをやらないと、Claude が二重インストールを試みてエラーで止まる場面に何度か遭遇しました。

レシピ 2: PR を出すときに gh CLI と連携させる

GitHub CLI は WSL 側にも入りますが、Windows 側で gh を入れておくと PowerShell Tool 経由で直接 PR を作れて便利です。私がよく使うのは、Claude にコード変更を任せたあとに「ブランチ切って push して PR 出すところまで」を 1 ステップで片付けるパターンです。

# 変更を確認 → ブランチ作成 → コミット → push → PR作成までのワンライナー
$branch = "feat/$(Get-Date -Format yyyyMMdd-HHmm)-claude-edit"
git checkout -b $branch
git add -A
git commit -m "Apply Claude edits"
git push -u origin $branch
gh pr create --fill --web

gh pr create --fill --web は本文を自動補完しつつブラウザを開いてくれるので、最終確認の習慣を保ちながらスピードが出ます。Claude に PR 本文まで書かせる場合は --fill を --body "$(cat .git/CLAUDE_NOTE.md)" のように差し替える形が好みです。

レシピ 3: dotnet プロジェクトのテストとカバレッジを 1 コマンドで

.NET 開発で dotnet test 単体ではカバレッジが取れず、いつも coverlet を組み合わせる手順を忘れがちでした。Claude にレシピとして覚えさせておくと、毎回同じ品質チェックを再現できます。

$proj = ".\src\MyApp.Tests\MyApp.Tests.csproj"
dotnet test $proj `
  --collect:"XPlat Code Coverage" `
  --results-directory ./TestResults `
  --logger "console;verbosity=normal"
$cov = Get-ChildItem .\TestResults -Recurse -Filter coverage.cobertura.xml | Sort-Object LastWriteTime -Descending | Select-Object -First 1
Write-Host "Coverage report: $($cov.FullName)"

PowerShell の Backtick での折り返しは Bash 出身者には違和感があるかもしれませんが、Claude に「Backtick で改行して」と一言伝えると以後はその形で出してくれます。

レシピ 4: WSL と PowerShell をまたぐファイル操作を安全にやる

PowerShell Tool が増えてもなお WSL を完全に捨てるのは惜しい場面があります。例えば Linux ネイティブのツール（ripgrep の最新版、jq など）を併用したいとき、PowerShell から WSL を呼び出すパターンが現実的です。ここでハマりやすいのが「WSL に渡したパスが認識されない」問題です。

# C:\Users\me\proj を WSL 側でgrepするときの正しい呼び出し方
$winPath = "C:\Users\me\proj"
$wslPath = wsl wslpath -a "$winPath"
wsl rg --hidden --no-ignore "TODO" $wslPath

wslpath -a で正確に POSIX 形式へ変換してから渡すのが鍵です。直接 C:\Users\me\proj を渡すと、WSL 側で「No such file」になりがちで、Claude も最初は素直に Windows パスを渡してしまうので、レシピ化しておくと安定します。

レシピ 5: Stripe や AdMob の管理 CLI を統合する

私の場合、Stripe CLI と Firebase CLI を Windows 側に入れています。これらを Claude Code から PowerShell Tool 経由で呼べるようにしておくと、課金や AdMob のデバッグが格段に速くなります。

# 直近24時間のStripeイベントから決済失敗だけ抜き出す
stripe events list --limit 100 --format json | `
  ConvertFrom-Json | `
  Where-Object { $_.type -like "*payment_intent.payment_failed*" } | `
  Select-Object id, created, type, @{n="amount";e={$_.data.object.amount}} |
  Format-Table -AutoSize

Claude に「最近の決済失敗を一覧化して」と依頼するだけで、このスクリプトを書いて実行してくれます。何度か使うコマンドはサブエージェントの設定（CLAUDE.md）に「stripe イベント分析時は ConvertFrom-Json でフィルタする」と記録しておくと、次回からの会話が短くなります。

レシピ 6: Windows サービスの再起動を安全にやらせる

PowerShell の Restart-Service は管理者権限が必要なケースがあり、Claude が黙って sudo 風に試して失敗することがあります。これを避けるため、私は最初から「権限が必要な場合は元の管理者プロンプトを開いて」と促す形のラッパーを Claude に書かせています。

function Restart-ServiceIfPossible {
  param([string]$ServiceName)
  $svc = Get-Service -Name $ServiceName -ErrorAction SilentlyContinue
  if (-not $svc) { Write-Warning "Service not found: $ServiceName"; return }
  try {
    Restart-Service -Name $ServiceName -Force -ErrorAction Stop
    Write-Host "Restarted: $ServiceName"
  } catch {
    Write-Warning "Restart failed (likely needs admin). Try: Start-Process pwsh -Verb RunAs"
  }
}

PowerShell Tool 経由で動かすときは、-Verb RunAs で別プロセスを開く挙動がそのまま走るので、ユーザー操作をブロックせずに権限昇格を促せるのが地味に便利です。

レシピを無人実行させる前に — 副作用の大きい操作に確認を挟む

ここまでのレシピは、手元で結果を見ながら使う分には快適です。ただ無人実行を視野に入れると話が変わります。winget install や Restart-Service のように環境を書き換えるコマンドが並んでいるからです。

先に書いたとおり、PowerShell ツールは現時点で Auto Mode に未対応なので、これらが完全な無人で走ることは今のところありません。ただしこれは仕様上の保護ではなく、プレビュー段階の副産物です。対応が入った瞬間に消える前提で設計しておかないと、そのリリースで足をすくわれます。私は「今は止まってくれる」ことを安全策の根拠にしないようにしています。

私は「一覧・取得は止めずに通す、状態を変えるものは一度止める」を基準にしています。PowerShell 側でできる手堅い方法は、状態を変える cmdlet に -WhatIf を付けて、まず実行計画だけを出させることです。

# 破壊的操作はまず -WhatIf で実行計画だけを確認する
function Invoke-ServiceRestartSafely {
  param([string]$ServiceName, [switch]$Apply)
  if (-not $Apply) {
    Restart-Service -Name $ServiceName -WhatIf
    Write-Host "計画のみ表示しました。実行するには -Apply を付けてください。"
    return
  }
  Restart-Service -Name $ServiceName -Force
}

Claude には「破壊的な操作はまず -WhatIf を付けて計画を見せて」と CLAUDE.md に書いておくと、Restart-Service や Remove-Item のような cmdlet が勝手に本番実行されるのを防げます。あわせて Claude Code 側の /permissions で、winget list のような取得系は許可、winget install のような導入系は確認を要求するよう分けておくと、無人実行でも「壊しうる操作の手前で必ず一度止まる」状態を保てます。レシピ 6 のラッパーで権限昇格を促す設計と、この二段構えは相性が良いと感じています。

ここまでをチームで共有するときの工夫

これらのレシピは個人の Microsoft.PowerShell_profile.ps1 に貯めても良いのですが、私はチームでも使えるように、リポジトリ直下の .tools/recipes.ps1 に集約しています。Claude には「.tools/recipes.ps1 を読み込んでから作業して」と CLAUDE.md に書いておけば、毎回同じレシピを下敷きに動いてくれます。

# .tools/recipes.ps1 の冒頭で関数を一括 dot-source
. "$PSScriptRoot\install-deps.ps1"
. "$PSScriptRoot\test-coverage.ps1"
. "$PSScriptRoot\service-helpers.ps1"

起動オーバーヘッドを WSL2 経由と比べる手順

切り替えの基準を頭の中だけで決めず、同じ処理を両方の経路に流して、起動まわりのオーバーヘッドを比べる方法を書き残します。対象は「カレント配下の .ts ファイルを列挙する」という、ごく軽い処理です。

# PowerShell ツール側で計測
Measure-Command { Get-ChildItem -Recurse -Filter *.ts | Out-Null } |
  Select-Object -ExpandProperty TotalMilliseconds
 
# 同じ処理を WSL2 経由（bash + find）で計測
Measure-Command { wsl find . -name '*.ts' | Out-Null } |
  Select-Object -ExpandProperty TotalMilliseconds

あえて数値は載せていません。結果はマシン・ディスク・セキュリティソフトの状態で大きく変わりますし、私の側でも、記事に載せる数字を再現できる形で残せていないためです。お手元で、初回と2回目以降を分けて数回ずつ計測し、中央値で比べていただければと思います。

見ていただきたいのは絶対値ではなく、WSL2 を挟む経路で初回呼び出しに固定コストが乗るかどうかです。単発の重い処理であれば、固定コストは誤差の範囲に収まるはずです。一方、環境変数を読み直しながら小さなコマンドを何十回も繰り返すワークフローでは、その固定コストが体感速度に効いてくる可能性があります。

環境変数の永続化パターンそのものは Claude Code の環境変数リファレンス に細かくまとめています。なお、計測のために settings.json をいじって起動しなくなった場合は、壊れた settings.json からの復旧手順 をたどれば安全に元へ戻せます。私は計測用の設定を別ファイルに切り出しておき、本番の設定を汚さないようにしています。

全体を振り返って

Claude Code v2.1.84 で追加された PowerShell ツールは、Windows で WSL2 を挟まずに済むという一点で、開発体験を確かに変えてくれます。一方で、有効化の方法もプレビュー特有の制約も、公式の一次情報にあたらないと誤解したままになりやすい領域でもありました。本記事のポイントを整理します。

• 有効化は settings.json の env に CLAUDE_CODE_USE_POWERSHELL_TOOL: "1" を書く一手のみです（UI のトグルは存在しません）
• Bash ツールと並行して使え、Windows ネイティブのリソースへ直接届きます
• 有効化しても、Claude が自分から PowerShell を選ぶことはありません。defaultShell か hook の shell で振り分けます
• Auto Mode には未対応で、確認プロンプトは出続けます。止まる領域を自分で選んで設計します
• Windows の権限チェックは8月に3度動きました。差し戻された項目もあるため、claude --version の確認を習慣にします
• Azure・Active Directory・Windows イベントログのように、WSL2 から届きにくい領域で力を発揮します
• /env コマンドと組み合わせると、環境変数の管理が一か所で済みます

振り返ってみると、このツールでいちばん手間をかけたのは機能の習得ではなく、止まる場所の設計でした。止まる場所は、Claude ではなく私が先に決めておく。 この線引きだけは、プレビューが外れたあとも変えないつもりでおります。

Claude Code のツール権限をさらに細かく制御したい方には、Claude Code のツール権限を自分好みに設定する の記事がおすすめです。許可・確認・拒否のポリシーを使い分け、安全性と開発効率を両立させる方法を詳しく解説しています。

次のアクション

明日からできることは、自分のリポジトリの README に「Claude Code から PowerShell Tool で叩いてほしい 1 行」を追記することです。たとえば「./scripts/setup.ps1 を最初に流す」という指示があるだけで、Claude の初動が大きく変わります。レシピは資産として育てるものなので、まずは 1 つ書いて使ってみてください。