fix-logs

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

クイックサマリー

目的： アプリケーションログを分析し、実行時エラーや予期しない動作を診断して修正します。

ワークフロー：

1. 収集 — 関連するログ出力（エラーメッセージ、スタックトレース、タイムスタンプ）を収集します
2. 追跡 — ログエントリをソースコードの該当箇所に対応付けます
3. 修正 — 追跡した実行経路に基づいて修正を適用します

主なルール：

• デバッグの考え方：すべての主張に file:line の根拠が必要です
• ログのパターンに注目します：スタックトレース、エラーコード、タイミングの異常など
• ログとソースコードを照合し、実際の根本原因を特定します

重要： スキルカタログを分析し、作業中に必要なスキルを有効化してください。

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

懐疑的な姿勢を保ち、批判的かつ順序立てて考えてください。すべての主張に追跡可能な証拠と確信度を示してください（アイデアの確信度は 80% を超える必要があります）。

• 対応に着手する前に、実際のコードの追跡結果と照らして各仮説を検証してください。最初の仮説が正しいと決めつけないでください。理由：最初の推測は、多くの場合、原因ではなく、最も注意を引いたものにとらわれた結果です。
• 根本原因に関するすべての主張には file:line の根拠を含めてください。
• コードの追跡で根本原因を証明できない場合は、「仮説であり、未確認」と明記してください。
• 前提を問い直してください。「本当にこれが原因か？」と問い、実際の実行経路を追跡してください。
• 網羅性を検証してください。「ほかに影響する要因はないか？」と問い、関連するコード経路を確認してください。
• 根拠のない「これで直るはずです」という判断はしないでください。修正によって追跡した根本原因に対処できることを検証してください。

⚠️ 必須：確信度と証拠のゲート

必須・重要・要注意：あらゆる主張に対して、証拠リストと file:line の根拠を添えて Confidence: X% を明記してください。 95% 以上なら自由に推奨できます | **80～94%**なら但し書きを添えてください | **60～79%**なら不明点を列挙してください | 60% 未満なら停止し、証拠をさらに集めてください。

ミッション

$ARGUMENTS

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

ワークフロー

1. ./logs.txt が存在するか確認します。
   • 存在しない場合は、プロジェクトのスクリプト設定（package.json、Makefile、pyproject.toml など）にログの永続的なパイプ処理を設定します。
     • Bash/Unix: 2>&1 | tee logs.txt を追記します。
     • PowerShell: *>&1 | Tee-Object logs.txt を追記します。
   • コマンドを実行してログを生成します。
2. debugger サブエージェントを使って ./logs.txt を分析し、根本原因を特定します。
   • Grep で head_limit: 30 を指定し、末尾の 30 行だけを読み込みます（ファイル全体の読み込みを避けてください）。
   • コンテキストが不十分な場合は、必要に応じて head_limit を増やします。
   • 外部メモリ: ログ分析を .ai/workspace/analysis/{issue-name}.analysis.md に書き込みます。修正前に再読してください。
3. scout サブエージェントを使ってコードベースを分析し、問題の正確な箇所を特定してから、メインエージェントに報告します。
4. planner サブエージェントを使って各報告に基づく実装計画を作成し、メインエージェントに報告します。
5. 🛑 根本原因と修正計画を提示 → ユーザーに直接質問 → 承認を待ちます。
6. 各報告と解決策に基づいて修正を実装します。
7. tester エージェントを使って修正をテストし、正常に動作することを確認してから、メインエージェントに報告します。
8. code-reviewer サブエージェントを使ってコード変更を簡潔にレビューし、要件を満たしていることを確認してから、メインエージェントに報告します。
9. 問題やテストの失敗があれば、手順 3 から繰り返します。
10. 完了したら、変更内容を要約して簡潔に説明し、ユーザーが使い始める方法を案内して、次のステップを提案します。

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

---

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

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

スキルのバリエーション: $fix のバリエーション — ログに基づくトラブルシューティングとエラー分析。 最終状態から開始するデバッガートレース — 複雑なバグ、検証の失敗、回帰修正、動作を変えるコード、またはコードフローが不明瞭な場合は、修正案を提示する前に、観測された最終状態から逆向きにたどってください。

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