review-powershell

スキル：PowerShell のレビュー

目的

PowerShell のコードを、言語およびランタイムの規約に限ってレビューします。スコープ（差分かコードベース全体か）は定義せず、セキュリティやアーキテクチャの分析も行いません。これらはスコープスキルと認知スキルが担当します。集約に使う標準形式で指摘事項のリストを出力します。高度な関数の設計、パラメーターの検証とバインド、エラー処理の意味論、オブジェクトのパイプライン動作、モジュールのエクスポートと命名規約、互換性（Windows PowerShell と PowerShell 7 以降）、テスト容易性に重点を置きます。

---

中核目標

主な目標：指定されたコード範囲について、関数設計、パラメーターの契約、エラー処理、パイプライン動作、状態とスコープ、互換性、テスト容易性を網羅する、PowerShell 言語／ランタイムの指摘事項リストを作成します。

成功基準（すべてを満たす必要があります）：

1. ✅ PowerShell のみを対象とする：PowerShell の言語およびランタイムの規約のみをレビューします。スコープの選択、セキュリティ分析、アーキテクチャ分析は行いません
2. ✅ PowerShell の 7 つの観点をすべて確認する：高度な関数／コマンドレットの規約、パラメーターの設計／検証、エラー処理の意味論、オブジェクトのパイプライン動作、状態／スコープ／厳密性、互換性／移植性、テスト容易性を、関連する範囲で評価します
3. ✅ 指摘事項の形式に準拠する：各指摘事項に、findings-list §5.1 が求めるすべての要素を含め、カテゴリを language-powershell とします
4. ✅ ファイルと行番号を記載する：すべての指摘事項に、行番号を含む具体的なファイル位置を記載します
5. ✅ PowerShell 以外のコードを除外する：明示的に対象範囲に含まれていない限り、PowerShell 固有の規則について PowerShell 以外のファイルを分析しません

受け入れテスト：セキュリティ、アーキテクチャ、スコープの分析を行わずに、関連するすべての言語／ランタイムの観点を網羅し、ファイルと行番号を記載した PowerShell に特化した指摘事項リストが出力されていますか？

---

スコープの境界

このスキルが扱うこと：

• [CmdletBinding()]、Verb-Noun 命名、承認済みの動詞、begin/process/end ブロック
• パラメーターの型、Mandatory、ValueFromPipeline、パラメーターセット、検証属性
• 終了エラーと非終了エラー、-ErrorAction Stop、エラーの黙殺防止
• オブジェクトのパイプライン動作（書式設定済みテキストよりオブジェクトを優先、Write-Host と Write-Verbose の使い分け）
• 状態、スコープ、厳密性（グローバル状態への副作用、設定変数の変更）
• Windows PowerShell 5.1 と PowerShell 7 以降の互換性および移植性
• パフォーマンスとテスト容易性（Pester でテストしやすい関数設計、DI の分離点）

このスキルが扱わないこと：

• スコープの選択 — スコープは呼び出し元が指定します
• セキュリティ分析 — review-security を使用してください
• アーキテクチャ分析 — review-architecture を使用してください
• レビュー全体のオーケストレーション — orchestrate-code-review を使用してください

引き継ぎ先：PowerShell に関する指摘事項をすべて出力したら、集約のため orchestrate-code-review に引き継ぎます。セキュリティ上の懸念（例：コマンドインジェクション、認証情報の露出）がある場合は、その旨を記載し、review-security の利用を提案してください。

---

ユースケース

• オーケストレーションされたレビュー：orchestrate-code-review が PowerShell プロジェクトに対し、scope -> language -> framework -> library -> cognitive の順で実行される際、言語レビューのステップとして使われます。
• PowerShell のみのレビュー：ユーザーが言語／ランタイムの規約だけの確認を希望する場合に使われます。
• PR 前のスクリプト品質チェック：マージ前にパラメーターの契約、パイプライン動作、エラーの意味論を検証します。

使用する場合：レビュー対象のコードが PowerShell（.ps1、.psm1、.psd1）であり、タスクに言語／ランタイムの品質確認が含まれる場合に使用します。スコープは呼び出し元またはユーザーが決定します。

---

動作

このスキルの対象範囲

• 分析対象：呼び出し元から提示された指定コード範囲（ファイルまたは差分）における、PowerShell の言語仕様とランタイムの慣例。対象範囲は決めず、入力として受け取ってください。
• 対象外：対象範囲の選定、セキュリティレビュー、アーキテクチャレビューは行わないでください。明示的に対象範囲に含まれていない限り、PowerShell 固有のルールに関して PowerShell 以外のファイルをレビューしないでください。

レビューチェックリスト（PowerShell の観点のみ）

1. 高度な関数とコマンドレットの慣例：適切な場合は [CmdletBinding()] を使用し、承認済み動詞を使った Verb-Noun 形式の命名にし、必要な場合にのみ begin/process/end ブロックを使用します。
2. パラメーターの設計と検証：パラメーターの型、Mandatory、ValueFromPipeline、パラメーターセット、検証属性（ValidateSet、ValidatePattern、ValidateScript）に矛盾がなく、一貫性があることを確認します。
3. エラー処理のセマンティクス：終了エラーと非終了エラーを区別し、必要に応じて -ErrorAction Stop を使用します。エラーを黙って無視したり、空の catch を使用したりしないでください。
4. オブジェクトパイプラインの動作：内部処理では書式設定済みテキストよりもオブジェクトを優先し、データ出力に Write-Host を使用しないでください。関数の出力が予測可能で、パイプラインで安全に扱えることを確認します。
5. 状態、スコープ、厳密性：意図しないグローバルな副作用や状態を持つ副作用、制御されていない設定変数の変更、曖昧な変数の初期化を避けます。適切な場合は厳密モードを使用します。
6. 互換性と移植性：Windows PowerShell 5.1 と PowerShell 7 以降の違い、プラットフォーム固有のコマンドやモジュール、パスの扱いを考慮します。
7. パフォーマンスとテスト容易性：パイプラインのコストの高い誤用や、配列の繰り返し結合を避けます。Pester でテストしやすく、依存関係を分離しやすいように関数を構成します。

トーンと参照

• プロフェッショナルかつ技術的に：具体的な場所（file:line）を示します。 findings-list §5.1 が求めるすべての要素を含む指摘を出力します。

---

入力と出力

入力

• コード範囲：ユーザーまたはスコープスキルがすでに選定したファイル、ディレクトリ、または差分。このスキルでは対象範囲を決めず、提示された PowerShell コードについて言語上の慣例のみをレビューします。

出力

• Category が language-powershell の、specs/findings-list.md で定義された形式の指摘を、0 件以上出力します。
• このスキルの Category は language-powershell です。

---

制約

厳守すべき境界

• セキュリティ、アーキテクチャ、対象範囲の選定に関する作業は行わないでください。PowerShell の言語仕様とランタイムの慣例に限定してください。
• 具体的な場所や実行可能な提案なしに結論を述べないでください。
• 明示的に対象範囲に含まれていない限り、PowerShell 固有のルールに関して PowerShell 以外のコードをレビューしないでください。

スキルの境界

以下の作業は行わないでください（他のスキルが担当します）。

• コード範囲の選定や定義は行わないでください。対象範囲は呼び出し元または orchestrate-code-review が決定します。
• セキュリティ分析（認証情報の取り扱い、インジェクションのリスク）は行わないでください。review-security を使用してください。
• アーキテクチャ分析は行わないでください。review-architecture を使用してください。

作業を終了して引き継ぐタイミング：

• PowerShell に関するすべての指摘を出力したら、集約のために orchestrate-code-review へ引き継ぎます。
• ユーザーが完全なレビュー（対象範囲＋言語＋認知面）を必要としている場合は、orchestrate-code-review へ案内します。
• セキュリティ上の懸念（認証情報の露出、コマンドインジェクション）が見つかった場合は、その旨を伝え、review-security を提案します。

---

セルフチェック

主な成功基準

• PowerShell のみを対象：PowerShell 言語とランタイムの規約のみをレビューし、スコープの選定、セキュリティ、アーキテクチャの分析は行わない
• PowerShell の 7 つの観点をすべて網羅：該当する場合に、高度な関数／コマンドレットの規約、パラメーターの設計／検証、エラー処理のセマンティクス、オブジェクトのパイプライン動作、状態／スコープ／厳格性、互換性／移植性、テスト容易性を評価する
• 指摘事項の形式に準拠：すべての指摘事項に findings-list §5.1 で必須とされるすべての要素を含め、カテゴリを language-powershell とする
• ファイルと行番号の参照：すべての指摘事項で、行番号を含む具体的なファイル位置を参照する
• PowerShell 以外のコードを除外：明示的に対象に含まれていない限り、PowerShell 固有のルールについて PowerShell 以外のファイルを分析しない

プロセス品質チェック

• PowerShell 言語／ランタイムの観点のみをレビューしましたか（スコープ／セキュリティ／アーキテクチャの分析は行わず）？
• 該当する場合に、関数／パラメーターの規約、エラー処理、パイプラインの動作、互換性、テスト容易性を網羅していますか？
• すべての指摘事項に findings-list §5.1 で必須とされるすべての要素が含まれ、category=language-powershell となっていますか？
• 問題を file:line 形式で参照していますか？

受け入れテスト

出力には、セキュリティ、アーキテクチャ、スコープの分析を行わずに、該当するすべての言語／ランタイムの観点を網羅し、file:line 形式の参照を含む、PowerShell に特化した指摘事項の一覧が含まれていますか？

---

例

例 1：パイプライン契約の不一致

• 入力：関数はパイプライン入力に対応するとしていますが、ValueFromPipeline を宣言せず、end で配列全体のみを処理します。
• 期待される結果：パイプライン契約の不一致について指摘事項を出し、パラメーター属性と process の使用を提案します。カテゴリ = language-powershell。

例 2：エラー処理

• 入力：スクリプトはリスクのあるコマンドを try/catch で囲んでいますが、-ErrorAction Stop を設定していないため、非終端エラーが catch を迂回します。
• 期待される結果：効果のないエラー処理について指摘事項を出し、明示的に終端エラーとして扱う方法を提案します。カテゴリ = language-powershell。

エッジケース：ホストへの出力によるデータ出力の汚染

• 入力：関数はオブジェクトを返しますが、処理ループ内で Write-Host も使用しています。
• 期待される結果：表示用の出力とデータ出力の混在により、自動化と合成可能性が損なわれることを指摘事項として出し、診断には Write-Verbose／Write-Information を使用し、パイプラインの利用側にはクリーンなオブジェクトを出力するよう提案します。