powershell-module-architect

PowerShell モジュールアーキテクト

目的

構造化され、再利用可能で、保守しやすい PowerShell モジュールの作成に特化した、PowerShell モジュールの設計とアーキテクチャに関する専門知識を提供します。エンタープライズ PowerShell 環境におけるモジュールアーキテクチャ、関数設計、バージョン間の互換性、プロファイルの最適化に重点を置いています。

使用する場面

• 散在するスクリプトを構造化された再利用可能なモジュールに変換する
• パブリック関数とプライベート関数を分離したモジュールアーキテクチャを設計する
• バージョン間で互換性のあるモジュールを作成する（PowerShell 5.1 および 7 以降）
• 読み込み時間を短縮するために PowerShell プロファイルを最適化する
• 適切なパラメーター検証を備えた高度な関数を作成する

クイックスタート

次の場合にこのスキルを呼び出します：

• 散在するスクリプトを構造化された再利用可能なモジュールに変換する
• パブリック関数とプライベート関数を分離したモジュールアーキテクチャを設計する
• バージョン間で互換性のあるモジュールを作成する（PowerShell 5.1 および 7 以降）
• 読み込み時間を短縮するために PowerShell プロファイルを最適化する
• 適切なパラメーター検証を備えた高度な関数を作成する

次の場合は呼び出さないでください：

• 再利用しない単発の簡単なスクリプトを作成する場合（powershell-5.1-expert または powershell-7-expert を使用してください）
• すでに構造化されたモジュールに機能を追加する場合（関連するドメインスキルを使用してください）
• UI を開発する場合（powershell-ui-architect を使用してください）
• セキュリティを強化する場合（powershell-security-hardening を使用してください）

判断の指針

モジュールを作成するタイミング

シナリオ	推奨事項
関連する関数が 3 個以上ある	モジュールを作成する
チーム間での共有が必要	モジュールとマニフェストを作成する
1 回限りの自動化	スクリプトのままにする
パラメーターセットが複雑	モジュール内に高度な関数を作成する
バージョン互換性が必要	互換性レイヤーを備えたモジュールを作成する

モジュール構成の判断

Script Organization Need
│
├─ Few related functions (3-10)?
│  └─ Single .psm1 with inline functions
│
├─ Many functions (10+)?
│  └─ Dot-source pattern (Public/Private folders)
│
├─ Publishing to gallery?
│  └─ Full manifest + tests + docs
│
└─ Team collaboration?
   └─ Git repo + CI/CD + Pester tests

コアワークフロー：スクリプトをモジュールに変換する

使用例： 散在する 10～50 個の .ps1 スクリプトを、整理されたモジュールにリファクタリングする

ステップ 1：分析

# Inventory existing scripts
$scripts = Get-ChildItem -Path ./scripts -Filter *.ps1 -Recurse

# Analyze function signatures
foreach ($script in $scripts) {
    $content = Get-Content $script.FullName -Raw
    $functions = [regex]::Matches($content, 'function\s+(\S+)')
    
    Write-Host "$($script.Name): $($functions.Count) functions"
}

# Expected output:
# AD-UserManagement.ps1: 12 functions
# AD-GroupManagement.ps1: 8 functions
# Common-Helpers.ps1: 15 functions (candidates for Private/)

ステップ 2：モジュール構成を設計する

# Create module skeleton
$moduleName = "Organization.ActiveDirectory"
$modulePath = "./modules/$moduleName"

New-Item -Path "$modulePath/Public" -ItemType Directory -Force
New-Item -Path "$modulePath/Private" -ItemType Directory -Force
New-Item -Path "$modulePath/Tests" -ItemType Directory -Force
New-Item -Path "$modulePath/$moduleName.psm1" -ItemType File -Force
New-Item -Path "$modulePath/$moduleName.psd1" -ItemType File -Force

ステップ 3：関数を分類する

Public functions (exported to users):
  ├─ Get-OrgADUser
  ├─ New-OrgADUser
  ├─ Set-OrgADUser
  ├─ Remove-OrgADUser
  └─ ... (user-facing functions)

Private functions (internal helpers):
  ├─ _ValidateDomainConnection
  ├─ _BuildDistinguishedName
  ├─ _ConvertToCanonicalName
  └─ ... (utility functions)

ステップ 4：モジュールファイルを実装する

# Organization.ActiveDirectory.psm1

# Dot-source Private functions first
$Private = @(Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Private) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import private function $($import.FullName): $_"
    }
}

# Dot-source Public functions
$Public = @(Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue)
foreach ($import in $Public) {
    try {
        . $import.FullName
    } catch {
        Write-Error "Failed to import public function $($import.FullName): $_"
    }
}

# Export Public functions explicitly
Export-ModuleMember -Function $Public.BaseName

ステップ 5：モジュールマニフェストを作成する

# Generate manifest
$manifestParams = @{
    Path              = "$modulePath/$moduleName.psd1"
    RootModule        = "$moduleName.psm1"
    ModuleVersion     = '1.0.0'
    Author            = 'IT Team'
    CompanyName       = 'Organization'
    Description       = 'Active Directory management functions'
    PowerShellVersion = '5.1'  # Minimum version
    FunctionsToExport = @(
        'Get-OrgADUser',
        'New-OrgADUser',
        'Set-OrgADUser',
        'Remove-OrgADUser'
    )
    VariablesToExport = @()
    AliasesToExport   = @()
}
New-ModuleManifest @manifestParams

ステップ 6：Pester テストを追加する

# Tests/Module.Tests.ps1
BeforeAll {
    Import-Module "$PSScriptRoot/../Organization.ActiveDirectory.psd1" -Force
}

Describe "Organization.ActiveDirectory Module" {
    It "Exports expected functions" {
        $commands = Get-Command -Module Organization.ActiveDirectory
        $commands.Count | Should -BeGreaterThan 0
    }
    
    It "Has valid module manifest" {
        $manifest = Test-ModuleManifest -Path "$PSScriptRoot/../Organization.ActiveDirectory.psd1"
        $manifest.Version | Should -Be '1.0.0'
    }
}

Describe "Get-OrgADUser" {
    It "Accepts Identity parameter" {
        { Get-OrgADUser -Identity "testuser" -WhatIf } | Should -Not -Throw
    }
}

クイックリファレンス：高度な関数のテンプレート

function Get-OrgUser {
    <#
    .SYNOPSIS
        Retrieves Active Directory user by name.
    
    .DESCRIPTION
        Queries Active Directory for user object and returns detailed properties.
    
    .PARAMETER Name
        The username or SamAccountName to search for.
    
    .EXAMPLE
        Get-OrgUser -Name "jdoe"
        
        Returns all properties for user jdoe.
    
    .EXAMPLE
        "jdoe", "asmith" | Get-OrgUser
        
        Retrieves multiple users via pipeline.
    #>
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$Name
    )
    
    process {
        Get-ADUser -Identity $Name -Properties *
    }
}

連携パターン

powershell-5.1-expert

• 引き継ぎ：モジュールアーキテクチャの設計後、5.1 エキスパートが Windows 固有の関数を実装します
• 連携：PowerShell 5.1 との互換性を考慮したモジュール構成の判断

powershell-7-expert

• 引き継ぎ：モジュール構成の定義後、7 エキスパートが最新構文による最適化を追加します
• 連携：バージョン検出を使用したデュアルモード関数

windows-infra-admin

• 引き継ぎ：モジュールアーキテクチャの設計後、Windows 管理者がドメイン固有のロジックを実装します
• 共同責任：Active Directory、GPO、DNS のモジュール関数

azure-infra-engineer

• 引き継ぎ：モジュールのパターンを基に、Azure エンジニアがクラウド自動化モジュールを構築します
• 連携：オンプレミスと Azure を組み合わせたクロスクラウドモジュール

注意が必要な兆候 — エスカレーションが必要な場合

状況	対応
1 つのモジュールに 100 個以上の関数がある	サブモジュールへの分割を検討する
バージョン間の互換性の問題が複雑	powershell-5.1 および 7 のエキスパートに相談する
プロファイルの読み込みが 1 秒未満のパフォーマンス	遅延読み込みパターンを適用する
セキュリティ上重要な操作	powershell-security-hardening を参加させる

追加リソース

• 詳細な技術リファレンス：REFERENCE.md を参照してください

  • プロファイル最適化のワークフロー
  • モジュールマニフェストのテンプレート
  • 動的パラメーターのパターン

• コード例とパターン：EXAMPLES.md を参照してください

  • アンチパターン（一枚岩のファイル、ヘルプの欠如）
  • バージョン間の互換性パターン
  • 高度なパラメーター検証