sdd-verify

サーフェスに応じた検証

単体テストでは、コードがテストの記述どおりに動作することを証明します。このスキルでは、変更が実行中のアプリで機能することを検証します。変更が実際に影響する箇所に合った検証方法を選びます。

1. サーフェスを検出する（差分から）

変更内容を確認するために git diff を調べます。

• フロントエンド：レンダリングされる UI に関わる場合。対象には .tsx/.jsx/.vue/.svelte/.html/.css/.scss、コンポーネントやページ／ルートのディレクトリ、デザイントークン、Storybook などがあります。
• API／バックエンド：リクエストハンドラー、ルート、コントローラー、リゾルバー、OpenAPI／Swagger の仕様、シリアライザー、Lambda ハンドラーに関わる場合。
• 変更が両方に関わることもあります。その場合は両方のサーフェスを検証します。

どちらのサーフェスにも該当しない場合（ライブラリ／ツール／ドキュメントのみ）は、その旨を伝えて終了します。操作対象がないため、単体テストの最低限の検証がゲートのすべてです。

2. フロントエンド → chrome-devtools MCP

chrome-devtools-mcp プラグインが必要です（ToolSearch でツールを読み込みます：+chrome navigate）。

1. 開発サーバーを起動するか、稼働中であることを確認します。プロジェクトの実行／開発用スクリプトを確認してください。ポートを決めつけてはいけません。
2. navigate_page で対象のルートに移動します。
3. take_screenshot を実行し、デザインがレンダリングされること（レイアウト、変更したコンポーネント、明らかな不具合がないこと）を確認します。参照デザインがある場合は、それと比較します。
4. list_console_messages を実行し、新たなエラーがないことを確認します。list_network_requests を実行し、そのビューで失敗した呼び出しがないことを確認します。必要に応じて、対象ページのアクセシビリティ／Lighthouse チェックを実行します。
5. 結果を報告します。レンダリング ✓／✗、コンソールに問題なし ✓／✗、ネットワークに問題なし ✓／✗ を、証拠となるスクリーンショットとともに示します。

3. API → Playwright のリクエストスクリプト

Playwright が必要です（キットインストーラーで確認できます。ない場合は pnpm add -D @playwright/test）。

1. 差分と OpenAPI の変更内容から、影響を受けるエンドポイント（メソッド＋パス）を特定します。

2. Playwright の request コンテキストを使用して、scripts-dev/ の下に一時的なスクリプト（例：api_smoke.spec.ts）を作成します。ブラウザーは使用しません。

   import { test, expect, request } from '@playwright/test'
   test('affected endpoint', async () => {
     const api = await request.newContext({ baseURL: process.env.BASE_API_URL })
     const res = await api.get('/the/affected/path')      // or .post(...) with a body
     expect(res.status()).toBe(200)
     expect(await res.json()).toMatchObject({ /* the shape the delta spec promises */ })
   })
   

3. このシェル自体の認証情報／環境変数を使って実行します（ロールを偽装したり、IAM 権限を拡大したりしないでください）。 npx playwright test scripts-dev/api_smoke.spec.ts

4. エンドポイントごとにステータスコードとデータ形状のアサーションを報告します。スクリプトはリポジトリの慣例に従って残すか削除します。

フロー内での実行タイミング

ハーネスの検証フェーズでは、決定的な最低限の検証（単体テスト＋openspec --strict）が実行されます。ブラウザーや API の操作は自動では行いません。変更を実装した後、または PR を承認する前に、このスキルを自分で実行するか、エージェントに実行させて、実行中のサーフェスが実際に機能することを確認してください。ハーネスが特定の技術スタックに依存しない状態を保てるよう、これは自動ゲートではなくスキルとして提供されています。

ルール

• 実際のサーフェスを操作してください。単体テストが通ることと、「ページがレンダリングされる」ことや「エンドポイントが約束したデータ形状を返す」ことは同じではありません。
• チェックを通すために認証情報／IAM 権限を拡大してはいけません。セッション自体の環境を使用してください。
• 一時的な API スクリプトは scripts-dev/ の下に置きます。スクリプトにシークレットをコミットしてはいけません。