production-parity-skill-builder

本番環境との同等性スキルビルダー

1 つのアプリケーション向けのスキルを構築します。生成されるスキルは、ローカル環境と非本番環境の動作を本番環境に合わせつつ、意図的な差異をすべて明示し、テストすることを目的とします。

アイデア提供：GitHub ユーザー @dm。

本番環境を参照契約とします。ローカル、CI、PR、プレビュー、ステージングでは軽量なインフラを使用してもかまいませんが、本番環境の動作をエミュレートするか、差異を補うテストを用意して、その差異を文書化する必要があります。本番環境では authentik のグループ制限があるのに、ローカル環境では存在しない場合、それは無害な利便性ではなく、同等性の不具合です。

ワークフロー

1. 質問する前に調査する

まず、リポジトリから根拠を集めます。ファイルから把握できることをユーザーに説明させないでください。

必要に応じて、次を調査します。

• ドキュメント：README*、docs/、ADR、運用手順書、オンボーディング、ローカル環境のセットアップ、デプロイに関するメモ
• アプリケーションコード：設定の読み込み、認証／認可、テナント管理、機能フラグ、サービスクライアント、スケジュールされたジョブ、Webhook
• テスト：単体、統合、E2E、スモーク、コントラクト、認証フィクスチャ、シードデータ、ファクトリー
• ローカル環境のセットアップ：Dockerfile、Compose ファイル、devcontainer、スクリプト、シーダー、Makefile、パッケージスクリプト
• CI とプレビュー：GitHub Actions、GitLab CI、Buildkite、プレビュー環境のデプロイ設定、テストマトリクス
• インフラ：Terraform、Pulumi、CDK、Helm、Kustomize、Kubernetes マニフェスト、Cloudflare／Vercel／Netlify／Fly／Render の設定
• 本番環境の記述：環境変数スキーマ、シークレット名、IdP／OIDC／SAML の設定、イングレス、ネットワークポリシー、ランタイムバージョン、データベース拡張機能、キュー、オブジェクトストレージ、cron、外部プロバイダーの設定

rg --files と対象を絞った rg 検索を使います。環境名と、同等性に影響する用語を検索します。

prod|production|staging|preview|pr|local|dev|ci|docker|compose|k8s|helm|terraform|pulumi|auth|oidc|saml|jwt|group|role|claim|permission|feature flag|secret|env|webhook|cron|queue|seed|fixture|migration

2. 同等性マップを作成する

生成するスキルを書く前に、作業用の同等性マップを作成します。各対象について、次を記録します。

• 本番環境の真実を示す情報源：ファイル、マニフェスト、ドキュメント、ダッシュボードのエクスポート、またはユーザーの回答
• 非本番環境での表現：ローカル、CI、PR／プレビュー、ステージング
• 差異のリスク：異なった場合に変わる、ユーザーに見える動作やセキュリティ動作
• 現在のガード：テスト、スキーマチェック、スモークテスト、コントラクトテスト、ポリシーチェック、またはなし
• 修正パターン：エミュレート、シード、コントラクトテスト、設定の検証、インフラの解析、または明示的な差異の文書化
• リポジトリから判断できない場合の担当者またはエスカレーション先

対象やチェック項目を選ぶ際は、resources/parity-surface-catalog.md を読み込みます。カタログはチェックリストとして使い、すべてのアプリケーションにすべての対象が必要だとは見なさないでください。

3. 対象を絞って質問する

ハーネスで利用可能な質問機能がある場合は、それを使います。たとえば AskUserQuestion、request_user_input、ask_question、または現在のエージェントハーネスにおける同等の機能です。構造化された質問ツールがない場合は、簡潔なテキストで質問します。

調査した後にのみ質問します。生成するスキルや必要な修正に影響する質問だけをします。

質問のルール：

• 2 つの選択肢が密接に関連している場合を除き、一度に 1 つの判断を質問します。
• 回答の選択肢が明確な場合は、構造化された選択肢を優先します。
• 質問のきっかけとなった根拠を示します。
• 最も安全な選択肢を最初に推奨しつつ、トレードオフも明示します。
• 各回答を生成するスキルに反映します。判断をチャット内だけに残さないでください。

再利用可能な質問の形式については、resources/question-patterns.md を読み込みます。

エミュレーター、ローカルサービス、ホスト型サンドボックス、テストツールの選択肢を比較する前に、同等性マップを作成します。リポジトリの根拠だけでは重大な選択肢を決定できない場合は、既知の同等性契約と制約を evaluate-existing-solutions に渡して判断させます。ツールの調査によって本番環境との忠実性の定義を決めさせないでください。

例：

Production appears to require authentik group `app-users` for login, but local and PR setup seed no equivalent restriction.
How should non-production enforce this?

1. Mirror production with seeded IdP group membership. Recommended: catches auth drift while keeping local deterministic.
2. Use a lightweight OIDC/authentik emulator with the same required claim. Good when running real authentik locally is too heavy.
3. Keep local unrestricted, but add contract/E2E tests that fail unless prod-only group enforcement is represented. Faster local login, higher residual drift risk.

4. アプリ固有のスキルを生成する

特定のアプリ用の新しいスキルを作成します。通常は <app-name>-production-parity という名前になりますが、ユーザーやリポジトリの命名規則が別の名前を示唆している場合はそれに従います。

生成したスキルは、対象アプリケーションのリポジトリに直接保存してください。生成したアプリ固有のスキルを、~/.agents/skills、~/.codex/skills、~/.claude/skills、$CODEX_HOME/skills などのユーザー/グローバルフォルダに作成しないでください。

アプリのリポジトリを調査して、プロジェクトローカルの配置場所を選択します:

• アプリにすでにプロジェクトローカルのスキルディレクトリがある場合は、その規則に従います。
• リポジトリが Claude のプロジェクト設定を使用している場合は、.claude/skills/<app-name>-production-parity/SKILL.md を優先します。
• リポジトリが Codex のプロジェクト設定を使用している場合は、.codex/skills/<app-name>-production-parity/SKILL.md を優先します。
• プロジェクトローカルのスキル規則が存在しない場合は、新しい規則を作成する前に、簡潔なハーネスへの質問を 1 つ行います。
• 利用可能なスキルディレクトリがグローバル/ユーザーフォルダのみの場合は、それらを使用せず、プロジェクトリポジトリ内のどこにスキルを置くべきかを質問します。

生成するスキルには以下を含める必要があります:

• そのアプリのパリティ、ドリフト、ローカル/本番の不一致、認証/設定/インフラの差異、および環境セットアップでトリガーされる description を持つ frontmatter
• 本番を参照基準として明示し、意図的な非本番の乖離を列挙する「App Parity Contract」
• 正確なファイルパス、マニフェスト、ドキュメント、コマンド、またはユーザーが確認したソースを含む「Production Truth Sources」
• リポジトリ固有のコマンドと読み取るべきファイルを含む「Inspection Workflow」
• 汎用的なチェックリストの寄せ集めではなく、そのアプリに合わせた「Parity Surfaces」
• エージェントが実行すべき具体的なテスト、スクリプト、スキーマ、または手動チェックを含む「Drift Checks」
• このアプリのアーキテクチャにおいてドリフトを解消する方法を説明する「Fix Patterns」
• ソースからは答えられない決定について、エージェントにアクティブなハーネスの質問機能を使用するよう指示する「Question Protocol」
• 今後のすべての実行に対する「Output Contract」: 検査したファイル、発見したリスク、実施した修正、実行したテスト、残っている明示的な乖離

resources/generated-skill-template.md から始めますが、無関係なセクションを削除し、プレースホルダーをアプリ固有の根拠に置き換えます。

5. セーフガードを明示する。承認された場合にのみ追加する

生成するスキルには、対象アプリが必要とする範囲を絞ったチェックを記載する必要があります:

• 設定パリティ: 必須の環境変数と本番専用の制限に対するスキーマ検証
• 認証パリティ: 必須の IdP グループ、ロール、クレーム、リダイレクト URI、Cookie、セッションポリシーに対するテスト
• フィクスチャパリティ: シードされたユーザー、テナント、フィーチャーフラグ、ロール、プラン、クォータ、データライフサイクル状態
• インフラパリティ: セキュリティに関連する設定について、デプロイメントマニフェストをローカル/プレビューのマニフェストと解析または差分比較する
• プロバイダーパリティ: 外部 API、Webhook、メール、ストレージ、キュー、決済プロバイダーに対するコントラクトテストまたは記録済みフィクスチャ
• ランタイムパリティ: 言語ランタイム、データベース、拡張機能、イメージタグ、ビルドコマンドのバージョン固定
• スモークパリティ: マージ前に、アプリが本番相当の制限で起動することを証明するプレビュー/ステージングのスモークテスト

差異が意図的な場合は、明示された理由と補償的なガードを必須とします。「ローカルのほうが簡単だから」では十分ではありません。

これらのチェックをアプリのコード、テスト、設定、フィクスチャ、またはインフラに実装するのは、ユーザーがパリティ修正を明示的に依頼した場合、またはギャップを確認した後に追加の変更を承認した場合のみです。再利用可能なスキルの作成だけを求める依頼は、スキル成果物のみを承認するものであり、無関係なアプリやインフラの変更を承認するものではありません。それ以外の場合は、正確なガード契約と推奨される配置場所を生成されたスキル/出力に記載し、対象アプリには手を付けないでください。

6. 生成されたスキルを検証する

完了する前に：

1. 新しいスレッドで呼び出された場合を想定して、生成されたスキルを読み直します。
2. アプリ固有のすべての主張が、リポジトリのソースまたは記録されたユーザーの回答を引用していることを確認します。
3. そのアプリに該当しない限り、汎用的なチェックリスト項目が残っていないことを確認します。
4. 生成されたスキルのパスが対象アプリのリポジトリ内にあり、ユーザー/グローバルのスキルフォルダー内にないことを確認します。
5. ハーネスまたはリポジトリにスキル検証コマンドが存在する場合は、それを実行します。
6. 検証を実行できない場合は、その理由を正確に説明します。

出力

以下を返します：

• 生成されたスキルのパス
• 生成されたスキルが対象プロジェクトのリポジトリ内に保存されていることの確認
• 検査したファイルとディレクトリ
• 作成中に見つかった最もリスクの高いパリティのギャップ
• 尋ねた質問と記録された決定事項
• 実行したテストまたは検証
• ドリフトが見つかったが修正されなかった場合に推奨される次の修正

汎用的なパリティレポートを最終成果物として提示しないでください。主要な成果物は、再利用可能なアプリ固有のスキルです。