ui-ux-pro-max

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／UX デザインインテリジェンスを提供します。スタイル 50 種、パレット 21 種、フォントの組み合わせ 50 種、チャート 20 種、スタック 8 種を収録しています。

ワークフロー：

1. 分析 — ユーザーのリクエストから、プロダクトの種類、スタイルのキーワード、業界、スタックを抽出します
2. 検索 — search.py を使用して、プロダクト、スタイル、タイポグラフィ、カラー、ランディングページ、チャート、UX の各ドメインを検索します
3. スタックのガイドライン — スタック固有のベストプラクティスを取得します（デフォルト：html-tailwind）
4. 実装 — 検索結果を統合し、一貫性のあるデザインとコードを作成します

重要なルール：

• UI アイコンに絵文字を使わないでください（SVG を使用します：Heroicons、Lucide、Simple Icons）
• クリック可能な要素にはすべて cursor-pointer とホバー時のフィードバックを設定します
• ライトモードのテキストは、コントラスト比を最低 4.5:1 にします
• すべての非同期 UI 領域で、すべての状態に必ず対応してください — 処理中はローディングインジケーター、失敗時はリトライ可能なユーザー向けエラー、データがない場合は意味のある空の状態を表示します。何も表示されないまま固まる状態、エラーが通知されない状態、空白のリストは決して避けてください。
• デフォルトでレスポンシブにします — 小型デバイスでもレイアウトを必ず使いやすく保ちます。推奨：再配置（flex-wrap を使った行、または「行 → 列」への変更、グリッドを 1 列にする）。レイアウトの再配置が現実的でない場合（テーブル、キャンバス、幅の広いグリッド）は、代替策として固定の min-width／min-height と overflow: auto によるスクロールを認めます。スクロールは問題ありません。最低限、レイアウトが壊れないようにしてください。コンテンツの一部が切れる、見切れる、アクセスできなくなる状態は避けます。小型画面への対応にタスクの範囲を超える大規模なリファクタリングが必要な場合は、まずユーザーに作業範囲を確認してください。
• 提出前に、ライト／ダークモード、すべての UI 状態（ローディング／エラー／空の状態）、レスポンシブの各ブレークポイント（320／768／1024／1440）をテストします

事前確認（プロジェクトのデザインシステム）： プロジェクトにデザインシステムがある場合は、docs/project-config.json から designSystem.canonicalDoc と tokenFiles を読み込み、汎用のスタイルインテリジェンスデータベースよりも、プロジェクトのトークン／コンポーネントを優先してください。

懐疑的な姿勢を保ってください。批判的思考と段階的思考を用いてください。すべての主張について、根拠を追跡し、確信度をパーセンテージで示してください（アイデアの確信度は 80％を超える必要があります）。

UI/UX Pro Max - デザインインテリジェンス

UI スタイル、カラーパレット、フォントの組み合わせ、チャートの種類、プロダクトの推奨事項、UX ガイドライン、スタック固有のベストプラクティスを収録した検索可能なデータベースです。

前提条件

Python がインストールされているか確認します。

python3 --version || python --version

Python がインストールされていない場合は、ユーザーの OS に応じてインストールします。

macOS：

brew install python3

Ubuntu/Debian：

sudo apt update && sudo apt install python3

Windows：

winget install Python.Python.3.12

---

このスキルの使い方

ユーザーが UI／UX の作業（デザイン、構築、作成、実装、レビュー、修正、改善）を依頼したら、次のワークフローに従います。

ステップ 1：ユーザーの要件を分析する

ユーザーのリクエストから重要な情報を抽出します。

• プロダクトの種類：SaaS、eコマース、ポートフォリオ、ダッシュボード、ランディングページなど
• スタイルのキーワード：ミニマル、遊び心のある、プロフェッショナル、エレガント、ダークモードなど
• 業界：ヘルスケア、フィンテック、ゲーム、教育など
• スタック：React、Vue、Next.js、またはデフォルトの html-tailwind

ステップ 2：関連するドメインを検索する

search.py を複数回実行して、包括的な情報を収集します。十分な文脈が得られるまで検索してください。

python .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]

推奨する検索順序：

1. プロダクト — プロダクトの種類に合ったスタイルの推奨事項を取得します
2. スタイル — 詳細なスタイルガイド（カラー、エフェクト、フレームワーク）を取得します
3. タイポグラフィ — Google Fonts のインポート方法を含むフォントの組み合わせを取得します
4. カラー — カラーパレット（プライマリ、セカンダリ、CTA、背景、テキスト、境界線）を取得します
5. ランディングページ — ページ構成を取得します（ランディングページの場合）
6. チャート — チャートの推奨事項を取得します（ダッシュボード／分析の場合）
7. UX — ベストプラクティスとアンチパターンを取得します
8. スタック — スタック固有のガイドラインを取得します（デフォルト：html-tailwind）

ステップ 3：スタックのガイドライン（デフォルト：html-tailwind）

ユーザーがスタックを指定しない場合は、デフォルトで html-tailwind を使用します。

python .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind

利用可能なスタック：html-tailwind、react、nextjs、vue、svelte、swiftui、react-native、flutter

---

検索リファレンス

利用可能なドメイン

ドメイン	用途	キーワードの例
product	製品タイプの推奨	SaaS、e コマース、ポートフォリオ、ヘルスケア、美容、サービス
style	UI スタイル、色、エフェクト	グラスモーフィズム、ミニマリズム、ダークモード、ブルータリズム
typography	フォントの組み合わせ、Google Fonts	エレガント、遊び心のある、プロフェッショナル、モダン
color	製品タイプ別のカラーパレット	SaaS、e コマース、ヘルスケア、美容、フィンテック、サービス
landing	ページ構成、CTA 戦略	ヒーロー、ヒーロー中心、推薦文、料金、ソーシャルプルーフ
chart	チャートの種類、ライブラリの推奨	トレンド、比較、タイムライン、ファネル、円グラフ
ux	ベストプラクティス、アンチパターン	アニメーション、アクセシビリティ、z-index、読み込み
prompt	AI プロンプト、CSS キーワード	（スタイル名）

利用可能なスタック

スタック	対象
html-tailwind	Tailwind ユーティリティ、レスポンシブ、a11y（デフォルト）
react	状態、フック、パフォーマンス、パターン
nextjs	SSR、ルーティング、画像、API ルート
vue	Composition API、Pinia、Vue Router
svelte	Runes、ストア、SvelteKit
swiftui	ビュー、状態、ナビゲーション、アニメーション
react-native	コンポーネント、ナビゲーション、リスト
flutter	ウィジェット、状態、レイアウト、テーマ設定

---

ワークフローの例

ユーザーのリクエスト：「プロフェッショナルなスキンケアサービスのランディングページを作成してください」

AI が行うこと：

# 1. Search product type
python .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product

# 2. Search style (based on industry: beauty, elegant)
python .claude/skills/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style

# 3. Search typography
python .claude/skills/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography

# 4. Search color palette
python .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color

# 5. Search landing page structure
python .claude/skills/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing

# 6. Search UX guidelines
python .claude/skills/ui-ux-pro-max/scripts/search.py "animation" --domain ux
python .claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux

# 7. Search stack guidelines (default: html-tailwind)
python .claude/skills/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind

**次に：**検索結果をすべて統合し、デザインを実装します。

---

より良い結果を得るためのヒント

1. キーワードを具体的にする — 「ヘルスケア SaaS ダッシュボード」＞「アプリ」
2. 複数回検索する — キーワードを変えると、異なる知見が得られます
3. ドメインを組み合わせる — スタイル＋タイポグラフィ＋色＝完全なデザインシステム
4. UX を必ず確認する — よくある問題を確認するには、「animation」「z-index」「accessibility」を検索します
5. スタックフラグを使用する — 実装に特化したベストプラクティスを取得できます
6. 反復する — 最初の検索結果が合わない場合は、キーワードを変えてみます

---

キュレーションの制約（UI/UX デザイン原則）

データベースは推奨事項を提示します。40 の UI/UX デザイン原則（UI-1.1～UI-9.4、以下の SYNC:ui-ux-design-principles ブロック）は、推奨できる内容を制約します。検索結果は判定ではなく候補です。ユーザーまたは design に提示する前に、条項に照らして確認してください。プロジェクトのデザインシステムのドキュメントは、条項とこれらのデータベースの両方より優先されます。実際に矛盾がある場合はユーザーに確認し、決して黙って解決してはいけません。

厳選した出力	推奨する前に満たすべき条項の制約
パレット（--domain color、スタイルパレット）	提案する色の組み合わせを測定します。背景上のテキストは ≥4.5:1、UI のエッジ／境界線は ≥3:1（UI-3.1）とし、測定した比率を報告します。「問題なさそう」とは決して言いません。アクセントは役割を1つに絞ります（UI-3.2）。色だけでステータスを示すことはせず、アイコンまたはラベルを併用します（UI-3.3）。ダークバリアントでは、エレベーションのためにサーフェスを明るくし、純白のテキストを和らげます。ライトパレットを反転したものではありません（UI-3.4）。
フォントの組み合わせ（--domain typography）	ファミリーは最大2種類、ウェイトは最大3種類です（UI-2.1）。3つ目のファミリーが必要な組み合わせは、選びすぎです。本文はウェブで16px、モバイルで17pxとし、読みやすいコンテンツでは14px未満にしません（UI-2.2）。1行あたり45～75文字になるよう測定します（UI-2.3）。行間は本文で1.5、ディスプレイで1.1～1.2にします（UI-2.4）。サイズをばらばらに列挙するのではなく、名前付きの6段階のタイプスケールとして組み合わせを提示します（UI-2.5）。
スタイル／製品の推奨（--domain style、--domain product）	スタイルでは、画面ごとにフォーカルポイントを1つに絞れること（UI-1.1）、入れ子のボックスではなく余白でグループ化できること（UI-1.3）が必須です。フォーカスリングの削除（UI-5.5）、プレースホルダーの背後にラベルを隠すこと（UI-7.2）、または動きを軽減する設定を無視した150～250msのイーズアウト以外のアニメーション（UI-5.4）を必要とする美的スタイルは、却下するか調整します。
間隔／レイアウトの指針（--domain style、スタックのガイドライン）	間隔は、4pxまたは8pxを基準単位とする乗数1つで表し、すべての間隔をその倍数にします（UI-4.1）。間隔はコンテナがgapプロパティで管理します（UI-4.2）。グループ内の間隔はグループ間より狭くします（UI-4.3）。ブレークポイントはデバイス名ではなく、コンテンツに合わせます（UI-4.4）。
この情報をもとに引き継ぐ、または構築するすべてのUI	空、読み込み中、エラーの各状態を、コンテンツが入った状態より先に指定します（UI-1.5）。読み込み後にレイアウトがずれないよう、あらかじめスペースを確保します（UI-9.3）。各インタラクティブ要素について、5つのインタラクション状態（デフォルト、ホバー、フォーカス、アクティブ、無効）を列挙し、該当する場合は読み込み中の状態も加えます（UI-5.2）。モバイル／タッチ画面では、タップ領域を44×44pt以上、間隔を8px以上にし（UI-8.1）、主要なアクションを画面下部3分の1に配置します（UI-8.2）。

厳選した推奨内容が条項を満たせない場合は、 条項IDを明示してその旨を伝え、準拠した代替案を提示してください。UI-3.1に違反する美しいパレットは、成果物ではなく指摘事項です。

プロフェッショナルなUIの共通ルール

UIをプロフェッショナルに見せるうえで、見落とされがちな問題は次のとおりです。

アイコンとビジュアル要素

ルール	推奨すること	避けること
絵文字アイコンを使わない	SVG アイコン（Heroicons、Lucide、Simple Icons）を使う	🎨 🚀 ⚙️ のような絵文字を UI アイコンとして使う
安定したホバー状態	ホバー時に色や不透明度をトランジションさせる	レイアウトがずれるスケール変換を使う
正しいブランドロゴ	Simple Icons で公式 SVG を調べる	ロゴのパスを推測したり、誤ったものを使ったりする
アイコンサイズの統一	固定の viewBox（24x24）と w-6 h-6 を使う	異なるアイコンサイズをランダムに混在させる

インタラクションとカーソル

ルール	推奨すること	避けること
ポインターカーソル	クリック可能またはホバー可能なすべてのカードに cursor-pointer を追加する	インタラクティブな要素にデフォルトのカーソルを表示する
ホバー時のフィードバック	視覚的なフィードバック（色、影、境界線）を提供する	要素がインタラクティブであることを示さない
スムーズなトランジション	transition-colors duration-200 を使う	状態を瞬時に切り替えたり、遅すぎるトランジション（>500ms）を使ったりする

ライト／ダークモードのコントラスト

ルール	推奨すること	避けること
ライトモードのガラスカード	bg-white/80 またはそれ以上の不透明度を使う	bg-white/10（透明すぎる）を使う
ライトモードのテキストコントラスト	テキストに #0F172A（slate-900）を使う	本文に #94A3B8（slate-400）を使う
ライトモードの控えめなテキスト	最低でも #475569（slate-600）を使う	gray-400 またはそれより明るい色を使う
境界線の視認性	ライトモードでは border-gray-200 を使う	border-white/10（見えない）を使う

レイアウトと間隔

ルール	推奨すること	避けること
フローティングナビバー	top-4 left-4 right-4 の間隔を追加する	ナビバーを top-0 left-0 right-0 に固定する
コンテンツのパディング	固定ナビバーの高さを考慮する	コンテンツを固定要素の背後に隠す
最大幅の統一	同じ max-w-6xl または max-w-7xl を使う	異なるコンテナー幅を混在させる

非同期 UI の状態とフィードバック（特に見落とされやすい基本事項）

データを取得、送信、変更するすべての画面またはコンポーネントでは、正常系だけでなく、すべての状態を表示する必要があります。 データが表示されているときは完璧でも、読み込み中に画面が固まったように見えたり、エラー時に何も表示されなかったり、空のときに何も表示されなかったりする UI は、ユーザー体験として不十分です。標準的な状態の用語（design-spec と共通）：デフォルト／読み込み中／無効／エラー／空／成功。

状態	すること	しないこと
読み込み中	リクエストの処理中は、スピナー／スケルトン／進行状況を表示する	画面を固まった状態や空白のままにする。ページ全体を何も表示せずにブロックする
エラー	再試行／復旧の操作とともに、ユーザーにわかりやすいメッセージを表示する	エラーを黙って無視したり、握りつぶしたり、生のスタックトレース／JSON を出力したりする
空	意味のある空の状態（イラスト／メッセージ＋任意の CTA）を表示する	リスト／テーブルに項目がないときに空白の領域を表示する
処理中／無効	リクエストの処理中は送信／操作ボタンを無効にする（または処理中であることを表示する）	トリガーを有効なままにして、二重送信を許す
成功	完了を通知する（トースト／インライン表示／目に見えるデータ更新）	ユーザーに何も知らせずに変更処理を完了する

レスポンシブ対応とマルチデバイス対応（小さな画面でも使いやすく）

ルール	すること	しないこと
行を折り返す	小さな画面幅では flex-wrap: wrap を使うか、flex-direction: row → column に切り替える	スマートフォンで表示がはみ出す、固定の flex-direction: row
グリッドを折りたたむ	複数列のグリッドを、小さな画面では1列にする	列数やトラック幅を固定し、決して折りたたまれないようにする
スクロールによる代替も可	折り返せない場合（テーブル／キャンバス／幅の広いグリッド）は、固定の min-width／min-height ＋ overflow: auto を使う — スクロールで構いません	コンテンツが切り取られる、見切れる、またはスクロール手段がないため画面外のコントロールにアクセスできない
固定より柔軟なサイズ指定	min/max-width、flex-grow、%／rem によるサイズ指定	コンテナー／カード／ダイアログに大きな固定 px 幅を指定する
大規模なリファクタリング → 確認	小さな画面への対応に大規模なレイアウト変更が必要な場合は、その旨を伝え、スコープをユーザーに確認する	大規模なレイアウトを黙って書き換える。または小さな画面で壊れた状態のままリリースする

---

提出前チェックリスト

UI コードを提出する前に、以下の項目を確認してください。

ビジュアル品質

• アイコンとして絵文字を使用していない（代わりに SVG を使用する）
• すべてのアイコンで統一されたアイコンセットを使用している（Heroicons／Lucide）
• ブランドロゴが正しい（Simple Icons で確認済み）
• ホバー状態でレイアウトがずれない

インタラクション

• クリック可能なすべての要素に cursor-pointer が指定されている
• ホバー状態で明確な視覚的フィードバックがある
• トランジションが滑らかである（150-300ms）
• キーボード操作時にフォーカス状態が見える

状態とフィードバック（非同期の画面要素 — すべて確認してください）

• 読み込み中 — データの取得／送信／変更の処理中は、すべてスピナーまたはスケルトンを表示してください（画面が真っ白なまま固まらないようにします）
• エラー — 失敗する可能性のあるすべての操作で、再試行／復旧方法を含む、ユーザーにわかりやすいエラーを表示してください（エラーを黙って無視したり、生のスタックトレースを表示したりしないでください）
• 空の状態 — リスト／テーブル／コレクションのすべてのビューに、意味のある空の状態（メッセージと任意のCTA）を用意してください。空白のままにしないでください
• 処理中の無効化 — リクエストの実行中は、送信／アクションボタンを無効化するか、処理中の状態にしてください（二重送信を防ぎます）
• 成功 — 変更処理が完了したら、確認フィードバック（トースト／インライン表示／データの更新）を行ってください

ライトモード／ダークモード

• ライトモードのテキストは十分なコントラストを確保してください（最低 4.5:1）
• ライトモードでもガラス風／透明な要素が見えるようにしてください
• どちらのモードでも境界線が見えるようにしてください
• 納品前に両方のモードをテストしてください

レイアウトとレスポンシブ対応

• フローティング要素と画面端の間に適切な余白を設けてください
• 固定ナビゲーションバーの背後にコンテンツが隠れないようにしてください
• 320px、768px、1024px、1440px の幅でレスポンシブに対応してください
• 小さい画面では、行の flex-wrap を設定するか、row → column に切り替えてください。複数列のグリッドは 1 列にしてください
• 320px まで使いやすい状態にしてください — 何も壊れていないこと（コンテンツが切れる、途中で見えなくなる、アクセスできなくなることがないこと）。レイアウトを本当に組み替えられない場合は、min-width／min-height と overflow: auto によるスクロールを許容します
• 小さい画面向けの修正に大規模なレイアウト変更が必要な場合は、黙って書き換えず、その旨をユーザーに伝えて確認を取ってください

アクセシビリティ

• すべての画像に代替テキストを設定してください
• フォーム入力にラベルを設定してください
• 色だけを唯一の識別手段にしないでください
• prefers-reduced-motion を尊重してください

関連項目

• design --lane=marketing — マーケティング／クリエイティブ UI（ランディングページ、キャンペーン）
• design --lane=product — プロダクト UI（ダッシュボード、管理パネル、SaaS アプリ）
• shadcn-tailwind
• design-spec

---

[IMPORTANT] 作業を始める前に、タスク管理を使って、各ファイルの読み込みタスクも含め、すべての作業を小さなタスクに分割してください。長いファイルによるコンテキストの喪失を防げます。簡単なタスクでは、スキップするかどうかを AI が必ずユーザーに確認しなければなりません。 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 / 文書化する	プロジェクトが意図的に逸脱している箇所を記録し、優先されるドキュメントが記録上の判断基準となるようにします。

省略できるのは変更にユーザー向けの画面がない場合（バックエンドのみ、ツール、ドキュメント）に限ります。省略を明示し、見落としではなく監査可能な判断として記録します。 AI によるミスの防止 — あらゆるタスクで避けるべき失敗パターン：

コンテキストが変わったらファイルを読み直してください。 コンテキストの圧縮、作業の再開、長時間にわたる作業によって記憶が古くなっている場合があります。作業に取りかかる前に、現在のファイルを確認してください。 生成した内容を根拠となるソースと照合してください。 AI は API、名前、主張、文書の事実を幻覚することがあります。文書化または参照する前に、該当するソースを確認してください。 削除または名前変更の前に、下流の参照を確認してください。 成果物を削除すると、ドキュメント、生成されたミラー、設定、呼び出し元に古い情報が残る可能性があります。まず参照先を洗い出してください。 編集後は影響の連鎖全体をたどってください。 定義を変更しても、派生出力や利用側への対応が漏れる可能性があります。完了と判断する前に、影響を受ける連鎖をたどってください。 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 チェックが 1 つ成功しても、すべて成功したことにはなりません。変更によって影響を受ける可能性のあるすべての出力先を検証してください。 既存の値は意図的なものと考え、変更したり不具合と指摘したりする前に、その理由を確認してください。 定数、上限、フラグ、しきい値、文言、パターンを変更または報告する前に、周辺のコンテキストと履歴、呼び出し元での順序、同じ規約を使う 2 つ以上の類似した呼び出し箇所を確認してください。何をするかだけを記したドキュメントに理由がない場合、それはガードの不足を示す証拠ではなく、根拠の説明が不足しているということです。 曖昧さは行動する前に明らかにし、黙って解釈を選ばないでください。 複数の妥当な解釈がある場合は、明示的に質問するか、リスクを示したうえで前提を明記してください。 インフラが管理する中間状態ではなく、システムが責任を持つ最終結果を検証してください。 非同期処理を検証する際は、最終的なビジネス状態を確認してください。共有インフラで並行実行中のどのプロセスからも書き込める、配信や再試行の記録状態は確認しないでください。このようなチェックは単独実行では成功しても、同じインフラを別の処理が共有した途端に不安定になります。 共有ガイダンスは、それを受け取る役割に関係する内容にしてください。 あらゆる役割に共通するガイダンスは、それを受け取るすべてのスキルやエージェントに役立つものでなければなりません。コード固有の要件は、コード固有のプロトコルにのみ記載してください。

批判的思考の姿勢 — 批判的思考と順序立てた思考を実践してください。すべての主張には追跡可能な証拠が必要です。行動するには確信度が 80% を超えている必要があります。 幻覚の防止： 推測を事実として示さないでください。すべての主張について出典を示し、不確実な点は率直に認め、出力の誤りを自己点検し、独立して相互参照し、自分の確信を疑ってください。証拠のない確信こそが、あらゆる幻覚の根本原因です。

必ず注意してください： 批判的かつ順序立てた思考を実践してください。すべての主張には、追跡可能な適切な証拠が必要です（リポジトリやコードに関する主張には file:line、調査、製品、コンテンツ、ドキュメントに関する主張にはソース URL または成果物のセクション）。行動するには確信度が 80% を超えている必要があり、60% 未満の場合は推奨しないでください。幻覚を防止してください。推測を事実として示さず、不確実な点は率直に認め、独立して相互参照し、自分の確信を疑ってください。

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

• 要厳守 ユーザー向けのあらゆる画面に、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単位を一貫して使い、マージンよりgapを優先し、内側は狭く、要素間は広く、コンテンツに応じたブレークポイントを設定する（§4）· 100ms未満で応答し、5つの状態すべてを用意し、確認より取り消しを優先し、動きを抑える設定を尊重した150–250msのイーズアウトを使い、フォーカスリングを表示する（§5）· 現在地／ここにあるもの／次の行き先を示し、トップレベルの移動先は5つ以下にし、ユーザーの言葉を使い、URLまたは戻る経路を用意する（§6）· 入力欄を減らし、ラベルを表示し、フォーカスが外れたときに検証し、キーボード操作を適合させ、入力内容を絶対に失わせない（§7）· ターゲットは44×44pt以上で、間隔を8px空け、主要な操作要素は画面の下3分の1に配置し、ジェスチャーだけを唯一の操作方法にせず、安全領域を確保する（§8）· データより先に構造を示し、ロールバックが見える楽観的更新を行い、スペースを確保し、低速接続時の状態を用意する（§9）。プロジェクトのデザインシステムのドキュメントは、これらの規定より優先されます。実際に矛盾する場合はユーザーに提示し、決して黙って解決しないでください。すべての指摘にUI-<clause>とfile:lineを添えてください。ユーザー向けの画面に変更がない場合に限り、明示したうえで適用を省略してください。

プロジェクトプロトコルのオーバーレイ — このスキルを実行する前に、このスキルに重ねて適用されるプロジェクトのオーバーレイルールを確認してください。プロジェクトのスキルプロトコルインデックス（デフォルトでは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から読み取ってください。本文が存在しない、または形式不備の場合は報告し、決して復元しないでください。オーバーレイは追加のみであり、このスキル独自のルールを置き換えることはありません。また、オーバーレイはブリーフであり、決して権限を強化するものではありません。同じ具体性の内容が矛盾する場合は、ユーザーに提示してください。

最後の確認事項

重要・必ず注意する目標： 検索可能な UI/UX デザインインテリジェンスを提供します。50 種類のスタイル、21 種類のパレット、50 種類のフォントの組み合わせ、20 種類のチャート、8 種類のスタックを統合し、アクセシブルでプロフェッショナル、かつコントラスト要件を満たすインターフェースにします。

適用されるプロトコル（このスキルが保持する SYNC／共有ブロックの簡潔な要約）：

• AI の誤り防止： 生成した内容を証拠と照合し、下流の参照を追跡し、影響を受けるすべての出力を検証し、コンテキスト喪失後に読み直し、曖昧さを明示します。
• 批判的思考： 主張ごとに追跡可能な file:line の証拠を示し、確信度が 80% を超える場合にのみ実行し、決して推測しません。

重要・必ず注意すること： 作業を始める前に、タスク追跡を使って作業を小さな TODO タスクに分割します 重要・必ず注意すること： 新しいコードを作成する前に、コードベースで類似パターンを 3 件以上検索します 重要・必ず注意すること： すべての主張に file:line の証拠を引用します（実行するのは確信度が 80% を超える場合のみ） 重要・必ず注意すること： 作業の品質を検証するため、最終レビューの TODO タスクを追加します 重要・必ず注意すること： 40 項目の UI/UX デザイン原則（UI-1.1～UI-9.4）は、選定内容を制約します。選定したパレットも、テキストは 4.5:1、境界線は 3:1（UI-3.1）のコントラスト比を満たし、アクセントカラーは 1 色にし（UI-3.2）、色だけに頼らないようにする必要があります（UI-3.3）。選定したフォントの組み合わせも、16px の Web／17px のモバイルで最大 2 ファミリー×3 ウェイト（UI-2.1）とし、14px 未満は使用せず（UI-2.2）、6 段階のタイポグラフィスケールで提供します（UI-2.5）。スペーシングには 1 つの 4／8px 単位を乗算して使います（UI-4.1）。これを基に作るものは、空、読み込み中、エラーの各状態を最初に指定し（UI-1.5）、5 つすべてのインタラクション状態を備える必要があります（UI-5.2）。いずれかの条件を満たさない検索結果は、成果物ではなく指摘事項です。

[TASK-PLANNING] 実行する前にタスクの範囲を分析し、タスク追跡を使って小さな TODO タスクとサブタスクに体系的に分割します。

Hookless Prompt Protocol Mirror（自動同期）

Source: .claude/.ck.json + .claude/skills/shared/sync-inline-versions.md (:full blocks) + .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、ビジネスエンティティ、機能ルール）を一切参照してはいけません。漏れがコンパイルされ、実行されると、再利用可能なはずの層が一つの利用側と結合していても、レビューで気づかれずに通過してしまいます。共有型からドメイン情報を排除し、サブクラス化／コンポジションを通じて、ドメインフィールド／ロジックを利用側へ移してください。理由：一つの利用側のドメインに結合した層は、もはや再利用可能ではありません。