mcpField
D
design-spec

design-spec

github.com/duc01226デザイン・UI1260 回インストール1 週間前に更新
リポジトリ

design-spec について

design-specは、要件、ユーザーストーリー、PBIを開発者向けのUI/UX仕様にまとめるスキルです。既存画面と関連フローを調査し、コンポーネント、状態、デザイントークン、レスポンシブ動作を記録して保存・関連付けます。

主な機能

  1. 01要件から構造化された設計仕様を作成
  2. 02既存UIと関連フローを調査
  3. 03コンポーネント、状態、操作を定義
  4. 04デザイントークンとレスポンシブ規則を記録
  5. 05仕様を保存して関連付け

活用シーン

  1. 01PBIやストーリーの設計引き継ぎ準備
  2. 02画面コンポーネントと操作状態の明確化
  3. 03複数ページのフローとレスポンシブ動作の記録

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/duc01226/easyplatform --skill design-spec

インストール後、Claude Code で/design-specを入力して読み込まれたか確認します。

詳細

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 を確認し、関連するファイルだけを開いてください。

[BLOCKING] スキルのステップは宣言された順序で実行してください。ユーザーが明示的に承認しない限り、ステップを省略、並べ替え、または統合してはいけません。 [BLOCKING] 各ステップまたはサブスキルの呼び出し前にタスク追跡を更新し、ステップの開始時に in_progress、終了時に completed を設定してください。 [BLOCKING] 完了またはスキップしたすべてのステップには、簡潔な根拠または明示的なスキップ理由を記載してください。 [BLOCKING] Task ツールが利用できない場合は、同じステータス遷移を反映した、同等のステップごとの計画トラッカーを作成し、維持してください。

クイックサマリー

目標： 要件／PBI／ストーリー／ワイヤーフレームから、構造化された技術非依存の UI/UX 設計仕様を作成します。開発者がどのスタックでも UI を再構築できるよう、すべてのコンポーネント、状態、デザイントークン、レスポンシブルール、アクセシビリティ要件を文書化し、根拠となる Feature Spec にリンクします。

概要（ほかを読まない場合はここをお読みください — 目的と主要な全ステップ）：

  • 目的 — 要件を開発者がすぐに利用できる UI/UX 仕様（コンポーネント一覧、状態、デザイントークン、レスポンシブ動作、アクセシビリティ）に変換します。技術非依存とし、コンポーネントは UX 上の役割で命名し、フレームワークやライブラリのクラス名は使いません。
  • ステップ 0–0b — まず調査する： 既存の関連画面／コンポーネントを一覧化し、関連するフローをマッピングして、§1 に記録します。これにより、仕様を実際の UI システムに合わせます。根拠となる Feature Spec がある場合は、その §6 のインタラクション範囲を基にし、ビューと観測可能な状態の用語をそのまま再利用します。 — 理由：用語が統一されていないと、移動可能な仕様書とデザインハブの連携が損なわれます。
  • ステップ 1–2 — 入力を確認して振り分け、複雑さを判断する： Figma URL → $figma-design、画像／スクリーンショット → 視覚分析ツール、ワイヤーフレーム／スケッチ → --mode=wireframe、PBI／テキスト → 要件を抽出します。クイック仕様（§1–4）と完全仕様（§1–7、および複数ページの場合はフロー図）のどちらにするかを選びます。
  • ステップ 3–6 — 本文を作成する： コンポーネント一覧（新規と既存）を作成し、7 つの状態すべてとインタラクションを定義し、デザイントークン（デザインシステムを再利用）を抽出し、レスポンシブブレークポイント（モバイル 320–767／タブレット 768–1023／デスクトップ 1024 以上）を記録します。
  • ステップ 7–8 — 保存してリンクする： 成果物を team-artifacts/design-specs/ に保存し、根拠となる Feature Spec のフロントマターにある design_spec:／mockup: を、保存したパスに設定します。変更するのはフロントマターのみで、§1–8 の本文は変更しません。 — 理由：パスが記録されていないと、artifact-review --type=design が失敗します。

ワークフロー：

  1. ソースを読む — PBI、ストーリー、または Figma URL から UI 要件を抽出します
  2. 複雑さを判断する — クイック仕様（セクション 1–4）と完全仕様（全 7 セクション）のどちらにするかを決めます
  3. コンポーネント一覧を作成する — 新規と既存のコンポーネントを列挙します
  4. 状態とトークンを定義する — インタラクション、デザイントークン、レスポンシブブレークポイントを定義します
  5. 成果物を保存する — team-artifacts/design-specs/ に出力します

主なルール：

  • Figma URL が指定された場合 → コンテキスト抽出のため $figma-design に自動的に振り分けます
  • ワイヤーフレーム画像（手描き／デジタル／ツールからのエクスポート）が指定された場合 → --mode=wireframe を使用して内部で処理します（下記の「モード：wireframe」を参照）
  • スクリーンショットが指定された場合 → デザインの抽出に visual analysis tooling を使用します
  • docs/project-reference/design-system/ の既存のデザインシステムトークンを参照します
  • コンポーネントのパターン：docs/project-reference/frontend-patterns-reference.md
  • アクセシビリティ要件（キーボード操作、ARIA ラベル、コントラスト）を含めます
  • [BLOCKING] 技術非依存の出力： 仕様の本文／見出しは docs/project-reference/spec-principles.md §3 に従います。コンポーネントはフレームワークやライブラリ名ではなく UX 上の役割で記述します。ソースパスとクラス名を記載できるのは、エビデンス欄（**Evidence**、[Source:]）、フロントマター、Mermaid のみです。

懐疑的な姿勢を保ち、批判的かつ段階的に考えてください。すべての主張には追跡可能な証拠と確信度（Idea は 80% 超）が必要です。

設計仕様

要件または PBI から、開発者への引き継ぎに使う、構造化された UI/UX 設計仕様書を作成します。

使用する場面

  • 実装前に、PBI またはユーザーストーリーの設計仕様が必要な場合
  • 要件を具体的な UI レイアウト、状態、トークンに変換する場合
  • コンポーネント一覧とインタラクションパターンを文書化する場合
  • レスポンシブブレークポイントの仕様を作成する場合

使用しない場面

  • このスキルは Figma URL を $figma-design に自動的に振り分け、ワイヤーフレームは --mode=wireframe を使用して内部で処理します — 別のスキルを呼び出す必要はありません
  • 実際の UI を構築する場合 — design --lane=marketing（マーケティング／クリエイティブ）または design --lane=product（プロダクト UI）を使用してください
  • 既存の UI コードをレビューする場合 — web-design-guidelines を使用してください

前提条件

実行前に以下をお読みください。

  • 元の PBI、ユーザーストーリー、または要件ドキュメント
  • docs/project-reference/design-system/ -- プロジェクトのデザイントークン（該当する場合）
  • team-artifacts/design-specs/ にある既存のデザイン仕様 -- 形式の一貫性を保つため
フロントエンド／UI のコンテキスト

このタスクにフロントエンドまたは UI の変更が含まれる場合：

  • フロントエンドのパターン：docs/project-reference/frontend-patterns-reference.md
  • スタイリング／BEM ガイド：docs/project-reference/scss-styling-guide.md
  • デザインシステムのトークン：docs/project-reference/design-system/README.md

ワークフロー

[BLOCKING] ステップ 0 — 既存 UI の棚卸しと関連フローのマッピング（このスキルが定める SYNC:existing-ui-research プロトコルに従います）。仕様書を作成する前に、この機能またはドメインに関連する既存の画面／コンポーネント／ページを棚卸しし、新しい画面と関連するすべての機能フロー（リンク、埋め込み、または新しい画面への／からの遷移があるもの）をマッピングします。一致する画面とフローを §1 Overview に記録し、仕様書が現在の UI システムを正確に反映するようにします。バックエンドのみの作業の場合に限り、この手順を省略できます（その旨を明記してください）。

[BLOCKING] ステップ 0b — 基準となる Feature Spec が存在する場合、その §6 のインタラクションサーフェスを起点にする。 この機能を規定する標準的な Feature Spec がすでに存在するかどうかを確認します（docs/specs/** で同じ機能を対象とする仕様書を探します）。存在する場合は、その仕様書の §6 Process Flows & Interaction Surface、すなわち View Inventory（§6.2）、Navigation Map（§6.3）、Key UI States（§6.4）、Per-Story Interaction Flow（§6.5）を読み、このデザイン仕様書の出発点として使用します。

  • 仕様書の用語をそのまま再利用します — §6.2 の UX ロールに基づくビュー名と、§6.4 の観測可能な状態名をそのまま引き継ぎます（このスキルの「Observable State Definitions」テーブルにある Default / Loading / Disabled / Error / Empty / Success の用語は共通言語です）。仕様書ですでに定義されている名称や分類を変更してはいけません。2 つの成果物で用語が一致しないと、ナビゲーション可能なハブが機能しなくなります。
  • 詳細化し、逸脱や矛盾は避けます。 仕様書は技術に依存しない内容のままとし、このデザイン仕様書では仕様書の意図を引き継いだうえで、レイアウト、トークン、ピクセル単位の詳細など、視覚的な忠実度を高めます。§6.5 の各ステップと §6.4 の各状態を具体的な視覚表現に対応付け、仕様書で定義済みの US-／OP-／BR- の論理 ID 参照を維持します。
  • この連携は、以下に記載された SYNC:ui-intent-layer 契約に基づきます。詳細はそのブロックを参照してください。ここでは繰り返し説明しないでください。

スキップできるのは、基準となる Feature Spec が存在しない場合に限ります（その場合は、元の PBI／ストーリーをもとにインタラクションの枠組みを作成してください）。どちらに該当するか明記してください。

  1. 入力元を読み取り、種類に応じて振り分ける

    検出された入力検出方法対応
    Figma URLテキスト内に figma.com/design または figma.com/file がある$figma-design を有効化してコンテキストを抽出し、その後続行する
    画像／スクリーンショットプロンプトに画像ファイルが添付されているvisual analysis tooling を使用してデザインガイドラインを抽出し、その後続行する
    手描きのワイヤーフレーム画像に「wireframe」または「sketch」のキーワードがある--mode=wireframe を実行する（内部用。「Mode: wireframe」セクションを参照）
    PBI／ストーリーのテキスト受け入れ基準が含まれているテキストから UI 要件を抽出し、続行する
    口頭／テキストによる要件画像、URL、PBI がないユーザーに確認してから続行する

視覚的な入力がある場合は、仕様書の生成に進む前に、必ず最初にデザインのコンテキストを抽出してください。

  1. 仕様書の複雑さを判断する

    単一のフォームまたはシンプルなコンポーネントの場合 → クイックスペック（セクション1～4のみ）
完全なページまたは複数のコンポーネントで構成されるビューの場合 → フルスペック（全7セクション）
複数ページにわたるフローの場合 → フルスペック + フロー図

  2. コンポーネント一覧を作成する

    • 必要な UI コンポーネントをすべて列挙します
    • 再利用可能なコンポーネントと機能固有のコンポーネントを特定します
    • 共有コンポーネントライブラリまたはデザインシステムに既存のコンポーネントがあれば記載します

  3. 状態とインタラクションを定義する

    • デフォルト、ホバー、アクティブ、無効、エラー、読み込み中、空の各状態
    • ユーザー操作（クリック、ドラッグ、キーボードショートカット）
    • トランジションとアニメーション

  4. デザイントークンを抽出する

    • 色、タイポグラフィ、余白、シャドウ、ボーダーの角丸
    • 可能な場合は既存のデザインシステムのトークンを参照します

  5. レスポンシブ動作を記録する

    • モバイル（320～767px）、タブレット（768～1023px）、デスクトップ（1024px 以上）
    • 各ブレークポイントでの変更点（レイアウト、表示、サイズ）
    • 小画面での最低要件（明示的に仕様に記載すること）： モバイルでもレイアウトが使いやすい状態を保つ必要があります。推奨はリフローです（行を flex-wrap にする／row → column にする、グリッドを1列にする）。コンポーネントの性質上、実際にリフローできない場合（データテーブル、キャンバス、幅の広いグリッド）は、許容される代替策として min-width／min-height と overflow: auto によるスクロールを指定します。スクロールは許容されます。必須要件は、何も壊れないこと（コンテンツや操作部が切れたり、画面外に隠れたり、操作できなくなったりしないこと）です。モバイルで動作させるために大規模な再設計が必要な場合は、全面的な書き換えを想定せず、ユーザーに伝えてください。

  6. 成果物を保存する — 成果物の種類に応じてファイル名の形式を選びます：

    • デザイン仕様書：team-artifacts/design-specs/{YYMMDD}-designspec-{feature-slug}.md
    • アクセシビリティ監査：team-artifacts/design-specs/{YYMMDD}-ux-audit-{feature-slug}.md
    • 単一コンポーネントのドキュメント：team-artifacts/design-specs/{YYMMDD}-ux-component-{component-name}.md

  7. 該当する Feature Spec が存在する場合は、そこへリンクを戻す。 成果物を保存した後も、仕様書をナビゲーションのハブとして維持します。docs/specs/** にある該当する Feature Spec を開き、そのフロントマターの design_spec: キーに、このデザイン仕様書の保存先パスを設定します（キーがない場合は追加し、古い場合は更新します）。モックアップも作成した場合（例：$pbi-mockup を使用）、同様に mockup: キーを設定します。編集するのはフロントマターのみです。§1～§8 の仕様書本文には一切手を加えないでください。これにより、デザイン仕様書が存在するのに、そのパスが仕様書の design_spec: フロントマターに記録されていない場合に失敗する artifact-review --type=design のリンクバックゲートを満たせます。該当する Feature Spec が存在しない場合（デザイン仕様書が単独である場合）のみ、この手順を省略し、その旨を記載してください。

役割のコンテキストと成果物のパス（正式）

team-artifacts/design-specs/ への書き込みに適用されます。

  • 現在の役割： ui-ux-designer · スキル： design-spec
  • パス： team-artifacts/design-specs/ · 種類： designspec · 役割トークン： ux
  • テンプレート： .claude/docs/team-artifacts/templates/design-spec-template.md
  • 命名規則： {YYMMDD}-ux-{type}-{slug}.md（一般的な成果物パスの形式：{YYMMDD}-{role}-{type}-{slug}.md）
  • コンテキスト： デザイン仕様 — コンポーネントの状態、デザイントークン、アクセシビリティ要件を含めます。
  • 品質チェックリスト： - [ ] すべての状態を記載 · - [ ] デザイントークンを指定 · - [ ] アクセシビリティに関する注記を含める · - [ ] レスポンシブのブレークポイントを定義

モード：wireframe（画像 → 仕様）

--mode=wireframe を指定して実行します（または、手描きのワイヤーフレーム、デジタルワイヤーフレーム、UI スケッチが入力の場合）。このモードは入力アダプターです。画像を分析した後、通常の仕様セクション（出力形式）へ進み、M1-M5/M7 準拠ゲートを通過します。ワイヤーフレームから仕様への変換を正式に担うのは design-spec です。

入力の振り分け（ワイヤーフレーム）
入力検出アクション
手描きスケッチの写真大まかで有機的な線がある画像ワイヤーフレーム用のプロンプトで分析する（このモード）
デジタルワイヤーフレーム明確な線や図形がある画像ワイヤーフレーム用のプロンプトで分析する（このモード）
ワイヤーフレームツールのエクスポートExcalidraw/Balsamiq/MockFlow からの画像ワイヤーフレーム用のプロンプトで分析する（このモード）
Figma の URLテキスト内に figma.com がある代わりに $figma-design に振り分ける
アプリのスクリーンショット実際のデータを含む洗練された UI代わりに $design --mode=screenshot に振り分ける
ワイヤーフレーム分析

以下のプロンプトを使って visual analysis tooling を使用します。

プロンプト 1：レイアウトの抽出 — 「このワイヤーフレーム画像を分析してください。（1）ページのレイアウト領域（ヘッダー、サイドバー、メイン、フッター）、（2）おおよその位置と種類（ボタン、入力欄、テーブル、カード、ドロップダウン、モーダル、タブ）を含むすべての UI 要素、（3）コンテンツの階層（主要な要素と副次的な要素）、（4）インタラクティブな要素、（5）テキストラベルや注釈、（6）ナビゲーションパターンを特定してください。」

プロンプト 2：コンポーネントの特定 — 「ワイヤーフレームに含まれる、種類の異なる UI コンポーネントをすべて列挙してください。それぞれについて、説明的な名前を付け、複雑さ（プリミティブ＝単一の要素、複合＝グループ化された要素、セクション＝ページの領域）を分類し、目的を記してください。」

ワイヤーフレーム出力の生成

画像分析後、以下を生成します（下記の SYNC:ui-wireframe-protocol ブロックに従います）。

  1. ASCII ワイヤーフレーム — 罫線文字を使ってレイアウトを再現します
  2. コンポーネント一覧 — ティア分類（Common/Domain-Shared/Page）とともに列挙します
  3. 状態テーブル — ビューごとにデフォルト、読み込み中、空、エラーを記載します
  4. コンポーネント分解ツリー — 詳細レベルに応じて作成します（refine/story）
  5. レスポンシブ対応の提案 — レイアウトの複雑さに基づいて提示します

ワイヤーフレームから作成するすべての文章に対し、UI 仕様の M1-M5/M7 準拠ゲート（以下）を適用します。コンポーネント名はビジネスレベルにすること、コードのプロパティへの参照を含めないこと、論理 ID で機能ロジックに対応付けること、観測可能な状態遷移を記載すること、仕様から再構築できること、ビジネスで可視化される対象を扱うことが必要です。

ワイヤーフレームから作成する仕様には、同じデザイン原則に関する必須事項（以下）が適用されます。状態テーブル（項目 3）は、空・読み込み中・エラーの状態を最初に作成し（UI-1.5）、インタラクティブな要素ごとに 5 つすべてのインタラクション状態を網羅します（UI-5.2）。レスポンシブ対応の提案（項目 5）は、デバイス名ではなく、コンテンツの配置が崩れる箇所を基準にします（UI-4.4）。また、スケッチからタイプスケール、スペーシング単位、コントラストを判断できない場合（UI-2.5、UI-4.1、UI-3.1）、描画から測定した独自の値を作り出すのではなく、§4 に [UNVERIFIED — needs design-system mapping] と記録します。

対応付けられたビジネス操作

各インタラクティブなコンポーネントを、それが駆動する機能操作／ルールに対応付けた以下のテーブルを出力します（論理 ID を主軸とします。ワイヤーフレームだけでは判断できない場合は [UNVERIFIED — needs feature-spec mapping] と記します）。

インタラクティブなコンポーネントインタラクション（観測可能）機能操作／ルール（論理 ID）備考
主要ボタンクリック → フォームを送信OP-XX作成／更新操作を実行します
フィルタードロップダウン選択 → リストを再読み込みOP-XXクエリ／検索操作を実行します
行アクションメニュークリック → 確認ダイアログBR-XX認可ルールによって制御されます
ワイヤーフレームの出力形式
  • 形式 A：PBI セクション（デフォルト） — PBI／ストーリーテンプレートと互換性のある独立した ## UI Layout セクションを出力します（$pbi-mockup で使用）。
  • 形式 B：独立した仕様書 — team-artifacts/design-specs/{YYMMDD}-wireframe-spec-{slug}.md に出力します。
信頼度とレビュー（ワイヤーフレーム）
  • ワイヤーフレームの解釈について、必ず信頼度を表示してください（分析の精度は70～80％です）。
  • 実装に進む前に、必ず人によるレビューを推奨してください。
  • 信頼度が70％未満の場合：曖昧な要素について、ユーザーに直接質問して確認してください。

出力形式

# Design Spec: {Feature Name}

**Source:** {PBI/story reference}
**Date:** {YYMMDD}
**Status:** Draft | Review | Approved

## 1. Overview

{1-2 sentence summary of what this UI does}

## 2. Component Inventory

| Component | Type     | Source           | Notes                       |
| --------- | -------- | ---------------- | --------------------------- |
| UserCard  | New      | Feature-specific | Displays user avatar + name |
| DataTable | Existing | shared library   | Reuse with custom columns   |

## 3. Layout

{Description or ASCII wireframe of layout structure}

- Desktop: {layout description}
- Tablet: {layout changes}
- Mobile: {layout changes}

## 4. Design Tokens

| Token      | Value          | Usage                 |
| ---------- | -------------- | --------------------- |
| $primary   | #1976D2        | Action buttons, links |
| $text-body | 14px/1.5 Inter | Body text             |
| $gap-md    | 16px           | Section spacing       |

## 5. States & Interactions

| Element  | Default    | Hover      | Active     | Disabled         | Error |
| -------- | ---------- | ---------- | ---------- | ---------------- | ----- |
| Save btn | Blue/white | Darken 10% | Scale 0.98 | Gray/50% opacity | --    |

## 6. Accessibility

- Keyboard navigation order
- ARIA labels for interactive elements
- Color contrast compliance notes

## 7. Open Questions

- {Any unresolved design decisions}

デザイン原則に関する必須要件（仕様書の各セクション）

仕様書は、40の UI／UX デザイン原則（UI-1.1～UI-9.4、以下の SYNC:ui-ux-design-principles ブロック）を継承可能にする文書です。後続の実装者は仕様書に記載された内容を実装するため、記載されていない条項は実装されません。このスキルが出力するすべての仕様書には、指定された出力形式のセクションにこれらの必須要件を含める必要があります。プロジェクトのデザインシステム文書は、これらの条項よりも優先されます。実際に矛盾がある場合は、いずれか一方を黙って採用するのではなく、両方の内容をユーザーに提示してください。

仕様セクションセクションに必ず盛り込むべき条項上の要件
§1 概要画面の主な焦点を1つ明記し（UI-1.1）、対象となる画面（ウェブ／モバイル／両方）を示して、モバイルに関する条項（UI-8.1～UI-8.4）を適用するか、明示的に除外するかを定めます。
§3 レイアウトネストした枠線ではなく、近接性と共通する整列エッジに基づいてグループ化します（UI-1.3、UI-1.4）。ブレークポイントはデバイス名ではなく、コンテンツが機能しなくなる箇所を根拠として設定します（UI-4.4）。
§4 デザイントークン個別サイズを設けず、名前付きの6段階で文字サイズのスケールを宣言します（UI-2.5）。本文はウェブで16px／モバイルで17pxとし、14px未満は絶対に使用しません（UI-2.2）。1行の文字数は45～75文字とします（UI-2.3）。行送りは本文で1.5、ディスプレイ文字で1.1～1.2とします（UI-2.4）。書体は最大2種類、ウェイトは最大3種類とします（UI-2.1）。間隔の基準単位を1つ宣言します。基準は4pxまたは8pxとし、すべての間隔をその倍数にします（UI-4.1）。間隔はコンテナーがギャッププロパティで管理します（UI-4.2）。内側のパディングは、次のグループとの間隔より狭くします（UI-4.3）。宣言されたスケールではなく、場当たり的な値を並べたトークン表は、この要件を満たしません。
§4 デザイントークン（色）すべてのトークンの組み合わせについて、コントラストの目標値と実測値を明記します。テキストは4.5:1、UIの境界は3:1とし（UI-3.1）、目視ではなく測定します。アクセントカラーは1つとし、用途も1つに限定します（UI-3.2）。ダークモードは反転ではなく、明るさを上げたサーフェスと、白を和らげたテキストとして仕様を定めます（UI-3.4）。
§5 状態とインタラクションコンテンツが表示された状態より先に、空・読み込み中・エラーの各状態を設計します（UI-1.5）。 インタラクティブ要素ごとに5つの状態（デフォルト、ホバー、フォーカス、アクティブ、無効）をすべて列挙し、該当する場合は読み込み中の状態も加えます（UI-5.2。後述の7状態の「コンポーネント状態チェックリスト」と整合させます）。結果の表示に時間がかかる場合でも、100ms未満で応答します（UI-5.1）。動きは150～250msのイーズアウトとし、動きを減らす設定に従います（UI-5.4）。確認より取り消しを優先し、確認を求めるのは取り消せない操作に限ります（UI-5.3）。フォームでは、ラベルを常に表示し、プレースホルダーはヒントとしてのみ使い、ラベルの代わりには絶対に使用しません（UI-7.2）。フォーカスが外れたときに検証し、修正方法のメッセージを該当フィールドの横に表示します（UI-7.3）。エラー、画面遷移、更新があっても、入力済みデータを絶対に失わせません（UI-7.5）。
§6 アクセシビリティフォーカスリングは常に表示します。背景と合わない場合はスタイルを変更し、絶対に取り除きません（UI-5.5）。色だけで意味を伝えることはありません（UI-3.3）。モバイルまたはタッチ対応の画面では、タップ対象を44×44pt以上とし、8px以上の間隔を設けます（UI-8.1）。主要なアクションは画面下部3分の1に配置します（UI-8.2）。ジェスチャーを唯一の操作手段にしません（UI-8.3）。セーフエリアと画面上のキーボードに配慮します（UI-8.4）。
§7 未解決事項意図的に逸脱するすべての条項について、逸脱を認めるプロジェクト文書またはユーザーの判断を明記します。文書化されていない逸脱は、スタイル上の選択ではなく、仕様の不備です。
すべての節の要件は、以下の M1〜M5／M7 ゲートを通過できるよう、観察可能な UX 言語で記述してください。CSS プロパティやフレームワークのプロパティではなく、画面上で確認できる結果を示してください。

機能にユーザー向けの表示がない場合に限りスキップし、単なる記載漏れではなく監査可能なスキップとなるよう、その旨を明記してください。

UI 仕様の M1〜M5／M7 準拠

ブロッキング条件については .claude/skills/shared/sdd-artifact-contract.md → 「AI-SDD Mandates (M1-M7)」を参照してください。UI 仕様は引き継ぎ前に、以下を満たす必要があります。

  • M1 — ビジネスレベルのコンポーネント名。 すべてのコンポーネントを UX 上の役割で命名してください（Primary Button、Secondary Button、Modal Dialog、Data Table、Dropdown、Toast など）。フレームワークのコンポーネントクラス名やライブラリのインポート名は絶対に使用しないでください。技術用語を含む文章は不合格です。
  • M2 — 文章中でコードのプロパティを参照しない。 動作と見た目を、平易な UX 言語で説明してください。コンポーネントの状態プロパティ、CSS クラス名、フレームワークのディレクティブ、セレクターを文章中で参照することは絶対に避けてください。これらは **Evidence**／[Source:] の記載箇所、フロントマター、Mermaid にのみ記述できます。
  • M3 — 論理 ID で相互参照する。 機能ロジックによって制御される動作については、すべて、その制御元となる操作またはルールを論理 ID（OP-／BR-／FR-）で示してください。UI の動作はハンドラーのコードではなく、機能仕様に紐付けます。[Source: namespace/service/id] の抽象アンカーは Evidence の記載箇所に厳密に限定し、物理コードの位置やリポジトリルートからのパスは記載しないでください。
  • M4 — テスト可能で曖昧さのない動作。 すべての状態と操作は、解釈が一つに定まり、観察可能な完了マーカーを備えている必要があります。「適切に処理する」「フィードバックを表示する」といった曖昧な表現は、具体的に観察できる結果に置き換えてください。
  • M5 — 仕様だけで再構築できること。 コードベースに関する知識がまったくない読者でも、仕様だけをもとに任意のフレームワークでこの UI を再構築できなければなりません。ソースコードを読まないと解釈できないマーカーは M5 不合格です。視覚的またはテキスト上で観察できる内容として書き直してください。
  • M7 — ビジネス上の可視性。 UI 仕様はビジネスツリーの成果物です。各ケースの BODY にデモテストを適用してください。「関係者は何が変わったとわかるか？」 に答えられない場合は、TECHNICAL-ONLY として不合格です。すべての Given はユーザーが用意できる状態、すべての When はユーザーが実行できる操作、すべての Then はユーザーが確認できる結果でなければなりません。ハンドラーが実行される、コンシューマーが受け取る、ジョブが起動する、データが同期される、といった呼び出しを表す When や、スキーマ／型／NULL 許容性／呼び出し回数を主張する Then は不合格です。タイトルや ID ではなく、BODY を判定してください。⚠️ ユーザーが確認できる UI 状態はビジネス上のものであり、M7 に合格します。スピナー、空のプレースホルダー、エラー枠、無効化されたコントロールはいずれもデモ可能な結果であり、技術的なケースではありません。不合格となるのは、呼び出しの記述やスキーマの断定を含むケースのみです。

M1 と M7 は異なるゲートです。 M1 が規定するのは用語、M7 が規定するのは題材です。技術的なケースでも、技術用語を一切使わない完璧な文章であれば M1 は満たしつつ、M7 には違反します。「ビューに同期済みレコードが正しく反映される」はフレームワーク名を含まないため M1 に合格しますが、ビジネスらしい装いをした技術的なケースであることに変わりはありません。この乖離こそ、ビジネス仕様が形骸化する最もよくある原因です。使われている言葉ではなく、ユーザーが何を確認できるかを考えてください。

観測可能な状態の定義

すべての状態は、CSS クラスやコンポーネントの状態プロパティではなく、ユーザーが目で確認できるもの（色、アイコン、位置、テキスト）、ビジネス上の意味、およびその状態を引き起こす操作やルールで定義してください。

状態観測可能な視覚的マーカービジネス上の意味トリガーとなる操作／ルール（論理 ID）
Defaultプライマリの塗りつぶし色、有効なラベル、スピナーなしアクターが操作を実行できる状態OP-XX（初期状態）
Loadingラベルがスピナーアイコンに置き換わり、操作不可操作中で、結果を待っている状態OP-XX（リクエストを送信）
Disabled抑えた色／グレーの塗りつぶし、薄いラベル、ポインターの操作感なし前提条件が満たされていない／アクターに権限がないBR-XX（認可またはガードルール）
Errorエラー色の境界線、インラインメッセージ、警告アイコン操作が拒否された、または検証に失敗した状態BR-XX（検証ルール）
Emptyプレースホルダーのイラストと案内テキスト、データ行なし現在のビューにレコードがない状態OP-XX（クエリの結果が 0 件）
Success確認トースト／チェックマーク、表示データが更新される操作が完了し、永続化された状態OP-XX（操作が成功）

コンポーネントの状態チェックリスト

すべてのインタラクティブコンポーネントについて、CSS クラスやフレームワークのプロパティではなく、観測可能な外観とビジネス上の意味に基づいて、以下の 7 つの状態をすべて記述してください（M2 を参照）。

  • Default — 通常時の外観。アクターが操作を実行できる状態
  • Hover — ポインターを重ねたときの操作感の変化（カーソル／浮き上がり／色の変化）
  • Active — 操作中の押下／操作中フィードバック
  • Focus — キーボード操作時のアクセシビリティ対応フォーカスインジケーター（視認可能なリング／アウトライン）
  • Disabled — 抑えた表示／操作不可。前提条件または権限が満たされていない状態
  • Error — インラインメッセージと警告を示す視覚的な手掛かりを伴う、検証／操作の失敗
  • Loading — 処理中のインジケーター（スピナー／スケルトン）。操作不可

アクセシビリティ監査（WCAG 2.1 AA）

アクセシビリティ監査の成果物として、このチェックリストレポートを作成し、{YYMMDD}-ux-audit-{feature-slug}.md として保存してください。

## Accessibility Audit: {Feature}

**Date:** {Date}
**Auditor:** {Name}
**Standard:** WCAG 2.1 AA

### Criteria Checklist

#### Perceivable

- [ ] 1.1.1 Non-text Content: Alt text for images
- [ ] 1.3.1 Info and Relationships: Semantic HTML
- [ ] 1.3.2 Meaningful Sequence: Logical reading order
- [ ] 1.4.1 Use of Color: Not sole means of conveying info
- [ ] 1.4.3 Contrast (Minimum): 4.5:1 text, 3:1 large text
- [ ] 1.4.4 Resize Text: Readable at 200% zoom
- [ ] 1.4.11 Non-text Contrast: 3:1 for UI components

#### Operable

- [ ] 2.1.1 Keyboard: All functions keyboard accessible
- [ ] 2.1.2 No Keyboard Trap: Can navigate away
- [ ] 2.4.1 Bypass Blocks: Skip navigation available
- [ ] 2.4.3 Focus Order: Logical tab sequence
- [ ] 2.4.4 Link Purpose: Clear from link text
- [ ] 2.4.6 Headings and Labels: Descriptive
- [ ] 2.4.7 Focus Visible: Clear focus indicator

#### Understandable

- [ ] 3.1.1 Language of Page: lang attribute set
- [ ] 3.2.1 On Focus: No unexpected context change
- [ ] 3.2.2 On Input: No unexpected context change
- [ ] 3.3.1 Error Identification: Clear error messages
- [ ] 3.3.2 Labels or Instructions: Form labels present

#### Robust

- [ ] 4.1.1 Parsing: Valid HTML
- [ ] 4.1.2 Name, Role, Value: ARIA where needed

### Issues Found

| #   | Criterion | Issue | Severity | Recommendation |
| --- | --------- | ----- | -------- | -------------- |
| 1   |           |       | P1/P2/P3 |                |

### Audit Status: PASS / FAIL / CONDITIONAL

**Remediation Priority:**
{List items by severity}

例

例 1：シンプルなフォーム仕様

入力：「顧客オンボーディングフォームのデザイン仕様」

**出力：**セクション 1〜4 で構成されるクイック仕様。フォームフィールド（名前、メールアドレス、会社名、プラン階層のドロップダウン）、検証ルール、送信／キャンセル操作、モバイルでの縦積み表示の挙動を記載します。

例 2：複雑なダッシュボード仕様

入力：「ドラッグ＆ドロップ可能な列を備えた注文パイプラインダッシュボードのデザイン仕様」

**出力：**カンバンボードのレイアウト、注文カード（コンポーネント一覧）、ドラッグ＆ドロップ操作、列の状態（空、データあり、上限超過）、フィルターバー、モバイルでリスト表示に切り替えるレスポンシブ動作、キーボードによるドラッグ操作のアクセシビリティを網羅した完全仕様。

関連スキル

スキル代わりに使用する場面
figma-designFigma デザインから仕様を抽出する
design --lane=marketingマーケティング／クリエイティブ UI を構築する
design --lane=productプロダクト UI（ダッシュボード、アプリ）を構築する
web-design-guidelines既存 UI の準拠状況を確認する

推奨ワークフロー

必須・重要・必ず注意 — 例外なし： すでにワークフローに参加していない場合は、必ずユーザーに直接確認してください。タスクの複雑さを判断したり、「省略しても問題ないほど簡単だ」と決めつけたりしてはいけません。ワークフローを使うかどうかを決めるのはユーザーであり、あなたではありません。

  1. デザインの手順を実行する（推奨） — $design-spec → $design --lane=product（プロダクトの UI）または $design --lane=marketing（マーケティング／クリエイティブ）→ $workflow-review-changes
  2. $design-spec を直接実行する — このスキルを単独で実行します

［重要］ 作業を始める前に、ファイルの読み取りも含め、すべての作業を小さなタスクに分割して、タスクの追跡を行ってください。長いファイルによるコンテキストの喪失を防げます。簡単な作業の場合、AI は必ず省略するかどうかをユーザーに確認してください。

［ブロッキング］新規または更新する画面のデザインや仕様を作成する前に、既存の UI を把握してください。 ワイヤーフレーム、モックアップ、画面デザイン、UI 仕様を作成する前に、次を行ってください。

  1. 関連する既存 UI を調査する — プロジェクトを検索し、この機能またはその領域ですでに使われている画面、ページ、コンポーネントを探します（デザインシステムのドキュメントと実際のコンポーネント一覧を参照してください）。
  2. 関連するフローを整理する — 新しい画面へのリンク、埋め込み、取り込み、または新しい画面への移動・新しい画面からの移動がある機能をすべて特定し、新しい画面が既存のフローに適合するよう、画面への入口と画面からの出口をたどります。
  3. 新規作成より再利用を優先する — 既存のコンポーネント、パターン、レイアウト規則を優先し、新しいコンポーネントを追加する場合は、既存のものでは不十分な理由を説明します。
  4. 調査結果を記録する — 現在の UI システムに忠実に沿ったデザインを後工程で作成できるよう、該当する既存の画面・コンポーネントと関連するフローを成果物に記載します。

省略できるのは機能がバックエンドのみで UI がない場合に限ります。その理由を明記してください。

［ブロッキング］UI を含むすべての仕様に、技術に依存しない UI／UX の意図レイヤーを記載してください。読者が技術名を知らなくても、機能の動作をイメージできる必要があります。 機能にユーザーインターフェースがある場合、仕様には必ずインタラクション画面セクションを含めてください。これにより、API だけでなくアプリケーション全体をどの技術スタックでも再構築できます。

  1. 画面一覧 — 各画面を UX 上の役割と目的（例：「項目の一覧」「項目の編集」「確認ステップ」）で挙げ、提示する情報を説明します。実装上の名前ではなく、役割で説明してください。
  2. ナビゲーションマップ — ユーザーが各画面間を移動する方法を説明します。入口、遷移、出口を示し、この画面群がシステム内の関連機能とどうつながるかをたどります。
  3. ユーザーが認識できる主要な UI 状態 — 各画面でユーザーが認識できる状態（空、読み込み中、データ表示、エラー、成功、権限不足など）を、どのように描画されるかではなく、ユーザーにどう見えるかで説明します。
  4. ストーリーごとのインタラクションフロー — 各ユーザーストーリーについて、意図から結果に至るまでのクリックや操作の手順を示し、仕様内ですでに定義されている論理 ID（US-／OP-／BR-）と相互参照します。
  5. 対応するデザイン成果物との連携 — 詳細なビジュアルの再現度（レイアウト、トークン、ピクセル単位の詳細）は仕様に含めず、リンクされた design-spec／モックアップに記載します。仕様を移動の起点として保てるよう、対応する成果物のパスを仕様のフロントマターに記録します。

M1 クリーン（譲れない要件）： 本文にはフレームワーク、ルート／URL、CSS、コンポーネントクラス名を一切記載しません。記載するのは役割、情報、状態、フローのみです。技術的な詳細は対応するデザイン成果物に記載し、ここには含めないでください。

省略できるのは機能がバックエンドのみで UI がない場合に限ります。その理由をセクション内に明記してください。 AI のミス防止 — あらゆるタスクで避けるべき失敗パターン：

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

UI システムのコンテキスト — .ts、.html、.scss、.css ファイルに関わるすべてのタスクが対象です：

実装前に必ず以下を注意深く読んでください：

  1. docs/project-reference/frontend-patterns-reference.md — コンポーネントの基底クラス、ストア、フォーム
  2. docs/project-reference/scss-styling-guide.md — BEM 手法、SCSS 変数、ミックスイン、レスポンシブ対応
  3. docs/project-reference/design-system/README.md — デザイントークン、コンポーネント一覧、アイコン

プロジェクト固有のパスについては docs/project-config.json を参照してください。 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 / 文書化するプロジェクトが意図的に逸脱している箇所を記録し、優先されるドキュメントが記録上の判断基準となるようにします。

省略できるのは変更にユーザー向けの画面がない場合（バックエンドのみ、ツール、ドキュメント）に限ります。省略を明示し、見落としではなく監査可能な判断として記録します。 UI ワイヤーフレームプロトコル — ワイヤーフレームから実装までのフロー：（1）デザイン入力を処理します（ビジュアル分析ツールを使った Figma／スクリーンショット／スケッチ）。（2）罫線文字を使って ASCII ワイヤーフレームを作成します。（3）コンポーネント一覧を作成し、階層を分類します（共通／ドメイン共有／ページ）。（4）状態を記録します（デフォルト／読み込み中／空／エラー）。（5）デザイントークンに対応付けます。（6）レスポンシブのブレークポイントを定義します。新しいものを作成する前に、既存のコンポーネントライブラリを検索します。スキルレベルに応じて段階的に詳細化します（アイデア＝スケッチ、ストーリー＝完全なツリー＋仕様）。

批判的思考の姿勢 — 批判的思考と逐次的思考を適用します。あらゆる主張には追跡可能な証拠が必要です。行動に移すのは確信度が80％を超える場合に限ります。 ハルシネーション対策： 推測を事実として示してはいけません。あらゆる主張の出典を示し、不確実性は率直に認め、出力に誤りがないか自己確認し、独立して相互参照し、自分の確信度を疑ってください。証拠のない確信は、あらゆるハルシネーションの根源です。

  • 必須・重要・要対応 UI を変更する前に、frontend-patterns-reference、scss-styling-guide、design-system/README を必ず読んでください。

  • 要対応 ユーザー向けのあらゆる画面に、40 の UI/UX デザイン原則（UI-1.1–UI-9.4）を適用してください。焦点は1つに絞る、近接する要素をグループ化する、空・読み込み中・エラーの状態を最初に設計する（§1）・フォントファミリーは最大2種類、本文はウェブで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）。プロジェクトの design-system ドキュメントは、これらの条項より優先されます。実際に矛盾する場合はユーザーに確認し、決して黙って解決しないでください。調査結果はすべて UI-<clause> と file:line を併記して引用してください。ユーザー向けの画面に変更がない場合に限り、適用を省略し、その旨を明記してください。

重要・要対応 ワイヤーフレームプロトコルに従ってください。ASCII ワイヤーフレーム、階層付きコンポーネント一覧、状態テーブル、デザイントークン、レスポンシブのブレークポイントを用意してください。

  • 必須 UI を含む仕様では、技術に依存しないインタラクションサーフェス層（View Inventory ＋ Navigation Map ＋観測可能な UI States ＋ US-/OP-/BR- をたどれるストーリーごとのフロー）を作成・維持してください。深いビジュアルの忠実度は、frontmatter に記録したリンク先の design-spec／モックアップで表現してください。フレームワーク／ルート／CSS／コンポーネントクラス名は一切記載しないでください。バックエンドのみの機能である場合に限り、理由を明記して省略できます。

要対応 批判的思考と逐次的思考を適用してください。あらゆる主張には、適切で追跡可能な根拠が必要です（リポジトリ／コードに関する主張は file:line、調査・製品・コンテンツ・ドキュメントに関する主張はソース URL または成果物のセクション）。行動に移すのは確信度が80％を超える場合に限ります。確信度が60％未満の場合は推奨しないでください。ハルシネーション対策：推測を事実として示さず、不確実性は率直に認め、独立して相互参照し、自分の確信度を疑ってください。

要対応 AI の誤りを防止してください。生成した内容を証拠と照合し、削除や名前変更の前に後続の参照先を追跡し、影響を受けるすべての出力を検証し、コンテキストを失った後はファイルを読み直し、行動を起こす前に曖昧さを明らかにしてください。

Prompt-Enhance Closing Anchors

重要・必ず注意 このスキルで宣言されているステップの順序に従ってください。ユーザーの明示的な承認なしに、ステップを省略、並べ替え、または統合してはなりません。 重要・必ず注意 各ステップ／サブスキルの呼び出しでは、実行前に in_progress に設定し、実行後に completed に設定してください。 重要・必ず注意 省略したステップにはすべて明確な理由を記載してください。完了したステップにはすべて簡潔な証拠を記載してください。 重要・必ず注意 Task ツールが利用できない場合は、ステータスを同期した同等のステップごとの計画トラッカーを維持してください。

プロジェクトプロトコルオーバーレイ — このスキルを実行する前に、このスキルに適用される 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 にある一致した本文のみを読み取り、本文が存在しない、または形式に不備がある場合は報告してください。再構成してはなりません。オーバーレイは追加のみであり（このスキル独自のルールを置き換えることはありません）、概要であり、権限を引き上げるものではありません。同じ具体性で矛盾する場合はユーザーに提示してください。

クロージングリマインダー

重要・必ず注意 目標： 要件／PBI／ストーリー／ワイヤーフレームから、技術に依存しない構造化された UI/UX 設計仕様を作成します。これにより、開発者は任意の技術スタックで UI を再構築できます。すべてのコンポーネント、状態、デザイントークン、レスポンシブルール、アクセシビリティ要件を文書化し、適用される Feature Spec にリンクしてください。

重要・必ず注意 主なステップ（どれも忘れないでください）：

  • まず Step 0–0b — 既存の関連 UI を調査し、接続されたフローをマッピングします（§1 に記録）。基準となる Feature Spec の §6 をもとにし、そのビュー／状態の用語をそのまま再利用してください。理由：既存のものを作り直したり、仕様の用語を改名したりすると、ナビゲーション可能なハブが壊れます。

  • Step 1–2 — 入力の種類に応じて処理を振り分けます（Figma→$figma-design、画像→視覚分析、ワイヤーフレーム→--mode=wireframe、PBI／テキスト→抽出）。その後、複雑さに応じて Quick（§1–4）または Full（§1–7）を設定します。

  • Step 3–6 — コンポーネント一覧（新規／既存）、7 つの状態すべてとインタラクション、デザイントークン（デザインシステムを再利用）、レスポンシブのブレークポイントを作成します。

  • Step 7–8 — team-artifacts/design-specs/ に保存し、基準となる Feature Spec の design_spec:／mockup: フロントマターを保存先パスに設定します（フロントマターのみ）。理由：これがないとリンクバックのゲートを通過できません。

  • M1–M5 ゲート（ブロッキング） — ビジネスレベルのコンポーネント名、本文でのコードのプロパティ参照なし、論理 ID（OP-／BR-／FR-）による動作の相互参照、各状態につきテスト可能な解釈を 1 つ、仕様書のみで再構築可能。理由：技術に依存する仕様では、別の技術スタックで再構築できません。 有効なプロトコル（このスキルに含まれる SYNC／共有ブロックの簡潔な要約）：

  • AI Mistake Prevention： 生成した内容を根拠と照合し、後続の参照をたどり、影響を受けるすべての出力を検証し、コンテキスト喪失後に読み直し、曖昧さを明示します。

  • UI System Context： UIを変更する前に、frontend-patterns、scss-styling、design-systemを読みます。

  • UI Wireframe： ASCIIワイヤーフレーム、階層化されたコンポーネント一覧、状態テーブル、トークン、レスポンシブのブレークポイントを用意します。

  • Critical Thinking： 主張ごとに file:line の根拠をたどり、確信度が80%を超えてから実行します。

  • 必須・重要・必ず注意 作業を始める前に、タスク追跡を使って作業を小さなTODOタスクに分割します

  • 必須・重要・必ず注意 新しいコードを作成する前に、コードベースを検索して3つ以上の類似パターンを確認します

  • 必須・重要・必ず注意 すべての主張について file:line の根拠を示します（実行の確信度は80%超）

  • 必須・重要・必ず注意 作業の品質を検証する最終レビューのTODOタスクを追加します

  • 必須・重要・必ず注意 40のUI/UX Design Principles（UI-1.1～UI-9.4）を仕様の各セクションに引き継ぎ、実装者にも適用されるようにします。§5では空・読み込み中・エラーの状態を最初に定義し（UI-1.5）、インタラクティブ要素ごとに5つすべてのインタラクション状態を列挙します（UI-5.2）。§4では、個別の値ではなく6段階のタイプスケール（UI-2.5）と、4/8pxの単一スペーシング単位（UI-4.1）を明記し、コントラスト目標を測定して記載します（テキストは4.5:1／境界線は3:1、UI-3.1）。§6ではフォーカスリングを常に表示し（UI-5.5）、色だけに頼らず（UI-3.3）、タッチ面では44×44pt以上のターゲットと画面下部3分の1への主要操作の配置を確保します（UI-8.1、UI-8.2）。§7では意図的な逸脱をすべて記録します。理由：このスキルを離れた後、明記されていない条項は実装されない条項になるためです

合理化の防止：

回避の言い分反論
「既存UIの棚卸しとデザインは省略します」ステップ0はブロッキングです。まず既存の画面／フローを棚卸ししてください。そうしないと仕様が実際のUIと矛盾します。
「フレームワークのコンポーネント名のほうが明確です」M1/M2は不合格です。UX上の役割で命名してください。フレームワーク／CSS名はEvidence／frontmatter／Mermaidのみに記載します。
「仕様にはすでにビューが記載されています。再分割します」§6のビューと状態の語彙をそのまま再利用してください。名前を変更すると、たどれる仕様↔デザインハブが壊れます。
「ファイルを保存しました。完了です」ステップ8のリンクバックは必須です。仕様の design_spec: frontmatterを設定しないと、artifact-reviewで不合格になります。
「『フィードバックを表示する』でエラー状態を説明できます」M4は不合格です。曖昧な表現ではなく、各状態に観察可能な完了マーカーを1つ指定する必要があります。

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

[IMPORTANT] 作業の規模を分析し、始める前に多数の小さなTODOタスクへ体系的に分割してください。これは非常に重要です。

Hookless Prompt Protocol Mirror（自動同期）

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

コメント

Markdown 対応