テスト時の必須行動

フロントエンドコードをテストする際のAIエージェントの必須行動。

5つのコアルール

フロントエンドコードに取り組むすべてのAIエージェントは、テスト時にこの5つのルールに従う必要があります：

ルール1: 最初にテスト計画を宣言する

テストを書いたり検証を実行したりする前に、以下を明示します：

• 何をテストするか

• どのレベルを使用するか

• なぜそのレベルが適切か

Test plan:
- Testing: notification banner visibility after CSS fix
- Level: 5 (verify-ui + screenshot)
- Reason: This is a visual bug — the element exists in DOM but
  user reports it's not visible. Need to check computed styles.

ルール2: テストレベルを目標に合わせる

テストレベルは実際に検証しているものと一致しなければなりません：

レベル5の問題にレベル1を使用しないでください。テストはパスしますが、バグは残ります。L4が難しいだけ、L5が扱いにくいだけでレベル6に飛ばないでください — L6は下位の両方のレベル（L4とL5）が真に実行不可能な場合にのみ正当化されます。

ルール3: 下位レベルがパスしても問題が解消しない場合はエスカレーションする

テストがパスしたにもかかわらず、ユーザーが問題が修正されていないと言う場合：

1. 同じテストを再実行しない

2. ユーザーにキャッシュのクリアを提案しない

3. 次のテストレベルにエスカレーションする

4. すでにレベル4の場合、レベル5にエスカレーションする

5. レベル5の場合、より深く調査する（祖先要素、スタッキングコンテキストなどをチェック）

6. レベル6（AIベース）には、L4が書けないかつL5がアサーションに届かない場合のみエスカレーションする。L6はレベル5の次のデフォルトのステップではない — 決定論的なチェックが不可能なcanvas／フォトエディタ系のサーフェスのために確保されています。

ルール4: UI/CSSはデフォルトでレベル5

以下に関わるタスク：

• CSSの変更

• レイアウトの変更

• 表示の問題

• 視覚的な外観

• レスポンシブデザイン

• 間隔、色、フォント

はレベル5の検証をデフォルトにすべきです。下位レベルはCSSの正しさを検証する構造的能力がありません。

ルール5: テストしなかったものを報告する

テスト後、ブラインドスポットを明示的に述べます：

Verification complete:
- Tested: computed styles confirm banner has display:block,
  opacity:1, and parent has overflow:visible
- Screenshot: banner is visible at top of page
- NOT tested: responsive behavior at mobile breakpoints
- NOT tested: animation transition timing

この透明性により、追加のテストが必要かどうかをユーザーが判断できます。

4つの実行ルール

階層化されたテストスイートの中で動作するエージェントは、さらにこの4つのルールに従う必要があります。検証アーティファクト、ティアタグ、および昇格ライフサイクルの背景については、実行ティアを参照してください。

ルール6 — 検証テストは自己昇格しない

エージェントが作成した検証スペックには @verification タグを付け、すべてのゲートから除外します。ティアへの昇格は明示的で意図的なステップです：

1. @verification タグを削除する

2. 適切なティアタグを割り当てる（例：@heavy、@gpu）

3. 対象スイートの時間予算内に収まることを確認する

エージェントは自分の検証テストを自己昇格させません。PRの説明で昇格を提案し、決定はレビュアーに委ねます。

# PR description excerpt
## Verification spec — graduation proposal
- spec: tests/banner-render.spec.ts
- currently: @verification (excluded from gates)
- proposed tier: T1 (untagged CI-safe e2e)
- rationale: stable for 5 runs, sub-2s, no platform dependency
- action needed: reviewer removes @verification tag and assigns tier

ルール7 — 赤いチェックは作者をブロックする

自分が作成したPRにある赤いチェックは、リポジトリ設定で必須チェックとして指定されているかどうかに関わらず、あなたをブロックします。唯一の例外：失敗したテストに、リンクされたオープンなissueを伴う @flaky タグがある場合。

# Blocked — do not merge
PR #42 authored by agent-session-A
  ✗  unit: auth-service.test.ts — 1 failed
     (not a required check, but authored by this session)
  → investigate and fix before declaring done

# Not blocked — exception applies
  ✗  e2e: flaky-animation.spec.ts @flaky — see issue #38
     (quarantined; allowed-to-fail in scheduled tier)
  → merge may proceed; issue #38 tracks the fix

ルール7はエージェント／規約のレイヤーであり、ブランチルールセットは機械／強制のレイヤーです -- どちらも互いの代替にはなりません（ゲートを宣言ではなく強制にするを参照）。

ルール7があなたを拘束するのは、赤いPRの作者としてです。逆の役割 — あなたがマージゲートを運用していて、redが自分の所有していないテストのものである場合 — には、専用の手続きがあります：ゲートオペレーターのプレイブック。

ルール8 — ゲートを不正操作しない

以下のいずれも、リンクされたオープンなissueの参照なしに導入してはなりません：

• 既存のテストへの test.skip

• 以前はパスしていたテストへの @flaky タグ

• スクリーンショット許容値の緩和（例：ピクセル閾値の引き上げ）

• アサーションの削除

既存のアサーションを編集してゲートをパスさせる場合、テスト差分についてフレッシュコンテキストのレビューが必要です — 元の変更を作成したのと同じセッションで編集を適用してはなりません。

この要件はアサーションだけでなく、ゲートを定義するファイルにも及びます。 ゲートは、アサーションに一切手を触れずに無力化できます：失敗しているスペックが動かなくなるように testMatch パターンを狭める、--grep-invert フィルタを追加する、リトライ回数を引き上げる、CIジョブを削除または必須指定から外す、失敗するシナリオがそもそもビルドされないようにフィクスチャ／セットアップスクリプトを編集する、などです。リトライ予算、grepフィルタ、testMatchパターン、ジョブの配線がこのようにゲートを無力化しうるため、ゲートを定義するファイル（テストランナー設定、CIワークフロー定義、フィクスチャ／セットアップスクリプト、pre-pushゲートスクリプト）への編集にも同じフレッシュコンテキストのレビューが必要です — 作者のdiff要約を鵜呑みにせず、ゲートファイルを最初から読み直し、元の変更を作成したのと同じセッションで編集を適用してはなりません。

プロジェクトは、テスト戦略ドキュメントに具体的なゲートファイルの一覧を列挙すべきです（例：ランナー設定、フィクスチャセットアップスクリプト、両方のCIワークフローファイル、pre-pushスクリプト）。

# Wrong — no issue reference
test.skip('banner renders correctly', () => { ... })

# Wrong — no issue reference
expect(page).toHaveScreenshot({ maxDiffPixels: 500 }) // was 50

# Wrong — gate-defining file edited to make a gate pass, no fresh-context review
testMatch: ['**/*.spec.ts', '!**/banner-*.spec.ts'] // silently excludes failing spec

# Right (a) — legitimate skip: a real, deliberate skip, not a flake
// skipped: https://github.com/your-org/your-app/issues/55 — pending backend flag rollout
test.skip('banner renders correctly', () => { ... })

# Right (b) — quarantine: NOT skipped; the test still runs, allowed-to-fail,
# with @flaky in the title, exactly matching the quarantine pipeline's convention
// quarantined: https://github.com/your-org/your-app/issues/55
test('banner renders correctly @flaky', () => { ... })

ルール9 — スコープを絞った重い検証

変更がヘビーレーンテスト（@heavy、@gpu、@interactive、または @macos-only タグの付いたもの）のみでカバーされているコードに触れる場合、作業完了を宣言する前に、関連するヘビースペックを対応可能なホスト上で実行してください。あるいは、ブランチに対してexamワークフローをディスパッチしてください。

どのテストがヘビーレーンとみなされるか、またどのホストが必要かを特定する方法については、ヘビーテスト判断ルールを参照してください。

# Before declaring done — change touches GPU rendering path
$ gh workflow run exam.yml --ref my-feature-branch
# or, if running locally on a capable host:
$ pnpm exec playwright test --grep "@gpu" tests/gpu-render.spec.ts

サマリーチェックリスト

修正完了を宣言する前に：

• テスト前にテスト計画を宣言した

• テストレベルが変更の性質と一致している

• テストがパスしたがユーザーが失敗を報告した場合、次のレベルにエスカレーションした

• CSS/ビジュアルの変更にはレベル5を使用した

• テストしたものとしなかったものを報告した

• 新しい検証スペックには @verification タグが付いており、自己昇格していない

• 自分のPRの赤いチェックはすべて解決済み、またはリンクされたissueを伴う @flaky タグがある

• test.skip、@flaky、または許容値の緩和はリンクされたissueなしに導入していない

• 変更がヘビーレーン専用のコードに触れる場合、対応可能なホスト上で関連するヘビースペックを実行した