azure-pipelines-generator

Azure Pipelines ジェネレーター

決定性のある手順、明示的なフォールバック、明確な完了条件を備えた、本番環境で利用できる Azure DevOps パイプライン YAML を生成します。

トリガーのガイダンス

ユーザーが Azure Pipelines YAML の生成または再設計を依頼した場合に、このスキルを使用します。たとえば、次のような依頼です。

• 「Node サービス用の azure-pipelines.yml を作成してください。」
• 「ステージングと本番環境を含む、複数ステージの Azure DevOps パイプラインを構築してください。」
• 「リポジトリ間で再利用できる Azure パイプラインのテンプレートを生成してください。」
• 「この CI フローを Azure Pipelines に変換してください。」

検証のみの依頼には、このスキルを使用しないでください。検証のみの場合は、azure-pipelines-validator を使用してください。

実行モデル

規範的なキーワード：

• MUST：必須
• SHOULD：ユーザーから別の指定がない限り、デフォルトとします
• MAY：任意

決定性のある手順：

1. 依頼のモードを分類します。
2. 必要最小限の入力を収集します。
3. 必要最小限のリファレンスを読み込みます（段階的開示）。
4. 品質チェックリストに従って YAML を生成します。
5. 検証します（バリデータースキル、スクリプトによるフォールバック、または手動でのフォールバック）。
6. 指定されたレポート形式で出力を返します。

環境の制約により手順を実行できない場合は、その手順のフォールバックを使用して続行してください。

1) 依頼のモードを分類する

主要なモードを1つだけ選択します。

• Basic CI： 1つのスタックを対象としたビルド／テスト／リンティング。
• Multi-stage CI/CD： 環境の追跡を含むビルド -> テスト -> デプロイ。
• Docker： イメージのビルド／プッシュと、任意のデプロイ。
• Kubernetes： イメージのビルド／プッシュと Kubernetes へのデプロイ。
• Language-specific： .NET、Node.js、Python、Go、Java に特化。
• Template-based： 再利用可能なテンプレートと、シンプルなルートパイプライン。
• Snippet-only： パイプライン全体ではなく、部分的な YAML を依頼された場合。

モードと例の対応：

• Basic CI -> examples/basic-ci.yml
• Multi-stage CI/CD -> examples/multi-stage-cicd.yml
• .NET -> examples/dotnet-cicd.yml
• Python -> examples/python-cicd.yml
• Go -> examples/go-cicd.yml
• Kubernetes -> examples/kubernetes-deploy.yml
• Template-based -> examples/template-usage.yml + examples/templates/*.yml

2) 必要な入力を収集する

生成の前に、次の情報を収集します。

• アプリのスタックとパッケージマネージャー
• ビルド／テストコマンドとレポートの要件
• デプロイ先（なし、Azure サービス、Docker レジストリ、Kubernetes）
• 環境のフロー（dev/staging/prod）とブランチのゲート
• サービス接続、変数グループ、シークレットの扱い
• テンプレートの要否（はい／いいえ）

情報が不足している場合の安全なデフォルト：

• CI ブランチ：main、develop
• 本番環境へのデプロイブランチ：main のみ
• エージェントイメージ：固定イメージ（例：ubuntu-22.04）
• デプロイ用イメージタグ：不変の値（$(Build.BuildId)）。latest はデプロイしないでください

重要な情報が不足している場合は、最終出力で前提を明示します。

3) リファレンスを読み込む（段階的開示）

まず、ローカルのリファレンスを読み込みます。

必ず読み込むもの：

• docs/yaml-schema.md
• docs/best-practices.md

条件に応じて読み込むもの：

• タスク／入力項目を選択する場合は docs/tasks-reference.md
• Template-based モードの場合のみ docs/templates-guide.md

続いて、上記のモードと例の対応から、最も近い例のみを読み込みます。

リファレンスが見つからない場合の動作：

• 例が見つからない場合：最も近いモードの例を使用し、置き換えたことを記載します。
• ドキュメントのセクションが見つからない場合：既知の規約に従って続行し、不確実な点を明記します。
• Snippet-only の依頼の場合：安全な出力に必要な最小限の内容のみを読み込みます。

最終回答には、必ず次の項目を含めます。

• References used
• References skipped or missing
• Impact

4) 外部ドキュメントへのエスカレーション（必要な場合のみ）

次の場合に限り、ローカルドキュメント以外の情報を確認します。

• 必要なタスク情報がローカルドキュメントにない
• タスクのバージョン互換性が不明確
• タスク固有の障害をトラブルシューティングする

次の順序で確認します。

1. Context7（mcp__context7__resolve-library-id -> mcp__context7__query-docs）
2. 公式ドキュメントの検索（まず Microsoft Learn）

ネットワークやツールを利用できない場合は、把握しているローカルのガイダンスに基づいて続行し、残存リスクについて記載します。

5) パイプライン生成チェックリスト

ユーザーが限定的なスニペットを求めている場合を除き、以下のすべての項目を適用してください。

セキュリティ：

• シークレットをハードコードしないでください。
• サービス接続と変数グループ／シークレットを使用してください。
• 不変のデプロイイメージタグを使用してください。

バージョン管理：

• vmImage は *-latest ではなく、明示的なバージョンに固定してください。
• タスクのメジャーバージョン（Task@N）を固定してください。
• @0 が許可されるのは、そのタスクのメジャーバージョンが 0 の場合のみです。

信頼性：

• 明示的な dependsOn を使用してください。
• 長時間実行されるジョブには timeoutInMinutes を追加してください。
• ブランチで制御するデプロイ condition ルールを使用してください。
• デプロイステージには environment を指定したデプロイジョブを使用してください。

パフォーマンス：

• 依存関係のインストール時間を短縮できる場合は Cache@2 を使用してください。
• 完全な履歴が不要な場合は、浅いチェックアウトを使用してください。
• 必要なアーティファクトのみを発行してください。

テスト／可観測性：

• CI で lint／テストを実行してください。
• condition: succeededOrFailed() を指定してテスト結果を発行してください。
• 利用可能な場合はカバレッジを発行してください。

保守性：

• ステージ／ジョブ／重要なステップに displayName を追加してください。
• ロジックが繰り返される場合はテンプレートを使用してください。
• 一見して明らかでないロジックにのみ、短いコメントを追加してください。

6) 検証ワークフロー

デフォルトの手順（完全なパイプライン生成では必須）：

1. YAML を生成または更新します。
2. azure-pipelines-validator で検証します。
3. 指摘事項を修正します。
4. ブロッキングの問題がなくなるまで検証を再実行します。

バリデータースキルが利用できないものの、ローカルのバリデータースクリプトがある場合のスクリプトによる代替手順：

bash devops-skills-plugin/skills/azure-pipelines-validator/scripts/validate_azure_pipelines.sh <pipeline-file>

スキルもスクリプトも実行できない場合の手動による代替手順：

1. YAML の構造／インデントの妥当性
2. 階層の妥当性（stages -> jobs -> steps）
3. タスク形式の妥当性（Task@Major）
4. シークレット露出のスキャン（平文の認証情報／トークンがないこと）
5. デプロイの安全性のスキャン（環境の使用、不変のデプロイタグ）

代替手順を使用した場合、最終回答には必ず以下を含めてください。

• Validation status: Manual fallback
• Checks performed
• Residual risk

検証を省略できるのは、以下の場合に限ります。

• スニペットのみの YAML
• ドキュメントのみのサンプル
• 検証を省略するようユーザーから明示的に要求された場合

7) 出力要件

最終回答には必ず以下を含めてください。

1. パイプライン YAML（またはテンプレート一式）
2. 必要なセットアップ：
   • サービス接続
   • 変数グループ／シークレット
   • 環境および承認／チェック
3. 検証結果：
   • バリデーターのステータス、スクリプトのステータス、または手動による代替手順のステータス
4. 前提事項
5. 使用／省略した参照資料とその影響
6. 任意の次の改善事項

8) 標準的な例のフロー

例 A：完全なマルチステージ生成

1. モードを選択します：マルチステージ CI/CD。
2. 技術スタック／デプロイ／サービス接続に関する入力を確認します。
3. docs/yaml-schema.md、docs/best-practices.md、examples/multi-stage-cicd.yml を読みます。
4. 要求されたカスタマイズ（ステージ、ブランチゲート、環境、タスク）を追加します。
5. azure-pipelines-validator で検証し、修正して再実行します。
6. YAML + セットアップ + 検証 + 前提事項 + 参照資料を返します。

例 B：簡易スニペット生成

1. モードを選択します：スニペットのみ。
2. 必要最小限の参照セクションのみを読みます。
3. 安全なデフォルト値を使って、目的を絞った YAML スニペットを生成します。
4. 完全な検証を省略し、Validation status: Skipped (snippet-only) と記載します。
5. スニペット + 前提事項 + 参照資料を返します。

9) 完了の定義

適用されるすべてのチェックに合格した場合にのみ、実行は完了です。

• リクエストモードが明示的に選択されている。
• 入力が不足している場合の前提事項が明示されている。
• YAML がチェックリストの要件（セキュリティ、バージョン管理、信頼性、パフォーマンス、保守性）に従っている。
• 検証手順（バリデーター、スクリプトによる代替手順、または手動による代替手順）が記録されている。
• 最終回答が、参照資料とその影響を含め、出力要件に従っている。