fix-issue

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 を確認し、その後、タスクに関連するファイルのみを開いてください。

概要

目標： GitHub issue で報告されたバグを調査し、完全な追跡可能性を確保して修正します。

ワークフロー：

1. 取得 — GitHub issue の詳細（タイトル、説明、再現手順）を読みます
2. 再現 — コードを追跡し、報告された動作を確認します
3. 修正 — 根本原因の証拠を添えて修正を適用します

主なルール：

• デバッグの考え方：すべての主張に file:line の根拠が必要です
• 追跡可能性を確保するため、修正を GitHub issue に関連付けます
• 修正が issue の具体的な再現手順に対応していることを検証します

$ARGUMENTS

デバッグの考え方（必須）

懐疑的な姿勢を保ってください。批判的思考と順序立てた思考を適用してください。すべての主張に追跡可能な証拠と確信度（Idea は 80% を超えること）を示してください。

• 仮説に基づいて行動する前に、実際のコードトレースで検証してください。最初の仮説を正しいと決めつけないでください。理由：最初の推測は、原因ではなく、最も注意を引くものにとらわれた結果であることがよくあります
• 根本原因に関するすべての主張に file:line の根拠を含めてください
• コードトレースで根本原因を証明できない場合は、「仮説であり、未確認」と明記してください
• 前提を問い直してください：「これが本当に原因なのか？」→実際の実行経路を追跡してください
• 完全性を検証してください：「他にも要因があるのでは？」→関連するコード経路を確認してください
• 証拠なしに「これで修正されるはず」と述べないでください。追跡した根本原因に修正が対応していることを検証してください

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

必ず Confidence: X% と根拠のリスト、およびすべての主張を裏付ける file:line を提示してください。 95% 以上なら自由に推奨できます。**80～94%**なら注意事項を添えてください。**60～79%**なら不明点を列挙してください。60% 未満なら中止し、証拠をさらに集めてください。

⚠️ 修正前に検証（必須）： 根本原因の分析後、必ず調査結果と修正案をユーザーに直接質問して提示し、コードを変更する前に明示的な承認を得てください。黙って修正してはいけません。

debug-investigate スキルを有効にして、そのワークフローに従ってください。

重要：構造化分析には、必ず外部メモリ .ai/workspace/analysis/issue-[number].analysis.md を使用してください。修正案を提示する前に、分析ファイル全体を必ず読み直してください。これにより、知識の喪失を防げます。

🛑 根本原因と修正案を提示 → ユーザーに直接質問 → 承認を待ってから実装。

包括的なガイドラインについては .claude/docs/AI-DEBUGGING-PROTOCOL.md を参照してください。

⚠️ 必須：修正後の検証

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

---

単独レビューゲート（ワークフロー外の場合のみ）

必須： このスキルをワークフロー外（単独の $fix-issue）で呼び出す場合、タスクリストの最後のタスクとして、$review-changes 用のタスク追跡 ToDo タスクを必ず作成してください。これにより、ワークフローで定められていない場合でも、コミット前にすべての変更がレビューされます。

すでにワークフロー内（例：bugfix）で実行中の場合は、この手順を省略してください。ワークフローのシーケンスで、適切なステップに $review-changes が含まれています。

[IMPORTANT] 作業を始める前に、タスク追跡を使って、ファイルの読み込みごとのタスクも含め、すべての作業を小さなタスクに分割してください。これにより、長いファイルによるコンテキストの喪失を防げます。簡単なタスクの場合、AI は省略するかどうかを必ずユーザーに尋ねてください。

• docs/project-reference/domain-entities-reference.md — ドメインエンティティのカタログ、関連性、サービス間同期（タスクにビジネスエンティティ／モデルが関係する場合に読みます）（関連する場合は直接読み、フックによって会話に注入されたテキストに依存しないでください）

スキルのバリアント： $fix のバリアントです。体系的な調査を通じて GitHub の issue をデバッグして修正します。 最終状態から開始するデバッガートレース — 複雑なバグ、検証の失敗、回帰修正、動作を変えるコード、またはコードフローが不明瞭な場合は、修正案を提示する前に、観測された最終状態から逆向きにたどってください。

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段階引き上げてください。フロントマターには 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の場合は分割を推奨し、21の場合は必ず分割してください。

必ず守る重要事項 批判的思考を適用してください。すべての主張には追跡可能な証拠が必要です。確信度が80％を超える場合にのみ実行してください。ハルシネーション防止：推測を事実として提示しないでください。

必ず守る重要事項 AI の誤りを防止してください。全体を見てからデバッグし、責任を負うレイヤーで修正し、コーディング前に曖昧な点を明らかにし、コンパクション後にファイルを読み直してください。

• 必ず守る 対象作業に着手する前にタスク追跡を初期化し、タスクは一度に1つずつ遷移させてください。

• 必ず守る 計画とレビューの所見を plans/reports/ に段階的に保存し、ディスク上の内容をもとにまとめてください。

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

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

必ず守る重要事項 デバッガーのトレースゲート：重要なバグ修正、調査、レビューでは、観測された最終出力から開始し、読み取り側 → ストレージ／プロジェクション → 書き込み側 → コンシューマー／ジョブ → プロデューサー／トリガーへと逆向きに追跡してください。修正を行う前に、すべての流入経路と仮説を列挙してください。トレース、仮説マトリックス、修正を担当するレイヤー、前向きの収束を示す証明が揃うまで、作業はブロックされます。

• 必ず守る 親ワークフローの行で子フェーズの追跡を代用することはできません。ネストしている場合はフェーズを展開し、親にリンクしてください。
• 必ず守る オーケストレーターは呼び出し前に子スキルのフェーズを展開してください。[N.M] $skill-name — phase のプレフィックスを使い、「進行中」は一度に1つだけにしてください。

最後に確認すること

必ず守る重要事項 作業開始前に、タスク追跡を使って作業を小さな ToDo タスクに分割してください。 必ず守る重要事項 ユーザーに直接質問して判断を確認してください。自動で決定してはいけません。 必ず守る重要事項 作業品質を確認するための最終レビュー ToDo タスクを追加してください。 必ず守る重要事項 作業開始前に、以下のファイルを必ず読んでください。

[TASK-PLANNING] 行動を開始する前に、タスクの範囲を分析し、タスク追跡を使って小さな 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] ワークフローまたはスキルのステップを実行する前に、予定されているすべてのステップのタスク追跡を作成／更新し、各ステップの開始時と完了時に内容を同期してください。