Matrix Builds Skill

GitHub Actions のマトリックスビルド戦略による効率的な並列実行パターン。

ディレクトリ構造

.claude/skills/matrix-builds/
├── SKILL.md                          # このファイル（概要とクイックリファレンス）
├── resources/
│   ├── matrix-strategy.md           # strategy.matrix構文詳細
│   └── dynamic-matrix.md            # 動的マトリックス生成
├── templates/
│   └── matrix-template.yaml         # マトリックス設定テンプレート
└── scripts/
    └── generate-matrix.mjs          # マトリックス設定ジェネレーター

コマンドリファレンス

リソース参照

# マトリックス戦略詳細（基本構文、include/exclude、制御オプション）
cat .claude/skills/matrix-builds/resources/matrix-strategy.md

# 動的マトリックス生成（fromJSON、出力ベースマトリックス）
cat .claude/skills/matrix-builds/resources/dynamic-matrix.md

テンプレート使用

# マトリックス設定テンプレート
cat .claude/skills/matrix-builds/templates/matrix-template.yaml

スクリプト実行

# マトリックス設定生成
node .claude/skills/matrix-builds/scripts/generate-matrix.mjs --os "ubuntu,windows,macos" --node "18,20,22"

基本マトリックスパターン

1. シンプルマトリックス

jobs:
  test:
    strategy:
      matrix:
        node-version: [18, 20, 22]
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}

結果: 9 個のジョブ（3 OS × 3 Node.js） = 並列実行

2. include/exclude パターン

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    node: [18, 20]
    include:
      # 特定の組み合わせに追加設定
      - os: ubuntu-latest
        node: 22
        experimental: true
    exclude:
      # Windows + Node 18は除外
      - os: windows-latest
        node: 18

結果: 5 ジョブ（2×2 - 1 除外 + 1 追加）

3. fail-fast 制御

strategy:
  fail-fast: false # 1つ失敗しても全て実行
  matrix:
    node: [18, 20, 22]

用途: 全バージョンのテスト結果を取得したい場合

4. max-parallel 制限

strategy:
  max-parallel: 2 # 同時実行2ジョブまで
  matrix:
    region: [us-east-1, us-west-2, eu-west-1, ap-northeast-1]

用途: API 制限やリソース節約

5. 動的マトリックス（fromJSON）

jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: echo "matrix={\"node\":[18,20,22]}" >> $GITHUB_OUTPUT

  test:
    needs: setup
    strategy:
      matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
    runs-on: ubuntu-latest

用途: 変更ファイルに基づく動的テスト選択

マトリックス変数アクセス

基本アクセス

steps:
  - name: マトリックス値を表示
    run: |
      echo "OS: ${{ matrix.os }}"
      echo "Node: ${{ matrix.node-version }}"
      echo "Experimental: ${{ matrix.experimental || 'false' }}"

条件分岐

steps:
  - name: Windows専用ステップ
    if: matrix.os == 'windows-latest'
    run: choco install some-package

  - name: 実験的ビルド専用
    if: matrix.experimental == true
    run: pnpm run test:experimental

ベストプラクティス

1. マトリックス次元の選択

推奨: 2-3 次元まで（OS × Version × Feature） 理由: 組み合わせ爆発を防ぐ（3×3×3 = 27 ジョブ）

2. fail-fast 戦略

• 開発中: fail-fast: false（全結果確認）
• 本番 CI: fail-fast: true（高速フィードバック）

3. max-parallel 調整

• 無制限: GitHub 無料プラン（20 並列）
• 制限: 外部 API やリソース制約がある場合

4. キャッシュとの組み合わせ

strategy:
  matrix:
    node: [18, 20, 22]
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}
      cache: "pnpm" # マトリックス別にキャッシュ

関連スキル

使用タイミング

✅ このスキルを使う場合:

• 複数の OS/バージョン/環境でテストが必要
• クロスプラットフォーム互換性検証
• 並列実行による高速化が必要

❌ 不要な場合:

• 単一環境のみのテスト
• 順次実行が必須のジョブ
• 極めてシンプルな CI/CD

詳細情報: resources/ディレクトリ参照 テンプレート: templates/matrix-template.yaml ツール: scripts/generate-matrix.mjs