ops-nuke-cicd

NUKE CI/CD

クイックリファレンス

• リポジトリに既存の NUKE Build.cs ターゲットを起点とし、リファクタリングの前に出力の契約を維持します。
• ターゲットグラフの意図を明確にします。必須の前提条件には DependsOn、順序制御には After、複合フローには Triggers、実行時のゲートには OnlyWhenDynamic を使用します。
• リポジトリで使用するテストプラットフォームを1つ選び、CI とローカル実行で統一します。VSTest または Microsoft.Testing.Platform を使用してください。
• このスキルはパイプラインのオーケストレーションとビルド契約に使用し、アプリケーションサービスのリファクタリングや NUnit フィクスチャの内部構造には使用しません。
• 高速なローカルフィードバック（build + filtered tests）と、完全な CI 検証（unit + api + db + merged coverage）を分けます。
• 高コストなターゲットを実行する前に、SDK バージョン、Docker の利用可否（必要な場合）、想定するファイルパスを事前確認します。
• 直接 dotnet test を実行する際に出力ルートを分離する必要がある場合は、--artifacts-path を優先します。
• 各テストカテゴリに1つのターゲットと1つのフィルターを割り当てます。カテゴリ名は1か所（たとえば定数クラス）にまとめ、すべて同じ命名スタイルを使用し、ユニットテストのターゲットではユニットテスト以外のすべてのカテゴリを除外します。
• ビルド、すべてのカテゴリ別ターゲット、カバレッジのマージをまとめる CI ターゲットを1つ（たとえば TestAll）用意します。従来のテストオーケストレーション経路を置き換える場合は、そのターゲットと環境設定を削除し、休眠状態のまま残さないでください。
• ファイルロックや MSBuild マニフェストのエラーを防ぐため、同じジョブ内で同じプロジェクトの出力パスに対して dotnet test を並列実行しないでください。
• Docker を利用するテストインフラストラクチャには、動的なホストポート予約を使用します。localhost のポートをハードコードしないでください。
• CI では Testcontainers API または DOCKER_HOST から Docker ホストを解決します。コンテナーへの接続に localhost が使えると決めつけないでください。
• 新しいテストスイートは、機能の提供時に正規のパイプラインエントリーポイントへ組み込み、後続のクリーンアップに先送りしないでください。
• zsh で安全に動作するシェルコマンドを使用します。シェルコマンドで引用符のない glob を避け、sed/cat/ls の前にパスを検証します。
• カバレッジとテスト成果物を決定論的に出力します（coverage.cobertura.xml、HTML サマリー、JUnit XML）。
• リポジトリでカスタムのパッケージングや堅牢化が必要な場合は Dockerfile を使用し、よりシンプルな SDK ネイティブのイメージには /t:PublishContainer を検討します。
• /t:PublishContainer を使用する場合は、ContainerFamily にベースイメージと一致する Chiseled コンテナーファミリーを設定します。非 root（UID 1654）とポート 8080 は .NET 8 以降のデフォルトです。ポート 80 と決めつけないでください。
• NUKE の issue #1584 では、Microsoft.Testing.Platform に対する DotNetTest のサポートを追跡しています。回避策を選ぶ前に、issue と現在のヘルパー API を確認してください。MTP モードでは、--logger やデータコレクターなど VSTest 固有のオプションは適用されません。.NET 10 では、VSTest が引き続き dotnet test のデフォルトモードです。ランナーの引数を選ぶ前に、global.json、インストール済み SDK でサポートされるランナーのオーバーライド、プロジェクトの SDK 設定を確認してください。.NET 10 をターゲットにするだけでは MTP は選択されません。NUKE ヘルパーがまだ MTP をサポートしていない場合は、ProcessTasks.StartProcess 経由でランナーを呼び出してください。
• SBOM は NUKE の主要ターゲットとして生成します（sbom-tool または CycloneDX .NET）。NuGet／コンテナー成果物には actions/attest-build-provenance でアテステーションを付与し、CI では packages.lock.json をコミットして RestoreLockedMode=true で復元します。
• NuGet 署名検証は .NET 8 SDK 以降でデフォルトで有効です。生成した .nupkg 成果物の事前確認ゲートとして dotnet nuget verify を実行します。
• ダイジェストで固定したイメージ参照を deploy.env または CI ネイティブの出力に公開し、構造化されたダイジェスト出力を優先します。対応している場合は、来歴情報／SBOM も出力します。
• IsLocalBuild はパフォーマンスと出力パスに関する用途に限って使用し、正確性の制御には使用しません。
• 作業の対象がサービスの実装詳細に移った場合は、$software-csharp-backend に切り替えてください。
• 作業の対象がフィクスチャの設計、WireMock／Testcontainers のセットアップ、またはテストの不安定化を防ぐ構成に移った場合は、$qa-testing-nunit に切り替えてください。

このスキルを使用しないケース

• リポジトリで NUKE を使用していない場合（通常の MSBuild ターゲット、Cake、PowerShell／Bash のみのパイプライン、またはビルド自動化レイヤーのない CI ネイティブのワークフローなど）。このスキルのターゲットグラフ、DotNetTasks、NUKE の慣用パターンに関するガイダンスは適用できないため、代わりに $ops-devops-platform を使用してください。
• 質問が「既存の NUKE パイプラインをどう修正／拡張するか」ではなく、「そもそも NUKE を採用すべきか」である場合。これはビルドツール（NUKE、Cake、生の MSBuild、CI ネイティブ YAML）の選定に関する判断であり、このスキルのトラブルシューティングの対象外です。
• NUKE の GitHub Actions パイプラインの生成機能（nuke.build/docs/cicd/github-actions/）を使用してワークフロー YAML 自体をひな形から作成している場合。これは NUKE CLI から一度だけ実行するジェネレーターであり、ターゲットグラフの設計に関する問題ではありません。生成された YAML はレビューの出発点として扱い、このスキルのターゲットグラフツールで実行時の動作をデバッグしないでください。
• 実際の失敗原因が NUnit のフィクスチャーロジック、WireMock のスタブ設定、またはテストの不安定さの根本原因調査にある場合。パイプライン／ターゲットの問題として扱わず、$qa-testing-nunit に引き継いでください。

MTP 移行の判断フレームワーク

NUKE パイプライン内で MTP への移行を推奨する前に、NUKE の issue #1584 とインストール済みヘルパー API を確認してください。そのうえで、次の点を検討します。

• VSTest を継続するのは、VSTest のカバレッジ／ロガーツールがリポジトリのニーズを満たし、テストフレームワークがアダプターをサポートしている場合です。xUnit v3 は xunit.runner.visualstudio を介して VSTest をサポートするため、v3 へのアップグレードだけで MTP への移行が必要になるわけではありません。
• 選択したフレームワークが MTP を必要とする場合（たとえば TUnit）、または測定済みのメリットによって正当化できる場合に移行します。インストール済みの NUKE ヘルパーがまだ MTP をサポートしていない場合は、ProcessTasks.StartProcess による回避策を使用し（references/test-platform-modes-and-cli.md を参照）、その制約を記録してください。
• ソリューションの一部だけを移行しないでください。1 回の dotnet test 呼び出し内で一部のプロジェクトを VSTest、ほかを MTP で実行することは、Microsoft 自身のドキュメントで明確にサポートされていません。移行対象はソリューション全体とするか、プロジェクトグループごとに NUKE ターゲットを明示的に分岐させてください。
• 長期間運用するプロジェクトでは、どちらの方針を選ぶ場合も、決定前に #1584 の状況とヘルパーの動作を再確認してください。

ワークフロー

1. ターゲットグラフの順序と実行上の制約をモデル化またはレビューします。 references/nuke-target-graph-design.md を読み込みます。

2. 早期に失敗を検出し、迅速にフィードバックを得られるビルドとテストのループを設計します。 references/build-test-feedback-loop.md を読み込みます。

3. レポートやランナーの引数を変更する前に、リポジトリのテストプラットフォームと CLI モードを確定します。 references/test-platform-modes-and-cli.md を読み込みます。

4. 単体テスト／API／DB／コンポーネントの分離に向けて、テストカテゴリのフィルターを定義し、検証します。 references/test-categories-and-filters.md を読み込みます。

5. マージと公開用の出力を含め、カバレッジとテストレポートを実装します。 references/coverage-and-reporting.md を読み込みます。

6. タグとダイジェストの取得、およびデプロイ用の出力を含め、Docker のビルドとプッシュを実装します。 references/docker-build-push-patterns.md を読み込みます。

7. 安定したアーティファクトの契約と、CI／プロバイダー向け出力のエクスポートを徹底します。 references/ci-output-contracts-and-provenance.md を読み込みます。

8. パイプラインの不具合を隠さずに、ローカルと CI の動作を調整します。 references/local-vs-ci-behavior.md を読み込みます。

9. CI のインシデント対応に備えて、信頼性、ログ、診断を強化します。 references/pipeline-reliability-and-observability.md を読み込みます。

10. 最終実行の前に、コマンドの衛生チェックと環境の事前確認を実施します。 references/execution-preflight-and-command-hygiene.md を読み込みます。

11. 最終決定の前に、アンチパターンのレビューを実施します。 references/nuke-pipeline-antipatterns.md を読み込みます。

12. 各パイプラインの主張を、対応する段階で検証します。ターゲットの選択は実行計画またはターゲットログで、コマンドの実行は終了コードとテスト／ビルド出力で、後続処理での利用はコレクターまたはデプロイジョブが正確なアーティファクトパス、ダイジェスト、エクスポートされた変数を読み取ることで確認します。Build.cs のコンパイルや DependsOn の確認で証明できるのは、グラフの構文だけです。Docker、認証情報、または CI プロバイダーを利用できない場合は、未実行の段階として報告し、残っている正確な正規ターゲットを明記します。

症状 → リファレンス

症状	主なリファレンス	追加のリファレンス
ローカルではテストが通るが、CI では失敗する	references/local-vs-ci-behavior.md	references/execution-preflight-and-command-hygiene.md
Docker を使用するテストがローカルでは通るが、CI では失敗する	references/local-vs-ci-behavior.md	references/execution-preflight-and-command-hygiene.md
パイプラインまたはフィードバックループが遅い、不安定、または停止する	references/nuke-target-graph-design.md	references/build-test-feedback-loop.md
実行されるテストが多すぎる、または少なすぎる	references/test-categories-and-filters.md	references/nuke-target-graph-design.md
カバレッジまたは JUnit アーティファクトが欠落または不完全	references/coverage-and-reporting.md	references/ci-output-contracts-and-provenance.md
ターゲットの順序が予期せず変わる、またはターゲットがスキップされる	references/nuke-target-graph-design.md	references/nuke-pipeline-antipatterns.md
.NET 10／MTP への移行後に dotnet test の引数が機能しない、またはランナーの動作が混在している疑いがある	references/test-platform-modes-and-cli.md	references/coverage-and-reporting.md
ダイジェストが欠落している、または変更可能なイメージタグがデプロイに使われる	references/docker-build-push-patterns.md	references/ci-output-contracts-and-provenance.md
後続ジョブがアーティファクトまたは deploy.env を読み取れない	references/ci-output-contracts-and-provenance.md	references/local-vs-ci-behavior.md
CI ログから障害を診断しにくい	references/pipeline-reliability-and-observability.md	references/execution-preflight-and-command-hygiene.md
シェルの引用符、グロブ、またはファイル欠落に関するエラー	references/execution-preflight-and-command-hygiene.md	—
新しいテストスイートが CI で実行されない	references/nuke-target-graph-design.md	references/nuke-pipeline-antipatterns.md
リファクタリング中にパイプラインの品質が低下する	references/nuke-pipeline-antipatterns.md	references/build-test-feedback-loop.md

ナビゲーション

• NUKE ターゲットグラフ設計
• ビルドとテストのフィードバックループ
• テストプラットフォームのモードと CLI
• テストカテゴリとフィルター
• カバレッジとレポート
• Docker のビルドとプッシュのパターン
• CI 出力の契約とプロベナンス
• ローカルと CI の動作
• パイプラインの信頼性と可観測性
• 実行前の確認とコマンドの衛生管理
• NUKE パイプラインのアンチパターン
• スキルの参照元：このスキル向けに厳選された、NUKE、.NET、コンテナー、CI の公式リファレンスです。

アセット

アセット	使用する場面
NUKE ターゲットテンプレート：ビルドとテスト	ビルド、カテゴリ別テスト、複合テストの各ターゲットを、単一のカテゴリリスト、フィルター、カバレッジ収集とともにひな形作成またはリファクタリングする際の出発点として使用します。ターゲット名とカテゴリ名は例示です。
NUKE ターゲットテンプレート：Docker のビルド、プッシュ、ダイジェスト	デプロイ参照を出力する Docker イメージのビルド、タグ付け、プッシュ、ダイジェスト取得のターゲットを実装する際の出発点として使用します。
テスト結果とカバレッジの公開チェックリスト	カバレッジまたはテストレポートに関する変更を確定する前に使用し、すべての出力パス、フォーマット、CI コレクターの設定が同期されていることを確認します。
CI トラブルシューティングチェックリスト	CI の失敗が発生している際に使用し、ターゲットグラフ、テストプラットフォーム、Docker、アーティファクト、詳細度の診断を順に進めます。
PR パイプライン品質チェックリスト	PR レビュー時に使用し、ターゲットグラフ、テストプラットフォーム、カバレッジ、Docker、プロベナンス、アーティファクトの契約が保たれていることを確認します。

学びのループ

過去の決定や落とし穴が関係する場合は、learnings.consolidated.md があれば参照します。必要な履歴を確認するとき、または利用できる代替資料としてのみ learnings.md を使用します。それ以外の場合は、どちらも参照しません。

適用後、記憶に値するパターン、再発防止に値する誤り、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付入りの箇条書きを learnings.md に1つ追記します。SKILL.md 自体は変更しないでください。