test-ui

Codex 互換性に関する注意：

• Codex でリポジトリのスキルを呼び出すには、$skill-name を使用します。このミラー版では、従来の Claude の /skill-name 参照を置き換えています。
• タスクトラッカーの必須事項：ワークフローまたはスキルの手順を実行する前に、すべての手順についてタスクの追跡情報を作成または更新し、進捗の変化に合わせて同期してください。
• ユーザーへの質問を促すプロンプトは、Codex でユーザーに直接質問することを意味します。
• Claude 固有のモード切り替え指示がある場合は無視してください。
• 厳格な実行規約：ユーザーがスキルを明示的に呼び出した場合は、記載どおりにそのスキルのプロトコルを実行してください。
• サブエージェントの承認：スキルがユーザーによって呼び出された場合、または AI によって検出された場合に、そのプロトコルでサブエージェントが必要とされるなら、そのスキルの有効化により、そのタスクで必要な spawn_agent サブエージェントを使用することが承認されます。
• ユーザーが事前に逸脱を明示的に承認しない限り、プロトコルの手順を省略、並べ替え、統合しないでください。
• ワークフロースキルでは、列挙された子スキルの各手順を明示的に実行し、手順ごとに根拠を示してください。
• 必須の手順またはツールをこの環境で実行できない場合は、対応方法を変更する前に停止し、ユーザーに確認してください。

Codex のプロジェクト参照の読み込み（フックなし）

Codex では、実行時にプロジェクト文書を注入する代わりに、静的なプロジェクト参照を読み込みます。 コーディング、計画、デバッグ、テスト、レビューを行う際は、以下の経路に従ってプロジェクト文書を明示的に開いてください。

必ず読むもの：

• docs/project-config.json（プロジェクト固有のパス、コマンド、モジュール、ワークフローとテストの設定）
• docs/project-reference/docs-index-reference.md（docs/project-reference/* カタログ全体への案内）
• docs/project-reference/lessons.md（常時適用されるガードレールとアンチパターン）

コンテキストがない、または古い場合の経路： docs/project-config.json、ドキュメントのインデックス、lessons.md、CLAUDE.md、AGENTS.md、またはタスクに必要な参照文書が存在しないか古い場合は、プロジェクト固有の通常作業を始める前に、$project-init または限定的なセットアップ経路（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）を自動的に実行してください。Codex のミラーまたは AGENTS.md が存在しないか古い場合は、ユーザーに $sync-codex の実行を依頼してください。自動実行はしないでください。

状況に応じて読む文書：

• プロジェクトの構造／アーキテクチャ／技術スタック／デプロイ／セットアップ（バックエンド、フロントエンド、インフラのいずれの層でも）：project-structure-reference.md
• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様書の作成、docs/specs/ のパス指定、または TC 形式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 振る舞い／公開契約の変更、または仕様書・テスト・コード間の同期：workflow-spec-test-code-cycle-reference.md と上記の仕様書関連文書
• 派生仕様インデックス／ERD／再実装ガイド：spec-system-reference.md および docs/specs/ 内の元となる Feature Specs
• 統合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査：code-review-rules.md と、変更対象のファイルに応じたドメイン文書

すべての文書を無差別に読まないでください。まず docs-index-reference.md を確認し、そこからタスクに関連するファイルだけを開いてください。

クイックサマリー

目的： ウェブサイトで包括的な UI テストを実施し、詳細なビジュアルレポートを生成します。

Playwright スクリプトを使用して個々のページやコンポーネントをテストする場合は、代わりに webapp-testing を使用してください。

ワークフロー：

1. 検出 — 対象の URL を開き、すべてのページ、コンポーネント、エンドポイントを見つけます
2. テスト計画 — アクセシビリティ、レスポンシブ対応、パフォーマンス、セキュリティ、SEO を網羅するテスト計画を作成します。レスポンシブ対応では、小画面の最小幅の基準として約 320px を必ず確認します。UI が使いやすい状態を保ち、何も壊れていないことを確認します。コンテンツやコントロールが切れたり、画面外に隠れて到達できなくなったりしてはいけません。リフローする代わりにスクロールするブロック（overflow: auto）は許容され、失敗ではありません。コンテンツが切れたり、スクロール手段がないままコントロールが画面外に隠れたりするブロックは失敗です。
3. 実行 — テスターのサブエージェントを並列で実行し、各テスト領域のスクリーンショットを撮影します
4. 分析 — ビジュアル分析ツールを使って、スクリーンショットと視覚要素を確認します
5. レポート — スクリーンショットを埋め込み、推奨事項を記載した Markdown レポートを生成します

主なルール：

• テストとレポート作成のみを行い、修正は実装しないでください（これはテスト／レポート作成用のスキルです）
• すべてのスクリーンショットをレポートディレクトリに保存します
• Cookie／トークン／localStorage の注入により、認証が必要なルートに対応します

懐疑的な姿勢を保ち、批判的思考と順序立てた思考を適用してください。すべての主張には追跡可能な証拠と信頼度をパーセンテージで示してください（Idea は 80％を超える必要があります）。

事前確認（デザインシステム）： docs/project-config.json から designSystem.canonicalDoc と tokenFiles を読み込み、見た目やスタイルに関する検証で推測ではなく実際のトークン名（--brand-*、$brand-*）を参照してください。

ブラウザー自動化ツールを有効にしてください。

目的

ウェブサイトで包括的な UI テストを実施し、詳細なレポートを生成します。

引数

• $1：URL — テストするウェブサイトの URL
• $2：OPTIONS — 任意のテスト設定（例：--headless、--mobile、--auth）

保護されたルートのテスト（認証）

認証が必要な保護されたルートをテストする場合は、次のワークフローに従ってください。

ステップ 1：ユーザーによる手動ログイン

ユーザーに次の操作を依頼してください。

1. ブラウザーで対象サイトを開く
2. 認証情報を使って手動でログインする
3. ブラウザーの DevTools（F12）を開き、Application タブ → Cookies/Storage を選択する

ステップ 2：認証情報の抽出

次のいずれかを提供するようユーザーに依頼してください。

• Cookie：Cookie の値（name、value、domain）をコピーする
• アクセストークン：localStorage または Cookie から JWT／Bearer トークンをコピーする
• セッションストレージ：関連するセッションキーをコピーする

ステップ 3：認証の注入

利用可能なブラウザー自動化ランナーを使って、テストの前に認証情報を注入します。

# Cookies
# Add cookies before navigating to protected pages.

# Bearer token
# Set the Authorization header or localStorage token key before navigation.

# Local/session storage
# Populate the required storage keys, then reload the page.

ステップ 4：テストの実行

認証を注入すると、ブラウザーセッションが維持されます。利用可能なブラウザー自動化ランナーを使って、通常どおりテストを実行します。

# Navigate and screenshot protected pages.
# Save outputs in the report directory for later analysis.

認証スクリプトのオプション

• --cookies '<json>' - Cookie を注入します（JSON 配列）
• --token '<token>' - Bearer トークンを注入します
• --token-key '<key>' - トークンの localStorage キー（デフォルト：access_token）
• --header '<name>' - トークンを含む HTTP ヘッダーを設定します（例：Authorization）
• --local-storage '<json>' - localStorage 項目を注入します
• --session-storage '<json>' - sessionStorage 項目を注入します
• --reload true - 注入後にページを再読み込みします
• --clear true - 保存された認証セッションを消去します

ワークフロー

• plan スキルを使用して、現在のプロジェクトディレクトリにテスト計画とレポートを整理します。
• すべてのスクリーンショットを同じレポートディレクトリに保存します。
• 指定された $OPTIONS を使用して $URL を閲覧し、すべてのページ、コンポーネント、エンドポイントを調査します。
• 調査した構成に基づいてテスト計画を作成します。
• 複数の tester サブエージェントまたはツール呼び出しを並行して使用し、すべてのページ、フォーム、ナビゲーション、ユーザーフロー、アクセシビリティ、機能、ユーザビリティ、レスポンシブレイアウト、クロスブラウザー互換性、パフォーマンス、セキュリティ、SEO などをテストします。
• visual analysis tooling を使用して、すべてのスクリーンショットと視覚要素を分析します。
• すべてのスクリーンショットをレポートに直接埋め込み、包括的なレポートを Markdown 形式で生成します。
• 最後に、調査結果と推奨事項を簡潔にまとめてユーザーに回答します。
• レポートを /preview スラッシュコマンドでプレビューするかどうか、ask the user directly ツールを使ってユーザーに尋ねます。

UI/UX デザイン原則 — 実行時に観察可能な評価

SYNC:ui-ux-design-principles の40項目（本文はこのスキル内にすべて記載）は、ここでは REVIEW の役割で適用し、ライブブラウザーセッションで観察できる内容に限定します。9つの観点を個別に評価します。実行中のサイトに対して一度に1つの観点ずつ、9つすべてを同時にまとめて確認することは避けてください。 それぞれの Think: プロンプトに原則から答えた後、ブラウザーを操作して、その判断を検証または反証します。

このスキルの対象外 — レポートでその旨を明記し、推測しないでください。 ソースコードまたはデザイントークンシステムの確認によってのみ判断できる項目は $ui-review の対象であり、スクリーンショットから判断せず、そちらに回します。対象は UI-1.2（シグナルの順序）、UI-2.1（ファミリー／ウェイトの一覧）、UI-2.5（6段階固定の文字サイズスケール）、UI-3.2（アクセントカラーを1つに絞り、用途も1つにする）、UI-4.1～UI-4.3（基本スペーシング単位、gap とマージンの使い分け、内側と外側のパディング）、UI-6.3（ユーザーの用語と内部命名の違い）、UI-7.1（各フィールドが引き続き必要かどうか）です。

指摘ごとの証拠： UI-<clause> と実行時の特定情報（URL／ルート・ビューポートサイズ・スクリーンショットのパス）を記載します。その項目で測定値が指定されている場合は、その測定値（計算済みコントラスト比、ヒットボックスの px、レイアウトシフト、応答 ms、1行あたりの文字数、アニメーション ms）も記載し、監査で該当ソースを特定できる場合は file:line も記載します。数値が指定された項目は、測定した数値がある場合にのみ満たされたと判断できます。「問題なしそう」といった主観的な評価で済ませてはいけません。

重大度： このスキルでは重大度の段階を定義せず、今回の評価でも新たに定義しません。既存のレポート構成（主要な指摘と推奨事項）に従い、ユーザーへの影響が大きい順に記録します。この監査結果を $ui-review に渡す場合は、マージの判断において同スキルの BLOCKED／WARN／PASS の基準に従います。

#	ディメンション（実行時に観察できる条項）	考える：
1	視覚的階層と状態の網羅性 — UI-1.1、UI-1.3～UI-1.5	最初の描画時、目が最初に向かう要素はどれですか？ また、それはページの目的に沿った要素ですか？ グループは余白と枠線のどちらで区切られていますか？ 各画面を EMPTY、LOADING、ERROR の状態にして、何が表示されるか確認してください。
2	表示されるタイポグラフィ — UI-2.2～UI-2.4	計算後の本文サイズ（Web では 16px、モバイルでは 17px、14px 未満にはしない）、各テスト幅での 1 行あたりの文字数（45～75）、行の高さの比率（本文は 1.5、ディスプレイは 1.1～1.2）を測定してください。
3	表示される色とコントラスト — UI-3.1、UI-3.3、UI-3.4	表示されるすべてのテキストと UI の境界の組み合わせについて、コントラスト比（4.5:1／3:1）を計算してください。スクリーンショットを目視で判断せず、必ず測定してください。色だけで伝えられているステータスはありませんか？ ダークモードに切り替えたとき、浮き上がった面になりますか、それとも反転しますか？
4	レスポンシブのブレークポイント — UI-4.4	各テスト幅で、レイアウトが機能しなくなるのはどこですか？ ブレークポイントはその位置にありますか、それともデバイス名に基づいていますか？ (テスト計画にある約 320px の最小基準は、引き続き合否を決定します。UI-4.4 では、ブレークポイントをどこに置くべきかを確認します。)
5	インタラクションとフィードバック — UI-5.1～UI-5.5	各コントロールを押すと、100ms 以内に何が変わりますか？ 5 つの状態（デフォルト／ホバー／フォーカス／アクティブ／無効）をすべて確認し、スタイルが適用されていない状態はありませんか？ Tab キーで移動し、フォーカスリングが見えるか確認してください。トランジションの時間（150～250ms、イーズアウト）を計測し、動きを減らす設定を有効にして再度実行してください。取り消しで済む場面で、確認を求めていませんか？
6	ナビゲーションと IA — UI-6.1、UI-6.2、UI-6.4	各ルートに直接アクセスしたとき、自分がどこにいるのか、ここに何があるのか、次にどこへ進めばよいのかが分かりますか？ 最上位の遷移先はいくつありますか（最大 5 つ）。状態をディープリンクで開いて戻るボタンを押したとき、適切な場所に戻りますか？
7	フォームと入力 — UI-7.2～UI-7.5	各フィールドに入力すると、ラベルは表示されたままですか？ フォーカスを外したとき、修正方法を示すメッセージとともに検証が実行されますか？ モバイルのキーボード／自動補完はデータ型に合っていますか？ エラーを発生させ、別の場所へ移動してから更新したとき、入力済みのデータは保持されますか？
8	モバイルとタッチ — UI-8.1～UI-8.4	タッチ対応のビューポートで、各ターゲットのヒット領域（アイコンではなく）と隣接要素との間隔を測定してください（44x44pt 以上、間隔は 8px）。主要なアクションは親指から見てどこに配置されていますか？ ジェスチャーだけで操作する要素はありませんか？ キーボードを開き、安全領域を確認してください。(マトリックスにタッチ対応ビューポートがない場合は、理由を明記してスキップしてください。)
9	速度と体感速度 — UI-9.1～UI-9.4	接続速度を制限したとき、データより先に構造が表示されますか（スケルトンかスピナーか）？ データ表示時にレイアウトがずれる要素はありませんか？ 楽観的更新が失敗したとき、目に見える形でロールバックされますか？ オフラインにしてタイムアウトを強制したとき、設計された状態が表示されますか、それともハングしますか？
優先順位： 上記のプロジェクトのデザインシステム資料（designSystem.canonicalDoc + tokenFiles）が、以下の条項に優先します。実際に矛盾がある場合は、両方の内容を示してユーザーに確認し、黙って解決してはいけません。サイトに適用できる箇所がない場合に限り、その項目を省略し、省略理由を明記してください。

出力要件

レポートの作成方法：

• 形式：見出し、リスト、適宜コードブロックを使用し、明確で構造化された Markdown にしてください。
• テスト結果の概要、主な調査結果、スクリーンショットへの参照を含めてください。
• 重要： 品質を維持しながら、トークン効率を確保してください。
• 重要： レポートを作成する際は、文法より簡潔さを優先してください。
• 重要： 未解決の質問がある場合は、レポートの末尾に列挙してください。

重要： テストとレポートの作成で止めてください。修正の実装を開始してはいけません。 重要： スキルカタログを分析し、作業中にタスクに必要なスキルを有効化してください。

---

[重要] 作業を始める前に、作業全体を細かいタスクに分割して、タスク追跡を行ってください。各ファイルを読むタスクも含めてください。長いファイルによるコンテキストの喪失を防ぐためです。簡単なタスクの場合、AI は省略してよいかユーザーに必ず確認してください。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関連、サービス間の同期（作業にビジネスエンティティ／モデルが関わる場合に読むこと）

批判的思考の姿勢 — 批判的思考と順序立てた思考を適用してください。すべての主張は追跡可能な証拠に基づき、実行に移す際の確信度は80％を超えている必要があります。 ハルシネーション対策： 推測を事実として示してはいけません。すべての主張に出典を明記し、不確実性は率直に認め、自身の出力に誤りがないか確認し、独立して相互参照し、自身の確信度にも懐疑的でいてください。証拠のない確信は、あらゆるハルシネーションの根本原因です。

証拠に基づく推論 — 推測は禁止です。すべての主張には証拠が必要です。

1. すべての主張について、file:line、grep の結果、またはフレームワークのドキュメントを引用してください。
2. 確信度を明示してください：80％超ならそのまま進め、60～80％なら先に検証し、60％未満なら推奨してはいけません。
3. アーキテクチャの変更には、サービス間の検証が必要です。
4. 「証拠が足りません」は、有効であり、期待される回答です。

以下が完了するまで作業はブロックされます： - [ ] 証拠となるファイルパス（file:line） - [ ] grep 検索の実施 - [ ] 類似パターンを3件以上確認 - [ ] 確信度の明示

証拠なしでは禁止： 「明らかに」、「私はそう思います」、「〜すべきです」、「おそらく」、「これが原因です」 未完了の場合 → 次を出力してください："証拠が不十分です。確認済み：[...]。未確認：[...]。" テスト失敗時の責任判定 — テストが失敗した場合（または失敗のデバッグや修正を行う場合）、どちらに問題があるか、つまり ソースコードかテストコードか を判断することが重要です。スイートをグリーンにすることよりも、正しい判定を下すことのほうが重要です。すべてのデバッグ／修正／テストスキルに同じように適用されます。

1. どちらにも手を加える前に暫定判定を行う。 観察された証拠を SOURCE-WRONG、TEST-WRONG、TEST-NOT-OPTIMAL、ENVIRONMENT-BLOCKED、AMBIGUOUS のいずれかに分類し、その後 $debug-investigate を実行して、編集前に処理を最後から最初へたどります。スイートを再びグリーンにすることは目的ではありません。
2. 仕様とソースの両方に照らして三角測量する。 動作を対象とする Feature Spec（例：docs/specs/** — §3 ACs／§4 BRs／§5 invariants／§8 TCs）がある場合、それを 意図された 動作を判断する際の決め手とし、本番ソースと失敗したテストの両方を仕様と比較します。仕様がない場合は、文書化された意図／受け入れ基準／呼び出し元との契約を基準にします。これらの証拠から、誤っているのがソースかテストかを判断します。
3. どちらに問題があるかを分類し、誤っている側を根本から修正する。
   • SOURCE-WRONG — 本番コードが仕様の意図する動作または明確な不変条件に違反している → 所有するレイヤーでソースを修正し、問題を検出したテストは維持または強化します。
   • TEST-WRONG — テストに古い、または誤ったアサーション、セットアップ、期待値が含まれ、意図する動作と矛盾している → テストを根本から修正します。グリーンにするためにアサーションを弱めたり、スキップを追加したり、タイムアウトを緩和したりしてはいけません。
   • TEST-NOT-OPTIMAL — 意図する動作は妥当だが、テストの接点、タイミング、またはアサーションのシグナルが不安定である → 不変条件を弱めずにテストを改善します。
   • ENVIRONMENT-BLOCKED — インフラストラクチャまたは外部状態がソース／テストの判定を妨げている → 診断情報を保持し、環境が正常になるまで変更を停止します。
   • AMBIGUOUS — 証拠または意図する動作から、どちらが問題の所有者かを安全に判断できない → 編集前にユーザーまたは正式な責任者に確認します。
   • 壊れたソースに合わせてテストを変更してはいけません。また、壊れたテストを満たすためにソースを変更してはいけません。（マイグレーションコードは除きます。スキーマ／データのマイグレーションは一度だけ実行される処理であり、コアアプリケーションロジックではありません。）
4. 意図する動作が不明確な場合はユーザーに確認する。 動作を対象とする仕様がない場合、仕様に記載がない場合、またはどちらが正しいか仕様が曖昧な場合は、編集前に停止してユーザーに直接確認する（または正式な仕様の責任者に相談する）。スイートを通すためだけに、ソースかテストかを黙って選んではいけません。

現在どちらが通るかではなく、意図する動作に合わせます。グリーンが、まさにバグを含んでいることもあります。 AI のミス防止 — どのタスクでも避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直す。 コンテキストの圧縮、作業の再開、長時間にわたる作業によって、記憶が古くなっている可能性があります。作業を進める前に、最新のファイルを確認してください。 生成した内容をソースの根拠と照合する。 AI は API、名称、主張、文書内の事実を幻覚することがあります。文書に記載したり参照したりする前に、該当するソースを確認してください。 削除や名前変更の前に、下流の参照を確認する。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元に古い情報が残ることがあります。まず参照関係を洗い出してください。 編集後は影響範囲全体をたどる。 定義を変更しても、派生した出力や利用側への影響を見落とすことがあります。完了と宣言する前に、影響を受ける経路を最後まで確認してください。 最初の出力だけでなく、影響を受ける出力をすべて確認する。 1 つのチェックが成功しても、すべてのチェックが成功したとは限りません。変更の影響を受ける可能性のある出力先をすべて検証してください。 既存の値は意図的に設定されていると考え、変更または不具合として指摘する前に、理由を確認する。 定数、上限、フラグ、しきい値、文言、パターンを変更または報告する前に、周辺のコンテキストと履歴、呼び出し元における処理順序、同じ規約を使う他の 2 か所以上の呼び出し箇所を確認してください。理由を示さず WHAT（何をするか）だけを記載したドキュメントは、ガードがない証拠ではなく、根拠の説明が不足している状態です。 曖昧さを明らかにしてから行動する。黙って解釈を選ばない。 複数の妥当な解釈がある場合は、明示的に質問するか、リスクを添えて前提を示してください。 インフラが管理する中間状態ではなく、システムが担う結果をアサートする。 非同期処理を検証する際は、最終的なビジネス状態をアサートしてください。共有インフラ内で実行中の他プロセスが書き込む可能性のある、配信や再試行の記録は決してアサートしないでください。このようなチェックは単独実行では成功しますが、同じインフラを他の処理と共有した途端に不安定になります。 共有ガイダンスは、対象となる役割に関連する内容に保つ。 共通ガイダンスは、それを受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の義務は、コード固有のプロトコルにのみ記載してください。 UI/UX デザイン原則（改訂 1.0 — 40 項目、Web ＋ モバイル） — ユーザーインターフェースを設計、計画、実装、レビューするあらゆるタスクに適用する作業ルール集です。特定の項目で指定されていない限り、両方のプラットフォームに適用します（§8 はモバイル／タッチ）。項目は ID で参照します：UI-3.1、UI-8.2。

優先順位： プロジェクトのデザインシステム／SCSS／フロントエンドパターンのドキュメントは、これらの項目より優先されます。これらの項目は一般的な好みより優先されます。実際に矛盾する場合は、双方をユーザーに提示します。黙って解決してはいけません。— 理由：プロジェクト独自の記録済みの決定が判断基準です。何も定められていない場合は、これらの項目がデフォルトとなります。

1.0 視覚的階層とレイアウト

• UI-1.1 1 画面につき、焦点は 1 つにします。最初に見せる要素が 2 つ競合する場合は、どちらかを目立たなくします。
• UI-1.2 視線を誘導する順序：サイズ → ウェイト → 色 → 位置。別の手段を加える前に、最も手軽で有効な手段を使います。
• UI-1.3 枠線ではなく、近接によってグループ化します。余白ならすっきり区切れますが、枠の中に枠を作ってはいけません。
• UI-1.4 共通の端に揃えます。理由の説明できないインデントは、すべてミスに見えます。
• UI-1.5 空、読み込み中、エラーの各状態を最初に設計します。全データが揃った状態を設計するのは簡単です。

2.0 タイポグラフィ

• UI-2.1 書体は最大 2 種類、各書体のウェイトは最大 3 種類にします。種類が増えると、表現の幅ではなく一貫性のなさに見えます。
• UI-2.2 本文の文字サイズは Web で 16px、モバイルで 17px にします。ユーザーが読む必要のある文字を 14px 未満にしてはいけません。
• UI-2.3 1 行の長さは 45～75 文字にします。コンテナーではなく、行幅を制限します。
• UI-2.4 行間は文字サイズに反比例させます：本文は 1.5、ディスプレイ用は 1.1～1.2。
• UI-2.5 エンジニアリングと共有する、名前付きの 6 段階からなる固定の文字サイズスケールを使います。個別の文字サイズを設定してはいけません。

3.0 色とコントラスト

• UI-3.1 コントラスト比はテキストで 4.5:1、UI の境界で 3:1 にします。測定してください。明るい画面で目視判断してはいけません。
• UI-3.2 アクセントカラーは 1 色にし、役割も 1 つにします。あらゆる場所に使われるアクセントカラーは、何も示せません。
• UI-3.3 色だけで意味を伝えてはいけません。アイコン、ラベル、または位置を組み合わせます。
• UI-3.4 ダークモードはライトモードの単純な反転ではありません。面の明度を上げて高さを示し、真っ白なテキストは和らげます。

4.0 余白とグリッド

• UI-4.1 余白の単位は 1 種類にして、倍数で使います。4px または 8px を基準とし、すべての間隔をその倍数にします。
• UI-4.2 余白は子要素ではなくコンテナーに持たせます。gap を使い、マージンは例外に限ります。
• UI-4.3 内側は狭く、グループ間は広くします。内側のパディングは、常に次のグループまでの間隔より小さくします。
• UI-4.4 ブレークポイントはデバイスではなくコンテンツに合わせます。レイアウトが機能しなくなる位置で切り替えます。

5.0 インタラクションとフィードバック

• UI-5.1 結果が出るまで時間がかかる場合でも、すべてのアクションに 100ms 未満で応答します。
• UI-5.2 5 つの状態（デフォルト、ホバー、フォーカス、アクティブ、無効）をすべて指定し、該当する場合は読み込み中の状態も指定します。
• UI-5.3 確認より取り消しを優先します。取り消せない操作に限り、確認を求めます。
• UI-5.4 モーションで原因と結果を明確にします：150～250ms、イーズアウト、視差効果を減らす設定に準拠します。
• UI-5.5 視認できるフォーカスリングを残します。デザインと合わない場合はスタイルを変更しますが、削除してはいけません。

6.0 ナビゲーションと IA

• UI-6.1 すべての画面で、今いる場所、ここにあるもの、次に進む先が分かるようにします。
• UI-6.2 最上位の遷移先は最大 5 つにします。最上位を詰め込むより、階層を深くする方が適切です。
• UI-6.3 内部用語ではなく、ユーザーが使う言葉でラベルを付けます。チーム内の語彙は分類体系ではありません。
• UI-6.4 すべての状態に URL または戻る経路を用意します。ディープリンクとハードウェアの戻る操作で、適切な場所に移動できるようにします。

7.0 フォームと入力

• UI-7.1 質問を減らします。すべてのフィールドについて、今それが必要な理由を説明できるようにします。
• UI-7.2 ラベルは常に表示します。プレースホルダーはヒントであり、ラベルではありません。
• UI-7.3 入力中ではなく、フォーカスが外れたときに検証します。エラーはフィールドの近くに表示し、修正方法を伝えます。
• UI-7.4 データの種類に合わせてキーボードを選びます。すべてのフィールドで、適切な入力タイプ、自動補完、自動大文字化を設定します。
• UI-7.5 入力済みのデータを失わせてはいけません。エラー、画面遷移、更新後も入力内容を保持します。

8.0 モバイルとタッチ (モバイル／タッチの画面)

• UI-8.1 タップ領域は 44×44pt 以上、間隔は 8px にします。タップ領域は、表示されているアイコンより大きくても構いません。
• UI-8.2 主なアクションは画面の下 3 分の 1 に配置します。そこが親指の届く範囲です。
• UI-8.3 ジェスチャーはショートカットとして使い、唯一の操作方法にしてはいけません。スワイプできるものは、タップでも操作できるようにします。
• UI-8.4 セーフエリアとキーボードを考慮します。ノッチ、ホームインジケーター、画面上のキーボードはいずれも表示領域を占有します。

9.0 速度と体感速度

• UI-9.1 データより先に画面の構造を表示します。既知のレイアウトにはスケルトンを使い、待ち時間が不明な場合に限りスピナーを使います。
• UI-9.2 楽観的に成功を仮定します。まず UI を更新し、その後に整合性を確認します。失敗時はロールバックを明示します。
• UI-9.3 読み込みが発生する要素のためにスペースを確保します。画像、広告、フォントによってレイアウトをずらしてはいけません。
• UI-9.4 遅い接続を想定して設計します。オフライン、タイムアウト、再試行は状態であり、例外ではありません。

役割に応じた適用 — 項目はすべて共通ですが、タスクによって適用方法が異なります：

役割	義務
画面を DESIGN / PLAN する	項目を成果物に反映します：空／読み込み中／エラー状態を最初に指定する（UI-1.5）、5 つの状態をすべて列挙する（UI-5.2）、文字サイズスケールと余白の単位を宣言する（UI-2.5、UI-4.1）
コンポーネントを IMPLEMENT する	完了前のチェック項目：状態・トークン・コントラスト・フォーカスリング・タップ領域・確保済みスペース（UI-5.2、UI-2.5／UI-4.1、UI-3.1、UI-5.5、UI-8.1、UI-9.3）
UI コードまたはデザイン成果物を REVIEW する	各項目を不合格の条件とし、すべての指摘に UI-<clause> ＋ file:line ＋ 重大度を記載します。チェックボックスを一通り埋めるだけの確認は禁止します。セクションごとに焦点を絞って確認します。
UI システムを SCAN / 文書化する	プロジェクトが意図的に逸脱している箇所を記録し、優先されるドキュメントが記録上の判断基準となるようにします。

省略できるのは変更にユーザー向けの画面がない場合（バックエンドのみ、ツール、ドキュメント）に限ります。省略を明示し、見落としではなく監査可能な判断として記録します。 重要・必ず注意 すべての主張に対して file:line の根拠を示してください（行動に移すのは確信度が80％を超える場合のみ）。証拠なしに推測してはなりません。

必ず注意 批判的かつ順序立てて考えてください。すべての主張には、適切な追跡可能な根拠（リポジトリ／コードに関する主張は file:line、調査・製品・コンテンツ・ドキュメントに関する主張はソース URL または成果物のセクション）が必要です。行動に移すのは確信度が80％を超える場合のみとし、60％未満の場合は推奨してはなりません。ハルシネーション防止：推測を事実として提示してはなりません。不確実性は率直に認め、独立した情報源と照合し、自分の確信度にも懐疑的でいてください。

必ず注意 AI のミスを防止してください。生成した内容を根拠と照合し、削除や名前変更の前に下流の参照を追跡し、影響を受けるすべての出力を検証し、コンテキストを失った後はファイルを読み直し、行動に移す前に曖昧な点を明示してください。

プロジェクトプロトコルのオーバーレイ — このスキルを実行する前に、重ねて適用される PROJECT オーバーレイのルールを解決してください。プロジェクトのスキルプロトコル索引（既定では docs/project-reference/skill-protocols-reference.md。docs/project-config.json の referenceDocs エントリでパスが上書きされます）の Target 列とこのスキル名を照合し、最も具体的に一致する階層のみを適用します（完全一致 > glob > *）。この優先順位はオーバーレイ同士にのみ適用され、このスキル自体より優先されるものではありません。一致した本文のみを、<protocols-dir>/<Name>.md として解決して読み取ってください。行の Body リンクは表示テキストであり、読み取り先のパスではありません。一致した本文が存在しない、または不正な形式の場合は、その旨を報告してスキップしてください。索引の Description から本文を再構成してはなりません。索引がない、または一致がない場合は、オーバーレイなしで進め、何も通知しません。契約の全文は .claude/skills/project-skill-protocol/references/registry.md にあります。

オーバーレイは追加のみです。つまり、このスキル独自のプロトコルにルールを追加するものであり、既存のルールを置き換えたり、上書きしたり、無効化したり、別の意味に解釈したりしてはなりません。すべてのオーバーレイを取り除いたとき、このスキルは文書化された動作と完全に同じでなければなりません。オーバーレイは簡潔な補足であり、権限を引き上げるものではありません。ワークフローのゲート、Git の規律、レビューのゲート、ユーザー確認のゲートを免除することはできません。オーバーレイとスキルに実際の矛盾がある場合、または同じ具体性のオーバーレイ同士が直接矛盾する場合は、両方をユーザーに提示してください。黙って解決してはなりません。

必ず注意 このスキルを実行する前に、プロジェクトプロトコルのオーバーレイを解決してください。最も具体的に一致する階層のみを適用します（完全一致 > glob > *。この優先順位はオーバーレイ同士にのみ適用され、このスキル自体より優先されるものではありません）。<protocols-dir>/<Name>.md にある一致した本文のみを読み取ってください。本文が存在しない、または不正な形式の場合は報告し、再構成してはなりません。オーバーレイは追加のみであり、このスキル独自のルールを置き換えるものではありません。また、簡潔な補足であり、権限を引き上げるものではありません。同じ具体性のオーバーレイ同士に矛盾がある場合は、ユーザーに提示してください。

• 必ず注意 ユーザー向けの画面には、40 の UI/UX デザイン原則（UI-1.1～UI-9.4）を適用してください。焦点は1つに絞り、関連要素を近接して配置し、空・読み込み中・エラーの各状態を最初に設計します（§1） · フォントファミリーは2種類以下、本文は Web で16px／モバイルで17px、14px未満は禁止、45～75ch、固定の6段階スケール（§2） · テキストのコントラスト比は4.5:1、エッジは3:1を測定し、アクセントカラーは1色に限定し、色だけに頼らず、ダークモードを単純な反転にしません（§3） · 4／8px単位を1つに統一し、マージンより gap を優先し、内側はより狭く、間隔は外側ほど広くし、コンテンツに応じてブレークポイントを設定します（§4） · 応答は100ms未満、5つの状態をすべて用意し、確認より取り消しを優先し、動きを減らす設定を尊重した150～250msのイーズアウトを使い、フォーカスリングを表示します（§5） · 「今どこにいるか／ここには何があるか／次にどこへ進むか」を示し、トップレベルの遷移先は5つ以下にし、ユーザーの言葉を使い、URL または戻る手段を用意します（§6） · 入力欄を減らし、ラベルを常時表示し、フォーカスを外したときに検証し、キーボード操作を適切に対応させ、入力内容を決して失わせません（§7） · ターゲットは44×44pt以上、間隔は8px以上にし、主要な操作は画面下部3分の1に配置し、ジェスチャーだけを唯一の操作経路にせず、安全領域を考慮します（§8） · データより先に構造を表示し、ロールバックが見える楽観的更新を行い、スペースを確保し、低速接続時の状態を用意します（§9）。プロジェクトのデザインシステム文書はこれらの条項より優先されます。実際に矛盾する場合はユーザーに提示し、黙って解決してはなりません。すべての指摘には UI-<clause> と file:line を記載してください。ユーザー向けの画面に変更がない場合に限り、明示したうえで適用を省略できます。

締めくくりの注意事項

重要・必ず注意 — 適用中のプロトコル（このスキルに含まれる SYNC／共有ブロックの簡潔な要約）：

• 批判的思考： 批判的かつ段階的に考え、根拠を追跡し、確信度が80％を超えること。
• 証拠： すべての主張に file:line を引用し、推測は決して行わないこと。
• AI の誤り防止： 生成した内容を証拠と照合し、下流の参照を追跡し、影響を受けるすべての出力を確認し、コンテキスト喪失後は読み直し、曖昧さを明示すること。

重要・必ず注意 作業を始める前に、タスク追跡を使って作業を小さな TODO タスクに分割すること 重要・必ず注意 新しいコードを作成する前に、コードベース内の類似パターンを3つ以上検索すること 重要・必ず注意 すべての主張に file:line の証拠を引用すること（行動するには確信度が80％を超えること） 重要・必ず注意 実行時に観察できる UI／UX デザイン原則の確認を実施すること — 40の節すべて（UI-1.1～UI-9.4）を9つの重点確認として実施し、すべての指摘に UI-<clause> と URL／ビューポート／スクリーンショット（ソースを特定できる場合は file:line も）を記載し、数値を指定している節では実測値も記載すること。ソースまたはデザイントークンの確認が必要な節はここでは対象外とし、$ui-review に回すこと 重要・必ず注意 作業の品質を確認する最終レビュー用の TODO タスクを追加すること 必須・重要・必ず注意 作業を始める前に、次のファイルを読むこと：

重要・必ず注意 作業を始める前に CLAUDE.md を読むこと

[TASK-PLANNING] 作業に取りかかる前に、タスクの範囲を分析し、タスク追跡を使って体系的に小さな TODO タスクとサブタスクに分割してください。

フックレス・プロンプト・プロトコルのミラー（自動同期）

ソース：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full ブロック）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] ワークフロー実行プロトコル — 必須・重要・必ず遵守・重大。いかなる理由があっても省略しないでください。

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとし、プロジェクト固有の規約は docs/project-config.json と docs/project-reference/ から確認します。共有 AI-SDD は shared/sdd-artifact-contract.md に従って適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクトリファレンスドキュメントを開いてください。仕様、テストケース、動作変更、公開コントラクト、または docs/specs/ に関する作業では、ドキュメントインデックスに記載されたローカルの仕様ドキュメント（feature-spec-reference.md、spec-system-reference.md、spec-principles.md、および仕様・テスト・コードの同期が必要な場合は workflow-spec-test-code-cycle-reference.md）を経由してください。いずれかのファイル、または必須のリファレンスドキュメントが見つからないか古くなっている場合は、通常のプロジェクト固有の作業に進む前に $project-init（または $project-config、$docs-init、$scan-all、$scan --target=<key> などの限定的な下位ルート）を自動実行してください。この共有コンテキストとローカルドキュメントが利用可能であれば、サポート対象の任意の AI ツールで実行できます。

1. 検出： プロンプトが明示的なスラッシュ形式のスキル／ワークフローコマンドで始まる場合は、それを直接実行します。それ以外の場合は、プロンプトをワークフローカタログとスキルリストに照らし合わせます。
2. 分析： 最適な方法を選択します。直接実行、スキルの呼び出し、標準ワークフローの開始、またはカスタムのステップ構成です。
3. 自動選択： 最適な方法を自分で選択します。直接実行、スキル、標準ワークフロー、カスタムワークフローのどれにするか、ユーザーに選択を求めてはいけません。
4. 開始： 選択したワークフローでは $start-workflow <workflowId> を呼び出します。選択したスキルではそのスキルを呼び出します。カスタムワークフローではカスタムステップを順に実行します。直接実行ではタスクに進みます。
5. タスクの作成： 選択した経路に複数のステップがある場合、実行前にすべてのワークフロー／スキル／カスタムステップについてタスクを追跡します。
6. 並列化： タスクリストの実行前に、各タスクに PAR（入力が独立しており、書き込み対象が他のすべての PAR タスクと重複しない）または SEQ（ブロックする依存関係を明記）を付け、PAR タスクをウェーブにグループ化し、ウェーブ計画を宣言して、各ウェーブのサブエージェントを1つのメッセージで起動します。各ウェーブでは全員の完了を待ち、サブエージェント自身の定義でさらなる並列化が認められている場合を除き、ファンアウトは1階層までとします。独立したタスクを逐次処理するのは不備です。共有の書き込み対象、出力を利用するタスク、単純な単一ファイルの作業、スキルやワークフローで順序が明示されている作業、ユーザー承認が必要な段階は並列化しないでください。
7. 実行： コンテキスト指示にある Workflow Step Advancement & Parallel Phases のルールに従って進めます。ステップの進行はモデル主導です。サブエージェントの完了はインライン呼び出しと同様にステップを進めます。並列フェーズのグループは全員の完了を待つバリアです（すべてのメンバーが完了した後にのみ進み、決して逐次化しません）。

共有 AI-SDD プロトコルマーカー

ソース：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 成果物契約 — 共有する仕様駆動開発のルールは、移植可能な状態に保ち、ソース側で管理します。

1. 再利用可能な AI-SDD の原則は .claude に置き、リポジトリ固有のパス、コマンド、担当者、製品、形式はプロジェクト設定または参照ドキュメントに記載します。
2. サイクルを維持します：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. すべての要件または不変条件を、判断、タスク、TC／テスト、ソースの根拠、ドキュメント／仕様の更新まで追跡します。
4. コードから仕様への抽出は、正規の仕様オーナーが承認するまでは参照専用として扱います。
5. 同期されたコンテキストがあれば、サポート対象の AI ツールで計画、実装、レビュー、検証を行えます。複数のツールを使うかどうかは任意です。
6. まず .claude のソースを更新してから、生成されたミラーを同期します。.agents、.codex、AGENTS.md を手動で編集しないでください。— 理由：ミラーは生成された成果物であり、次回の同期時に手動編集内容が上書きされます
7. docs/project-config.json、ルートの指示ファイル、または必須のプロジェクト参照ドキュメントが欠落しているか古い場合は、通常のプロジェクト固有の作業を行う前に、$project-init または適切な下位レベルの手順を自動実行します。

有効な参照先： アクティブなスキルルート内の shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• 必須 shared/sdd-artifact-contract.md を適用し、再利用可能な AI-SDD は .claude に、ローカルルールはプロジェクトのドキュメントに保持します。
• 必須 コードから仕様への抽出は、正規の承認を得るまで参照専用です。サポート対象の AI ツールであれば、同期されたコンテキストを使って実行できます。
• 必須 生成されたミラーを同期する前に .claude のソースを更新します。.agents、.codex、AGENTS.md を手動で編集しないでください。
• 必須 プロジェクト設定、ルートの指示ファイル、または必須の参照ドキュメントが欠落しているか古い場合は、プロジェクト固有の作業を $project-init または適切なセットアップ手順に自動的に振り分けます。 [TASK-PLANNING] [必須] ワークフローまたはスキルの手順を実行する前に、計画したすべての手順についてタスク追跡を作成／更新し、各手順の開始時と完了時に同期してください。

[LESSON-LEARNED-REMINDER] [BLOCKING] タスク計画と継続的な改善 — 必須。省略しないでください。

作業を始める前に、作業を小さなタスクに分割して追跡します。最後のタスクに「AI のミスと教訓を分析する」を追加します。

教訓の抽出 — 症状への対処ではなく、根本原因のみを扱います：

1. 症状ではなく、失敗モード（推論や前提の誤り）を特定します。「間違った enum 値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を確認します。この失敗モードは 3 つ以上の状況／コードベースに当てはまりますか？当てはまらない場合は、もう一段階抽象化します。
3. 普遍的なルールとして記述します。プロジェクト固有の名前、パス、クラスを取り除きます。どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードに起因する複数のミスは、1 つの教訓にまとめます。
5. 再発ゲート：「このリマインダーがなければ、今後のセッションで再発するか？」いいえ → $learn は省略します。
6. 自動修正ゲート：「$code-review／$code-simplifier／$security-review／$lint で検出できるか？」はい → 代わりにレビュー用スキルを改善します。
7. 両方のゲートを通過した場合は、ユーザーに $learn の実行を依頼します。 [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。あらゆる主張に追跡可能な証拠を求め、行動する際は確信度を 80% 超とします。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実性を率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。証拠のない確信が、あらゆるハルシネーションの根本原因です。 AI の注意力の原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、最も重要なルールを上部と下部の両方に 3 つずつ配置し、長いコンテキストでも指示への準拠を維持します。 目標主導の実行： まず成功基準を定め、検証できるまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストは意図を検証します： テストは現在の動作をなぞるだけでなく、ビジネスルールや不変条件を保護し、保護対象の意図が崩れたときに失敗する必要があります。

よくある AI のミスを防ぐ（システムの教訓）

• コンテキスト圧縮後はファイルを再読込してください。 編集するには、同じコンテキスト内で事前に Read している必要があります。圧縮によって読込状態は消去されます。編集前に再読込してください。
• 一括置換後は古い用語を grep してください。 AI は検索・置換の完全性を過信します。一括編集後はリポジトリ全体を grep し、ドキュメント／設定／カタログに参照漏れがないか確認してください。
• 削除前に下流の参照を確認してください。 削除の影響は、ドキュメントやコードの陳腐化へ連鎖します。削除前に参照元ファイルを洗い出してください。
• 記憶を失った後、新しく作成する前に既存の状態を確認してください。 圧縮によってこれまでの作業の記憶が消去されます。作業を再開するときは現在の状態を確認し、決してむやみに重複作成しないでください。
• AI 生成コンテンツは実際のコードと照合してください。 AI は API、クラス名、メソッドシグネチャを幻覚することがあります。ドキュメントへの記載や参照の前に、grep して実在を確認してください。
• 編集後は依存関係を最後までたどってください。 定義を変更しても、その下流の利用箇所を見落とすことがあります。依存関係をすべてたどってください。
• 名前を変更するときは、利用側の全ファイル形式を grep してください。 ファイル形式によっては、参照先が見つからなくてもエラーなしで無視されます。コード、テンプレート、設定、生成ファイルを検索してください。
• 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することと、実行されることは同じではありません。正常系だけでなく、早期リターン、エラー分岐、条件によるスキップもたどってください。
• ソースが変わったら、正規データを埋め込んでいるドキュメントも更新してください。 派生データ（ワークフロー、スキーマ、設定など）を直接記載しているドキュメントは、気づかないうちに古くなります。ソースと合わせて、該当する埋め込みドキュメントをすべて更新してください。
• コンテキスト復旧後は、サブエージェントの結果を検証してください。 親エージェントが圧縮されている間にバックグラウンドエージェントが完了している場合があります。完了したはずだと信じず、出力を grep して確認してください。
• 対象の全一覧とサブエージェントへの割り当てを照合してください。 カテゴリごとにサブエージェントを並行実行すると、境界上の項目を見落とすことがあります。作業を進める前に、割り当ての和集合を対象一覧と照合してください。
• サブエージェントが引き継ぐ知識は、そのエージェントの .md 定義に書かれた内容だけです。組み込みの Explore ではなく、カスタムエージェント種別を使用してください。 ツールの採用には、権限＋知識＋適用（番号付きワークフロー手順）が必要です。
• サブエージェントの調査結果は最後にまとめてではなく、随時保存してください。 長時間実行されるサブエージェントは、最終書き込み前に打ち切られることがあり、調査結果が失われます。報告ファイルにセクションごとに追記するよう指示してください。
• デバッグ時は修正する前に「どちらの責任か」を確認してください。 呼び出し元（データが誤っている）と呼び出し先（処理が誤っている）をたどり、責任のある層を修正してください。症状が表れる箇所だけを修正してはいけません。
• テスト失敗時は、追跡や編集の前に暫定判定を記録してから調査してください。 次の 5 つの分類をすべて使ってください。SOURCE-WRONG（本番コードが意図に反している）、TEST-WRONG（アサーション／セットアップが古くなっている）、TEST-NOT-OPTIMAL（妥当だが脆弱、または情報量の少ないテスト）、ENVIRONMENT-BLOCKED（外部状態のため判定できない）、AMBIGUOUS（意図や証拠から安全に選べない）。その後、根本原因をたどり、適用される仕様（存在する場合は docs/specs/**）とソースの両方に照らして検証してください。成功を無理に得るために、アサーションを弱めたり、スキップを追加したり、タイムアウトを緩めたり、ソースを変更したりしてはいけません。
• 抽出／リファクタリング後は、削除した名前をすべて grep してください。 主要ファイルの作業完了は、他のファイルもクリーンであることを意味しません。完了を宣言する前に、対象範囲全体で削除したシンボルを一つずつ grep してください。
• 既存の値には意図があると考え、変更したり不具合だと指摘したりする前に、必ず理由を確認してください。 パターンマッチで「誤り」と決めつけると、背景を見落とします。定数／上限／フラグ／しきい値を変更または報告する前に、コメント、git blame、呼び出し元の処理順序（値を正しくする保証は、通常、該当行の直前に実行されるコードにあります）、同じ規約を使っている 2 つ以上の類似した呼び出し箇所を確認してください。理由なしに WHAT（何をするか）だけを記したドキュメントは、根拠が欠けているのではなく、WHY（なぜそうするか）の説明が不足しているということです。検証作業でも、正確な file:line の引用が証明するのは転記が正確であることだけであり、不具合の存在ではありません。
• 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 一つのビルドが成功しても、すべてが成功したとは限りません。複数のスタックにまたがる変更（バックエンド／フロントエンド／テスト／ドキュメント）では、すべての出力を検証してください。
• 近くにあるパターンをコピーする前に、適合性を評価してください。 最も近い例が適合するとは限りません。新しいコンテキストが同じ制約、基底クラス、スコープ、ライフタイムを共有するか確認してください。
• デバッグでは全体を優先し、目についた箇所に飛びつかないでください。 最初に思いついた原因へすぐ飛びつかないでください。前提条件（設定、環境変数、パス、DB、エンドポイント、認証情報、バージョン、DI、データ）をすべて列挙し、それぞれを証拠（推論ではなく grep／クエリ）に照らして検証してください。「何があればこの仮説は否定されるか？」と問い、何も答えられないなら、それは仮説ではありません。最もコストの高い失敗は、バグが一度も疑われていない層にあるのに、「明らか」だと思い込んだ層をさらに深掘りすることです。
• 変更は最小限にし、差分テストを適用してください（コンテキストに合わせて判断）。 2 つのモードがあります。（1）バグ修正 → すべての行がバグに直接関係するようにし、スタイル変更はしないでください。不要になったインポートを削除してよいのは、あなたの変更によって不要になったものだけです。（2）レビュー／機能強化 → 改善を実装し、「主な依頼を超える機能強化：[内容]」と明示してください。黙ってスコープを拡大しないでください。差分テスト：「X を依頼されていなかったとしても、この行は存在していたか？」いいえなら、削除するか明示してください。
• 実装前に曖昧さを明らかにし、黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、それぞれの工数とともに提示してください。「[依頼] は（1）[N 時間]、（2）[N 時間]のいずれかと解釈できます。どちらが重要ですか？」まずスコープ／形式／量／制約に関する前提を列挙してください。より簡単な方法がある場合は、そのことも伝えてください。黙って選ばないでください。
• [必須の最初のアクション] 応答する前に、必ず適切なスキルまたはワークフローを有効にしてください。 ワークフローカタログとスキル一覧に照らしてタスクを確認し、スキルの呼び出し、または $start-workflow <workflowId> で実行してください。確認する前に回答やコード作成をしてはいけません。省略はプロトコル違反です。
• Why-Review の敵対的な視点は、計画、判断、設計をレビューするときに適用してください。 基本姿勢は VALIDATOR（妥当性を確認する側）ではなく SKEPTIC（懐疑的な側）です。却下された代替案の最も強い論拠を組み立て、述べられた理由を一つずつ逆転させて「何を犠牲にするのか」を問い、上位 2～3 個の前提をストレステストし、プレモーテム（「リリースしたが 3 か月後に失敗した。何が壊れたのか？」）を行い、作成者が見落とした代替案を 1～2 個提示してください。セクションがあるだけでは十分ではありません。重要なのは、因果関係に基づく推論、具体的な軽減策、証拠です。「より良い」や「注意深く監視する」だけでは不十分です。
• 大規模なレビューでは、サブエージェントへのプロンプトで報告書の書き込みを最初に行わせてください。 多数のファイルを扱うサブエージェントは、最終書き込みの前に予算を使い切り、調査結果を失うことがあります。プロンプトは、（1）報告書の書き込みを最初に明示する成果物とする、（2）まとめてではなくファイル／セクションごとに追記する、（3）読み込みで予算を使い切らないようスコープを限定する、という構成にしてください。報告ファイルを残さず文の途中で打ち切られた場合は、同じプロンプトを再試行せず、より狭いスコープで再実行してください。
• コンテキスト圧縮後は、続行する前に以前の各フェーズの結果をすべて再検証してください。 要約が示すのは意図であり、環境の状態（git のインデックス、ファイルシステム、プロセス）ではありません。再開時はまず git status を確認し、変更したファイルを再読込し、ファイルシステムを検証してください。証拠で確認されるまでは、「完了した」という主張もすべて未検証の仮説です。
• OOM／メモリ：行サイズより先に行数を確認してください。 次の順にトリアージします。（1）上限のないクエリ — 条件を設定するトリガーとなる DB フィルターがありませんか？ DB 側にフィルターを移せば、OOM を解消できます。（2）行サイズが大きいですか？ プロジェクションを使えば比例して減らせます。費用対効果では、プロジェクションより行数削減が優先です。
• システムが担う最終結果をアサートし、インフラストラクチャが担う中間状態をアサートしないでください。 非同期処理（キュー／ブローカーへの配信、再試行、バックグラウンドジョブ、キャッシュ、レプリケーション）をテストする場合は、最終的なビジネス／エンティティの状態をアサートしてください。配信の記録、つまり消費／送信ステータス、試行回数、最終エラー、ブローカー、スケジューラー、outbox／inbox テーブル内の行の有無や件数をアサートしてはいけません。この記録は共有インフラストラクチャに存在し、並行して動く任意のプロセス（別のワーカー、2 つ目のレプリカ、残っているローカルコンテナー）から書き込めるうえ、通常は決定的な共有キーが使われます。そのため、こうしたアサーションは気づかないうちにシステムではなく開発者の環境をテストします。単独実行では成功しても、同じブローカー＋データベースをほかの何かが共有した途端に不安定になります。すべてのアサーションで、次の判定の問いを使ってください。「どのプロセスが処理しても、この結果は成り立つか？」いいえなら、代わりに収束後のデータ状態をアサートしてください。系として、プロセスローカルな障害注入やプロセス内テレメトリーを、任意のプロセスが実行する処理のゲートとして使うことはできません。負荷増幅に使ってください（有効化 → 範囲を限定した時間枠 → 無効化 → 収束をアサート）。前提条件として使ってはいけません。
• ドメイン概念を汎用／共有／インフラストラクチャ層に持ち込まないでください。 再利用可能な層（共有ライブラリ、フレームワーク、インフラモジュール）は、利用側に固有のドメイン概念（テナント／顧客／製品 ID、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。