fix-ui

Codex 互換性に関する注意：

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

Codex によるプロジェクト資料の読み込み（フックなし）

Codex では、Claude のフックによるドキュメントの自動注入は行われません。 コーディング、計画、デバッグ、テスト、レビューの際は、次の手順でプロジェクトのドキュメントを明示的に開いてください。

必ず読むもの：

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

状況に応じて読むもの：

• バックエンド／CQRS／API／ドメイン／エンティティの変更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• フロントエンド／UI／スタイリング／デザインシステム：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 仕様／テストケースの計画または TC マッピング：feature-docs-reference.md
• 結合テストの実装／レビュー：integration-test-reference.md
• E2E テストの実装／レビュー：e2e-test-reference.md
• コードレビュー／監査作業：code-review-rules.md に加え、変更対象のファイルに応じた上記のドメイン関連ドキュメント

すべてのドキュメントを無差別に読まないでください。まず docs-index-reference.md を確認し、その後、タスクに関連するファイルだけを開いてください。

簡単な概要

目標： レイアウト、スタイリング、レスポンシブ対応、表示上の不具合など、UI／UX の問題を診断して修正します。

ワークフロー：

1. 特定 — 表示上の問題を引き起こしているコンポーネント／テンプレートを特定します
2. 診断 — CSS／HTML／コンポーネントのロジックをたどって根本原因を見つけます
3. 修正 — 対象を絞った修正（SCSS、テンプレート、コンポーネントのロジック）を適用します
4. 検証 — レスポンシブ動作とブラウザー間の表示を確認します

主なルール：

• デバッグの心得：すべての主張に file:line の証拠を添えてください
• テンプレートの要素では常に BEM クラスを使用してください
• レイアウトの問題を修正する際は、レスポンシブのブレークポイントを確認してください

事前に読むもの（デザインシステム）： docs/project-config.json から designSystem.canonicalDoc と tokenFiles を読み込み、実際のトークン名（--brand-*、$brand-*）と標準のコンポーネントクラスを使って修正してください。値を独自に作らないでください。

デバッグの心得（必須）

懐疑的な姿勢を保ち、批判的思考と順序立てた思考を適用してください。すべての主張に、たどって確認した証拠と確信度（アイデアは 80％超）を示してください。

• 対応に着手する前に、実際のコードのトレースを通じて仮説を一つずつ検証してください。最初の仮説が正しいと決めつけてはいけません。最初の推測は原因ではなく、最も目につきやすいものに引きずられた結果であることが多いためです。
• 根本原因に関するすべての主張に、file:line の証拠を含めてください。
• コードのトレースで根本原因を証明できない場合は、「仮説であり、未確認」と明記してください。
• 前提を問い直してください。「本当にこれが原因なのか？」と考え、実際の実行経路をたどってください。
• 網羅性を確認してください。「ほかに影響している要因はないか？」と問い、関連するコード経路を確認してください。
• 証拠なしに「これで直るはず」と言わないでください。修正が、トレースで特定した根本原因に対処していることを検証してください。

⚠️ 必須：信頼度と根拠の確認

必須・重要・要注意： すべての主張について、根拠のリストと file:line の証拠を添えて、Confidence: X% を明記してください。 95% 以上：制限なく推奨 | 80～94%：注意事項を添える | 60～79%：不明点を列挙 | 60% 未満：停止して、さらに証拠を集める。

必須スキル（優先順位順）

1. ui-ux-pro-max - デザインインテリジェンスデータベース
2. web-design-guidelines - デザイン原則
3. frontend-design - 実装パターン

⚠️ 修正前に検証（必須）： UI の根本原因を特定したら、変更を加える前に、必ず調査結果と修正案をユーザーへの直接の質問で提示し、明示的な承認を得てください。黙って修正してはいけません。

ui-ux-designer サブエージェントを使って ./docs/design-guidelines.md を読み、分析したうえで、次の問題を修正してください。 $ARGUMENTS

ワークフロー

最初に：ui-ux-pro-max で検索し、背景とよくある問題を把握してください。

python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<product-type>" --domain product
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "<style-keywords>" --domain style
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux
python3 $HOME/.claude/skills/ui-ux-pro-max/scripts/search.py "z-index animation" --domain ux

ユーザーからスクリーンショットや動画が提供された場合は、ai-multimodal スキルを使って問題をできるだけ詳細に説明し、その説明から開発者が根本原因を容易に予測できるようにしてください。

1. ui-ux-designer サブエージェントを使って、手順に沿って修正を実装してください。
2. スクリーンショット撮影ツールと ai-multimodal スキルを使って、実装した修正のスクリーンショットを撮影してください（対象は正確な親コンテナーとし、ページ全体のスクリーンショットは撮らないでください）。その出力を適切な Gemini 分析スキル（ai-multimodal、video-analysis、または document-extraction）で分析し、デザインガイドラインに適合し、すべての問題に対処できていることを確認してください。

• 問題に対処できていない場合は、すべての問題が解決するまでこの手順を繰り返してください。

3. chrome-devtools スキルを使って実装した修正を分析し、デザインガイドラインに適合していることを確認してください。
4. tester エージェントを使って修正をテストし、コードをコンパイルして動作を確認したうえで、メインエージェントに報告してください。

• 問題やテストの失敗があった場合は、メインエージェントにすべて修正するよう依頼し、すべてのテストに合格するまで手順を繰り返してください。

5. プロジェクト管理とドキュメント： ユーザーが変更を承認した場合： project-manager と docs-manager のサブエージェントを並行して使い、プロジェクトの進捗とドキュメントを更新してください。
   • project-manager サブエージェントを使って、指定された計画ファイルのプロジェクト進捗とタスクのステータスを更新してください。
   • docs-manager サブエージェントを使って、必要に応じて ./docs ディレクトリ内のドキュメントを更新してください。
   • project-manager サブエージェントを使って、./docs/project-roadmap.md ファイルにプロジェクトのロードマップを作成してください。
   • 重要： 出力では、簡潔さを優先し、文法にこだわらないでください。 ユーザーが変更を拒否した場合： 問題点の説明をユーザーに求め、メインエージェントにすべて修正するよう依頼して、手順を繰り返してください。
6. 最終報告：

• 変更内容を要約してユーザーに報告し、簡潔に説明してください。利用を開始する方法を案内し、次のステップを提案してください。
• Git リポジトリへのコミットとプッシュを希望するかユーザーに尋ねてください。希望する場合は、git-manager サブエージェントを使ってコミットとプッシュを行ってください。
• 重要： 報告では、簡潔さを優先し、文法にこだわらないでください。
• 重要： 未解決の疑問がある場合は、報告の最後に列挙してください。

忘れないでください：

• ai-multimodal スキルを使って、必要に応じて画像をいつでも生成できます。

• 生成したアセットは必ず ai-multimodal スキルで読み取り、要件を満たしていることを確認してください。

• 背景の削除、調整、トリミングなどの画像編集には、必要に応じて media-processing スキルを使ってください。

• 重要： スキルカタログを分析し、タスクの実行中に必要なスキルを有効にしてください。

• 修正後は、必ず $prove-fix を実行してください — 変更ごとに信頼度スコア付きのコード証明トレースを作成します。省略してはいけません。

[IMPORTANT] 作業を開始する前に、タスク管理を使って、ファイルを読むタスクも含めてすべての作業を小さなタスクに分割してください。これにより、長いファイルによるコンテキストの喪失を防げます。単純なタスクの場合、AI は必ずユーザーにスキップしてよいか確認しなければなりません。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関係、サービス間の同期（業務エンティティ／モデルに関わるタスクで読む）（該当する場合は直接読むこと。フックによって注入された会話テキストに頼らないこと）

スキルのバリアント： $fix のバリアント — UI／UX の視覚的な問題の診断と修正。

終点から始点へのデバッガートレース — 複雑なバグ、検証の失敗、リグレッションの修正、動作を変えるコード、またはコードフローが不明確な場合は、修正を提案する前に、観測された最終状態から逆向きにたどってください。

1. フレーム 0：観測された最終状態 — ユーザーに表示された正確な出力、失敗したアサーション、ログ行、永続化された値、API レスポンス、レンダリングされた UI、または集計バケットを特定します。それを生成したリーダー／クエリ／レンダラーを、file:line の根拠とともに記録します。
2. 1 ホップずつ逆向きにたどる — 最終的なリーダー -> プロジェクション／キャッシュ／ストレージ -> ライター -> コンシューマー／ハンドラー／ジョブ -> プロデューサー／呼び出し元 -> 元のトリガーの順に追跡します。各ホップで、入力、変換、出力、所有者、根拠を記録します。
3. すべての入力経路を列挙する — リトライ、非同期処理、キャッシュ、バックグラウンド処理、別の UI／API 経路を含め、最終経路に書き込み可能な上流のプロデューサー／呼び出し元／イベント／ジョブをすべて見つけます。各経路に、検証済み、除外、未解明のいずれかを記します。
4. 仮説マトリックスを作成する — 考えられる各原因について、裏付ける根拠、反証する根拠、再現／検証方法、影響範囲、ステータス（primary、contributing、ruled out、latent）を記載します。競合する原因を明示的に解決するか、範囲を限定するまでは修正しないでください。
5. 修正を担うレイヤーを選ぶ — 不変条件の所有者と、すべての下流コンシューマーを保護する最も低い共通の箇所を特定します。不変条件を所有していない限り、症状が現れる箇所での修正は認められません。
6. 順方向の収束を証明する — 修正を選んだ後、始点 -> 終点を再度たどり、修正された状態がどのように観測された最終出力に届くかを示します。各根本原因を修正内容に対応づけ、各修正内容をテスト／証明に対応づけます。

以下が完了するまで作業は禁止です： 最終状態の特定 · 逆向きのトレースの記述 · すべての入力経路の列挙 · 仮説マトリックスの完成 · 修正を担うレイヤーの妥当性の説明 · テストに対応づけた順方向の収束の証明。

決して行わないこと： 最初に疑わしいコード経路から調査を始める。複数のプロデューサーをひとつの「フロー」にまとめる。読み取りモデルの実態を証明せずに、重複した症状を重複レコードとして扱う。除外した仮説を省略する。

ソース／テストの乖離チェック。 コーディング、修正、デバッグ、調査、テスト、レビューを行う場合、ソースの動作が変わったときは、影響を受けるユニット／統合／E2E テストを調べ、意図した動作に合わせてテストを変更すべきか、それともソースの変更が意図しないバグであり修正すべきかを、根拠に基づいて判断します。マイグレーションコードのテストは作成しないでください。スキーマ／データのマイグレーションは一度限りの実行経路であり、アプリケーションのコアロジックではありません。 AI のミス防止 — あらゆるタスクで避けるべき失敗パターン：

削除する前に、下流の参照を確認してください。 コンポーネントを削除すると、ドキュメントやコードの古さが連鎖的に広がります。削除する前に、参照しているすべてのファイルを洗い出してください。 AI が生成したコンテンツを実際のコードと照合してください。 AI は存在しない API、クラス名、メソッドのシグネチャをでっち上げることがあります。ドキュメントに記載したり参照したりする前に、必ず grep で実在を確認してください。 編集後は依存関係を最後までたどってください。 定義を変更しても、そこから派生する下流の変数や利用箇所を見落とすことがあります。必ず依存関係を最後までたどってください。 正しさを検証するときは、すべてのコードパスをたどってください。 コードが存在することを確認しても、それが実行されることの確認にはなりません。正常系だけでなく、早期リターン、エラー分岐、条件によるスキップも必ずたどってください。 デバッグでは、修正する前に「誰の責任か」を確認してください。 バグが呼び出し元（誤ったデータ）にあるのか、呼び出し先（誤った処理）にあるのかをたどってください。責任のあるレイヤーで修正し、症状が現れる箇所だけを修正してはいけません。 既存の値は意図的なものと考え、変更する前に理由を確認してください。 定数、上限、フラグ、パターンを変更する前に、コメントを読み、git blame を確認し、周辺のコードを調べてください。 最初の出力だけでなく、影響を受けるすべての出力を検証してください。 複数のスタックに関わる変更では、すべての出力を検証する必要があります。チェックが 1 つ成功しても、すべてが成功したことにはなりません。 全体を優先してデバッグし、目先のことにとらわれないでください。 あらゆる障害を調査するときは、まずすべての前提条件（設定、環境変数、DB 名、エンドポイント、DI 登録、データの前提条件）を列挙してください。その後、コードレイヤーの仮説を立てる前に、それぞれを証拠と照らして検証してください。 変更は必要最小限にし、差分テストを適用してください。 バグ修正では、変更する各行がバグに直接関係していることを確認してください。隣接するコードのスタイル変更や改善はしないでください。機能改善タスクでは、改善を実装し、その内容を明示的に伝えてください。 実装前に曖昧さを明らかにし、黙って解釈を決めないでください。 依頼に複数の解釈がある場合は、それぞれの作業量の見積もりを示して確認してください。全レコード対象、ファイルベース、またはより複雑な方法だと決めつけてはいけません。

根本原因のデバッグ — 推測と場当たり的な試行をせず、体系的に進めてください。

1. 再現 — 証拠（エラーメッセージ、スタックトレース、スクリーンショット）によって、問題が存在することを確認します。
2. 切り分け — 二分探索とグラフの追跡を使って、対象のファイル／関数／行を絞り込みます。
3. 追跡 — 入力から失敗箇所までのデータフローをたどります。推測せず、実際のコードを読みます。
4. 仮説の立案 — 確信度（％）を添えて仮説を立てます。それを裏付ける証拠と否定する証拠を示します。
5. 検証 — 対象を絞った grep／読み取りで仮説を検証します。一度に変更する変数は 1 つにします。
6. 修正 — 症状ではなく根本原因に対処します。グラフの connections を使い、修正によって呼び出し元が壊れないことを検証します。

絶対にしないこと： 証拠なしに推測する。原因ではなく症状を修正する。再現の手順を省く。

ネストされたタスクの展開に関する契約 — ワークフローのステップを呼び出す場合、[Workflow] ... の行は親コンテナーにすぎません。子スキルは引き続き、可視のフェーズタスクを作成します。

1. 最初に現在のタスクリストを取得します。一致するアクティブな親ワークフロー行がある場合は nested=true を設定して parentTaskId を記録し、ない場合は単独で実行します。
2. フェーズの作業を始める前に、宣言されたフェーズごとにタスクを 1 つ作成します。ネストされている場合は、サブジェクトに [N.M] $skill-name — phase を接頭辞として付けます。
3. ネストされている場合は、TaskUpdate(parentTaskId, addBlockedBy: [childIds]) で親タスクにリンクします。
4. オーケストレーターは、子スキルまたはサブエージェントを呼び出す前に、子スキルのフェーズ一覧を事前に展開し、ワークフロー行をリンクする必要があります。
5. 作業を始める前に、子タスクを正確に 1 つ in_progress にし、証拠を書き込んだ直後に completed にします。
6. すべての子タスクが完了するか、理由を明記して明示的にキャンセルされた後にのみ、親タスクを完了します。

次の条件を満たすまでブロックされます： 現在のタスクリストを取得し、子フェーズを作成し、ネストされている場合は親にリンクし、最初の子タスクを in_progress にすること。 プロジェクト参照ドキュメントの確認ゲート — タスク追跡の初期設定後、対象ファイルやソースファイルの読み取り、grep、編集、分析を行う前に実行してください。プロジェクトのドキュメントは、汎用的なフレームワークの前提より優先されます。

1. 対象範囲を特定します：ファイルの種類、ドメイン領域、操作内容。
2. トリガーに応じた必須ドキュメント：常に docs/project-reference/lessons.md；ドキュメント検索 docs-index-reference.md；レビュー code-review-rules.md；バックエンド/CQRS/API backend-patterns-reference.md；ドメイン/エンティティ domain-entities-reference.md；フロントエンド/UI frontend-patterns-reference.md；スタイル/デザイン scss-styling-guide.md + design-system/design-system-canonical.md；統合テスト integration-test-reference.md；E2E e2e-test-reference.md；機能ドキュメント/仕様 feature-docs-reference.md；アーキテクチャ/新規領域 project-structure-reference.md。
3. 存在する必須ドキュメントをすべて読みます。存在しないドキュメントは該当なしとしてスキップします。現在のコンテキストにドキュメントが含まれている証拠として、[Injected: <path>] などの会話テキストを信用しないでください。
4. 対象作業の前に、次のように明示します：Reference docs read: ... | Missing/not applicable: ...。

次の条件を満たすまで作業不可： 対象範囲の評価、必須ドキュメントの確認と読み取り、lessons.md の確認、参照の提示。

タスク追跡と外部レポートの保存 — 実行前に初期設定を行い、その後、対象作業やソース作業の前にプロジェクト参照ドキュメントを先読みしてください。

1. 対象ファイルの読み取り、grep、編集、分析を行う前に、小規模なタスクの内訳を作成します。コンテキストを失った場合は、まず現在のタスクリストを確認します。
2. 作業前に1つのタスクを in_progress にし、根拠を得たら直ちに completed にします。ステータス変更をまとめて行わないでください。
3. 計画/レビュー作業では、最初の所見を得る前に plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md を作成します。
4. 各ファイル/セクション/判断の後に所見を追記し、最後にレポートファイルをもとに内容をまとめます。
5. 最終出力には Full report: plans/reports/{filename} を記載します。

次の条件を満たすまで作業不可： タスクの内訳が存在し、計画/レビュー作業ではレポートのパスが宣言され、次の所見に進む前に最初の所見が保存されていること。

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

まずコードを理解する — 厳格なゲート：既存コードを読むまで、記述、計画、修正を行わないでください。

1. 類似パターンを3つ以上検索し（grep/glob）、根拠として file:line を示します。
2. 対象領域の既存ファイルを読み、構造、基底クラス、規約を理解します。
3. .code-graph/graph.db が存在する場合は、python .claude/scripts/code_graph trace <file> --direction both --json を実行します。
4. connections または callers_of で依存関係を把握し、対象に依存するものを確認します。
5. 重要なタスク（3ファイル以上）では、調査内容を .ai/workspace/analysis/ に記録します。
6. 実装前に分析ファイルを読み直します。記憶だけを頼りに作業してはいけません。 — 理由：長いコンテキストではファイルから内容がずれていきます。ファイルが正確な情報源です。
7. 既存パターンが機能している場合、新しいパターンを決して考案しないでください。完全に一致させるか、逸脱を記録します。 — 理由：異なるパターンがコードベースを分断し、将来の読者の作業を遅らせます。

次の条件を満たすまで作業不可： - [ ] 対象ファイルを読んだ - [ ] 3つ以上のパターンをgrepした - [ ] グラフをトレースした（graph.db が存在する場合） - [ ] 前提を証拠で検証した 根拠に基づく推論 — 推測は禁止です。すべての主張に証拠が必要です。

1. すべての主張について、file:line、grep の結果、またはフレームワークのドキュメントを引用してください
2. 確信度を明示してください：80% 超なら自由に実行、60～80% なら先に検証、60% 未満なら推奨しない
3. アーキテクチャの変更には、サービス間の検証が必要です
4. 「証拠が十分ではありません」は、妥当であり、想定される出力です

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

証拠なしでの使用は禁止： 「明らかに」「私は思います」「～のはずです」「たぶん」「これは～が原因です」 未完了の場合 → 次を出力してください："証拠が不十分です。確認済み：[...]。未確認：[...]" 見積もりフレームワーク — まずボトムアップで見積もり、SP は DERIVED とします。3日以上になりそうな場合は最小値と最大値の範囲で出力します。スタックに依存しません。基準：開発経験3〜5年、1日あたり生産的な作業時間6時間。AI見積もりでは Claude Code とプロジェクトのコンテキストを前提とします。

手法：

1. 影響範囲の確認（下記）— コードとテストのコストに影響します
2. フェーズに分解 → フェーズごとの時間を算出 → bottom_up_hours = Σ phase_hours
3. likely_days = ceil(bottom_up_hours / 6) × productivity_factor
4. リスクマージン（基本値＋加算分）を合計 → max_days = likely_days × (1 + margin)
5. min_days = likely_days × 0.9
6. likely_days ≥3 の場合は範囲で出力します。<3 の場合は単一の値でも構いません（ただしマージンは記録します）
7. man_days_ai = 同じ範囲 × AI による高速化率
8. story_points は SP-Days を使って likely_days から DERIVED します。決して見積もりの基準にしません。乖離が50%を超える場合は、ボトムアップの見積もりを優先します

生産性係数： 足場となるコード＋コード生成＋AI フックが充実している場合は 0.8 · 成熟した標準的な場合は 1.0 · パターンが弱い場合は 1.2 · 新規開発の場合は 1.5

コスト要因のヒューリスティック（作業種別の行を選ぶ前に適用）：

• UI が支配的なのは CRUD／業務アプリの場合です — バックエンドの1.5〜3倍（状態、バリデーション、レスポンシブ対応、アクセシビリティ、仕上げ）
• バックエンドが支配的なのは次の場合のみです： 複数集約にまたがる不変条件、サービス間コントラクト、スキーマ移行、複雑なクエリ／パフォーマンス、新しいイベントフロー

再利用か新規作成か（レイヤーごとの最重要要因）：

UI の段階	コスト
既存画面でコンポーネントを再利用	0.1-0.3d
既存画面にコントロール／列を追加	0.3-0.8d
コンポーネントを組み合わせて新しい画面を作成	1-2d
独自レイアウト／状態／バリデーションの新画面	2-4d
新しい共有／共通コンポーネント（テーマ適用、テスト済み）	3-6d+

バックエンドの段階	コスト
新しい場所でクエリ／ハンドラーを再利用	0.1-0.3d
既存ハンドラー／エンティティの小規模な更新	0.3-0.8d
既存リポジトリ／モデルに新しいクエリを追加	0.5-1d
既存集約に新しいコマンド／ハンドラーを追加（拡張）	1-2d
新しい集約／エンティティ（リポジトリ、バリデーション、イベント）	2-4d
新しいサービス間コントラクトまたはスキーマ移行	各 2-4d
複数集約にまたがる不変条件／複雑なドメインルール	3-5d

ルール： UI＋バックエンド＋テストの各段階を合計し、生産性係数を適用します。再利用できる場合は段階を省略できます — その旨を明記します。

テスト範囲の要因（test_count を明示的に算出してください。「＋テスト」という曖昧な記載が失敗原因の第1位です）：

要因	件数
正常系のユーザージャーニー	ストーリー／AC の主要フローごとに1件
状態遷移	到達可能な遷移 × 許可されたアクター
複数エンティティの状態の組み合わせ	state(A) × state(B) — 到達可能な組み合わせのみ。直積ではありません
認可マトリクス	(所有者、非所有者、権限昇格済み、未認証) × 各変更操作
バリデーションルール	必須フィールド／境界値／形式／フィールド間チェックごとに1件
UI の状態（新しい画面／ダイアログごと）	正常、読み込み中、空、エラー、一部表示 — 存在する状態のみ
異常系／不変条件	違反可能な業務ルールごとに1件

テスト段階（従来方式、セットアップ＋アサーション＋不安定さを含む）	コスト
1-5 件、フィクスチャを再利用	0.3-0.5d
6-12 件、新しいフィクスチャ1つ	0.5-1d
13-25 件、複数エンティティのセットアップ	1-2d
26-50 件、または新しい状態遷移の網羅	2-3d
>50 件、または E2E ジャーニー全体	3-5d

テストの倍率： 新しいフィクスチャ／シード用ハーネス +0.5d · サービス間／バスのアサーションは各 +0.3d · UI E2E は ×1.5 · 新しいロールごとに +1-2 件

影響範囲（必須の事前確認 — コードとテストの両方に影響）：

1. 直接変更するファイル／コンポーネント — 件数
2. そのうち「複雑なもの」（>500 LOC、複数ハンドラー、中心的、頻繁に変更されるもの）— 件数
3. 下流の利用者（呼び出し元、イベント購読者、サービス間）— 一覧
4. 共有／共通コードへの変更（複数アプリに影響）— yes/no
5. 回帰テストの範囲 — 再テストが必要な領域

ルール： 複雑な箇所に触れる場合は risk_factors に追加します。下流の利用者ごとに回帰テストを +1-3 件追加します。影響範囲が5領域を超える、または複雑な箇所が2つを超える場合は、見積もり前に SPLIT を再検討します。

リスクマージン（最大値を決定）：

likely_days	基本マージン
<1d 軽微	+10%
1-2d 小規模な拡張	+20%
3-4d 実質的な機能	+35%
5-7d 大規模	+50%
8-10d 非常に大規模	+75%
>10d	+100% AND 分割を推奨

リスク要因の加算分（加算方式 — risk_factors に列挙）：

要因	+マージン
touches-complex-existing-feature（>500 LOC、複数ハンドラー、中心的）	+20%
cross-service-contract の変更	+25%
schema-migration-on-populated-data	+25%
new-tech-or-unfamiliar-pattern	+30%
regression-fan-out（再テストが必要な下流領域が3つ以上）	+20%
performance-or-latency-critical	+20%
concurrency-race-event-ordering	+25%
shared-common-code（複数の利用者／アプリ）	+25%
unclear-requirements-or-design	+30%

上限ルール： マージンの合計が100%を超える場合は、作業を停止して分割します（2倍を超える水増しは不誠実です）。likely_days ≥5 でマージンが15%未満の場合は、過小見積もりです。範囲を広げてください。

作業種別の上限（likely_days の厳格な上限）：

作業種別	最大 SP	最大 likely
単一フィールド／設定フラグ／スタイル修正	1	0.5d
既存モデルにプロパティを追加し、既存 UI にバインド	2	1d
拡張エンドポイント＋軽微な UI コントロール（ボタン／メニュー／列）、フィクスチャを再利用	3	2-3d
拡張エンドポイント＋新しい UI 表面、または複数レイヤーの拡張＋新しいドメインルール＋テストファイル2つ以上	5	3-5d
新しいモデル／集約、移行、モジュール間コントラクト、重いテスト（>1.5d）、または新しい UI＋無視できないバックエンド	8	5-7d
新しい UI 表面＋（新しい集約、移行、またはサービス間コントラクト）	13	分割を推奨
サービス間コントラクト＋移行の組み合わせ	13	分割を推奨
これを超える場合	21	分割必須

SP→日数（検証専用）： 1=0.5d/0.25d · 2=1d/0.35d · 3=2d/0.65d · 5=4d/1.0d · 8=6d/1.5d · 13=10d/2.0d（従来方式／AI の likely） AI による高速化： SP 1≈2倍 · 2-3≈3倍 · 5-8≈4倍 · 13以上≈5倍。AI コスト = (code_gen × 1.3) + (test_gen × 1.3)（レビューのオーバーヘッド30%）。

必須のフロントマター：

story_points: <n>
complexity: low | medium | high | critical
man_days_traditional: '<min>-<max>d' # likely が3日以上の場合は範囲、3日未満の場合は '<N>d'
man_days_ai: '<min>-<max>d'
risk_margin_pct: <n> # 基本値＋加算分
risk_factors: [touches-complex-existing-feature, regression-fan-out] # 加算要因の選択肢から指定。該当なしの場合は []
blast_radius:
    touched_areas: <n>
    complex_touched: <n>
    downstream_consumers: [list or count]
    shared_common_code: yes | no
estimate_scope_included: [code, integration-tests, frontend, i18n, docs]
estimate_scope_excluded: [unit-tests, e2e, perf, deployment, code-review-rounds]
estimate_reasoning: |
    以下を含む5〜7行：
    (a) UI の段階 — 適用した行
    (b) バックエンドの段階 — 適用した行
    (c) テスト範囲 — 要因ごとのケース内訳、ファイル数、フィクスチャ、段階の行
    (d) コスト要因 — 支配的な段階とその理由
    (e) 影響範囲 — 変更箇所、複雑な箇所、回帰テスト範囲
    (f) リスク要因 — マージンの要因となるものの一覧と、さらに大きく／小さくならない理由
    例：「UI：Form/Table/Dialog を組み合わせて新画面を作成（約1.5d）。バックエンド：既存集約に新しいコマンドを追加し、
    バリデーションとリポジトリを再利用（約1d）。テスト：遷移4件 × 2アクター＋バリデーション3件＋UI 状態2件 = 13件、
    新しいフィクスチャ1つ → 13-25 件の段階で約1.5d。要因：UI の組み合わせと新しい状態。影響範囲：4領域、複雑な箇所1つ。
    リスク：基本値35%＋複雑な箇所への変更20% = 55% → 最大3.9d → 範囲2.5-4d。」

妥当性のセルフチェック：

• likely_days ≥3d なのに単一の値になっている？ → 不採用。必ず範囲にする
• likely_days ≥5d なのにマージンが15%未満？ → 過小見積もりです。範囲を広げる
• マージンが100%を超えている？ → 停止して、バッファを増やすのではなく分割する
• 既存の複雑な機能に触れるのに、(c) に回帰テストの予算がない？ → 不採用
• 影響範囲が5領域を超える、または複雑な箇所が2つを超えるのに、分割の検討がない？ → 不採用
• 既存モデルと既存 UI への追加だけ？ → テストが1.5dを超えない限り SP は3を上限とする
• 新しい UI 表面（ページ／複雑なフォーム／ダッシュボード）がある？ → バックエンドが単一エンドポイントでも SP 5以上
• バックエンドにサービス間連携／移行／複数集約がある？ → UI に関係なく SP 8以上
• bottom_up_hours / 6 と SP-Days の乖離が50%を超えている？ → ボトムアップの見積もりを優先し、SP を下げる
• テストがない場合に SP が1段階以上下がる？ → テストが支配的な要因です。明記する
• 推論で UI とバックエンド、影響範囲、リスク要因に触れている？ → 不足があれば追加する

• 必須・重要・厳守 変更を加える前に、既存パターンを3つ以上検索し、コードを読んでください。graph.db が存在する場合は、グラフトレースを実行してください。

• 必須・重要・厳守 すべての主張について file:line 形式の根拠を示してください。実行するには確信度が80％を超えている必要があります。確信度が60％未満の場合は、推奨しないでください。

• 必須・厳守 見積もり：ボトムアップで見積もった各フェーズの所要時間を基に man_days_traditional を算出します（Σh/6 × productivity_factor）。SP はそこから導出します。通常、UI のコストが最も大きくなります。新しい UI の画面（ページ／複雑なフォーム／ダッシュボード）を追加する場合は、SP を1段階引き上げてください。Frontmatter には story_points、complexity、man_days_traditional、man_days_ai、estimate_scope_included、estimate_scope_excluded、estimate_reasoning（UI とバックエンド、どちらがコスト要因か）を必ず含めてください。既存のモデルと既存の UI への追加で、テスト範囲が1.5日を超えない場合は、SP を3以下にしてください。SP が13の場合は分割することが望ましく、SP が21の場合は必ず分割してください。

必ず注意 批判的思考を適用してください。すべての主張には追跡可能な根拠が必要であり、実行するには確信度が80％を超えている必要があります。ハルシネーション防止：推測を事実として示さないでください。

必ず注意 AI の誤りを防止してください。まず全体を捉えてデバッグし、責任を持つレイヤーで修正し、コーディング前に曖昧な点を明確にし、コンパクション後はファイルを読み直してください。

• 必須 対象作業を始める前にタスク追跡を初期化してください。タスクは一度に1つずつ状態を遷移させてください。

• 必須 計画とレビューの所見を plans/reports/ に逐次保存し、ディスク上の内容を基にまとめてください。

• 必須 タスク追跡の初期化後、対象やソースの作業に着手する前に、必須のプロジェクト参照ドキュメントを読み、Reference docs read: ... と記載してください。

• 必須 常に lessons.md を含めてください。プロジェクトの規約は一般的なデフォルトより優先されます。

重要・必ず注意 デバッガーのトレースゲート：重要なバグ修正・調査・レビュー作業では、観測された最終出力から開始し、reader → storage/projection → writer → consumer/job → producer/trigger の順にさかのぼって追跡してください。修正する前に、すべての入力経路と仮説を列挙してください。トレース、仮説マトリックス、修正を担うレイヤー、前方収束の証明がそろうまで、作業はブロックされます。

• 必須 親ワークフローの行は、子フェーズの追跡の代わりにはなりません。ネストされたワークフローではフェーズを展開し、親にリンクしてください。
• 必須 オーケストレーターは、呼び出し前に子スキルのフェーズを展開してください。[N.M] $skill-name — phase のプレフィックスを使い、同時に in_progress にできるタスクは1つだけとしてください。

終了時の確認事項

• 必須・重要・厳守 作業を始める前に、タスク追跡を使って作業を小さな TODO タスクに分割してください。
• 必須・重要・厳守 新しいコードを書く前に、コードベースで類似パターンを3つ以上検索してください。
• 必須・重要・厳守 すべての主張について file:line 形式の根拠を示してください（実行するには確信度が80％を超えている必要があります）。
• 必須・重要・厳守 作業の品質を確認するための最終レビュー TODO タスクを追加してください。
• 必須・重要・厳守 修正に3回失敗したら停止してください。結果を報告し、4回目を試す前にユーザーに確認してください。 必須・重要・厳守 作業を始める前に、以下のファイルを読んでください。

[タスク計画] 作業に着手する前に、タスクの範囲を分析し、タスク追跡を使って小さな TODO タスクとサブタスクに体系的に分割してください。

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

ソース：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

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

汎用的な移植性の境界： 再利用可能なスキルとプロトコルのテキストはプロジェクトに依存しないものとします。プロジェクト固有の規約は、docs/project-config.json と docs/project-reference/ から確認してください。shared/sdd-artifact-contract.md の共通 AI-SDD を適用します。docs/project-config.json と docs/project-reference/docs-index-reference.md を読み、そこに記載されているプロジェクト参照ドキュメントを開いてください。この共通コンテキストとローカルドキュメントを利用できる場合は、サポートされている任意の AI ツールで実行できます。

1. 検出： プロンプトをワークフローカタログと照合します
2. 分析： 最適なワークフローを見つけ、カスタムのステップ構成のほうが適しているかどうかも評価します
3. 確認（必須形式）： ユーザーが明示的にワークフロー／スキルを呼び出し、かつローカルプロトコルで明示的な呼び出しを確認とみなす場合を除き、次の構成でユーザーに直接質問します
   • 質問："どのワークフローを有効にしますか？"
   • 選択肢 1："[最適なワークフロー] を有効にする（推奨）"
   • 選択肢 2："カスタムワークフローを有効にする：[step1 → step2 → ...]"（1 行で理由を記載）
4. 有効化（確認後）： 標準ワークフローの場合は $workflow-start <workflowId> を呼び出し、カスタムステップの場合は手動で順に実行します
5. タスクを作成： ワークフローのすべてのステップについてタスク追跡を行います
6. 実行： 各ステップを順番に実行します [CRITICAL-THINKING-MINDSET] 批判的思考と段階的思考を適用します。すべての主張には追跡可能な根拠が必要であり、確信度が 80% を超える場合にのみ行動します。 ハルシネーション防止の原則： 推測を事実として提示しないでください。すべての主張に出典を示し、不確実な点は率直に認め、出力に誤りがないか自己確認し、独立した情報源と照合し、自分の確信を疑ってください。根拠のない確信こそが、あらゆるハルシネーションの根本原因です。 AI の注意力に関する原則（初頭効果・新近効果）： 長いプロンプト／プロトコルでは、指示の順守が長いコンテキストウィンドウでも保たれるよう、最も重要な 3 つのルールを冒頭と末尾の両方に配置します。 目標主導の実行： まず成功基準を定義し、検証が完了するまで繰り返し、観察可能なチェックに合格した場合にのみ終了します。 テストで意図を検証： テストでは、現在の挙動をなぞるだけでなく、ビジネスルール／不変条件を保護し、保護対象の意図が損なわれた場合に失敗するようにします。

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

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

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

1. 症状ではなく、失敗モード（推論／前提の誤り）を特定します。「誤った列挙値を使った」ではなく、「ソースを読まずに API が存在すると仮定した」とします。
2. 一般性を検証します。この失敗モードは 3 つ以上のコンテキスト／コードベースに当てはまりますか？ 当てはまらない場合は、抽象度を 1 段階上げます。
3. 普遍的なルールとして記述します。プロジェクト固有の名前／パス／クラスを除き、どのコードベースでも役立つ内容にします。
4. 統合します。同じ失敗モードを共有する複数のミスは、1 つの教訓にまとめます。
5. 再発判定：「この注意書きがなければ、今後のセッションで再発するか？」いいえの場合は $learn を省略します。
6. 自動修正判定：「$code-review／$code-simplifier／$security／$lint で検出できるか？」はいの場合は、代わりにレビュー用スキルを改善します。
7. 両方の判定を通過した場合： $learn を実行するようユーザーに依頼します。 [TASK-PLANNING] [MANDATORY] ワークフローまたはスキルのステップを実行する前に、予定されているすべてのステップのタスク追跡を作成／更新し、各ステップの開始時と完了時に内容を同期してください。