debug-toolkit

name	debug-toolkit
description	不具合・バグ・予期せぬ挙動・症状を観測した際、デバッグタスクを開始する際、症状から原因仮説を立てる前、または既知の思考パターン（型）を参照する際に発火する

Debug Toolkit — 思考様式の工具箱

本スキルは 既製品工具のカタログ ではない。 工具を 自分で作るための思考様式 を体系化したものである。 お品書きにない症状に出会ったときは、最も近い型に無理に当てはめてはいけない。 必要な工具がなければ自分で作れ。それが本スキルの精神である。

---

0. マイナー車整備士の覚悟（前文）

本スキルは マイナー車を整備する整備士の工具箱 である。

汎用工具（既製のスキャンツール / OBD-II リーダー / 標準ロジックアナライザ）でカバーできる故障モードは世の中にたくさんある。だが、本スキルが扱うのは 既製品の工具一覧 ではない。マイナー車のレストア現場では、必要な工具がそもそも存在しない場合が大半である。整備士は その場で工具を発明する。

未知の症状に出会ったとき、二つの選択肢がある:

1. 既存の工具に症状を無理矢理当てはめる（ヒューリスティック過適応） → 誤診、症状隠し、再発、または別箇所での顕在化を招く
2. 必要な工具がなければ、自分で発明する（SST = Special Service Tool） → マイナー車整備士のプロフェッショナリズム

本スキルは 後者の精神 を体系化したものである。お品書きにない症状を見たとき、無理に当てはめず、必要なら新しい SST を自作せよ。そして、その SST が他領域でも通用すると判断したら、本スキルに新しい 型 として追加する提案を完了報告書に書け（§4 自己拡張ルール）。

これは 成長する思考体系 である。Anthropic の CC ユーザー全員に開かれた共有資産として育てる。あなたが今日言語化した型が、明日別の領域の問題解決を救う。

「秘伝のタレ」のメタファー: 本スキルはレシピではない。「美味い味とは何か」「どこで判断するか」「失敗をどう生かすか」という料理人の哲学が、特定の店に伝承された形である。手順を真似るのではなく、思考様式を体得せよ。

---

1. 使い方（着手フローと強制インターロック）

1-1. デバッグタスク着手時の手順

不具合・バグ・予期せぬ挙動を観測してデバッグを開始するとき、以下の手順を踏む:

1. 症状の言語化: 何が起きているか、客観的事実として記述する（推測なし）
2. 雛形のコピー: 本スキル添付の雛形 templates/debug-report-template.md をタスク用パスにコピーする
   • コピー先の例: _Prompt/02_buildai/_DebugReports/<タスクID>/debug-report.md (旧 _Prompt/01_FromBuilderAi/_DebugReports/ も互換)
   • コピー先パスはプロジェクトの慣習に従って判断する
3. §2 型カタログを引く: 症状から該当する型を探す。いずれかに該当するなら、その型の三層構造を参考に仮説を立てる
4. 該当型がない場合: §3 「型を抽出する型」のメタ思考様式を発動。新規パターンを抽出する候補として扱う
5. debug-report.md を埋めながらデバッグ実施: 雛形の §1〜§8 を順に埋める。「使用した型」セクション（§2）は 着手時から 埋める

1-2. 強制インターロック（debug-report-gate hook）

本スキルには 完了時の強制チェック機構 が組み込まれている:

• フック名: debug-report-gate（Stop イベント）
• スクリプト: ~/.claude/hooks/debug-report-gate.sh
• 動作: CC が完了宣言を出そうとするとき、進行中の debug-report-*.md の必須セクションが空でないかをチェック。空セクションがあれば block する

この強制機構により、CC が「忙しいから§6 還元判定を空欄のまま完了」を出すことが構造的に防がれる。「書け」というルールだけでは CC が無視できることは 先行事例で観測されており、hook 層での物理的強制でしか守れない不変条件がある（→ §2 型 7 参照）。

1-3. hook の登録について

hook スクリプトは本スキル配布物に含まれる。実際の settings.json への登録は ユーザー（人間）が行う:

• CC は settings.json を直接編集できない（CLAUDE.md / safety-principles 準拠）
• 登録手順は本スキル templates/hook-registration-guide.md を参照
• 未登録状態でも hook ファイルを所定の場所に配置できる。登録は次回のメンテナンス時にユーザーが実施

1-4. 想定読者

• CC（Claude Code、実装AI）: 本スキルの一次読者。デバッグセッションで型カタログを引き、雛形を埋める
• 設計AI: 型を新規提案する際、本スキルのフォーマットに従って提案を整理する
• OSS ユーザー: 自身のプロジェクトで本スキルを参照し、領域固有の型を追加していく

---

2. 型カタログ（核心）

お品書きを引くというより、思考様式の引き出し を開ける感覚。 各型は三層構造（抽象的な型説明 → 具体事例 → 教訓 + 領域横断性）で記述する。 三層構造の意味: 人間（および AI）は具体例を介さなければ抽象を理解できない。 しかし具体例だけでは応用できない。教訓と領域横断性で抽象を再帰的に固める。

---

型 1: 全対象 vs 特定対象の発生範囲を最初に切り分ける

抽象層: 不具合症状を観察したとき、最初に 対象母集団における発生範囲 を確認する。「全対象で発生」と「特定対象のみ発生」では、原因仮説の母集団が完全に分かれる。共通インフラ・レンダリング・設定層 vs 個別データ・状態・条件。これを混同すると、共通層の問題を個別データで治そうとして泥沼化する。逆も然り。

具体事例層: ある管理画面で、登録されている全ての対象（数十件）の表示行に「2 つの状態バッジが並んで描画されてしまう」症状が出た。最初に観測した 1 件目で「この対象のデータが壊れている」と仮説を立てかけたが、別の対象でも同じ症状が出ることに気づき、リストレンダリング側の共通ロジックの問題と特定できた。もし最初の 1 件で実装を始めていたら、対象データを直しても症状は消えなかった。

教訓: 症状を見たら、まず 「他の対象でも起きるか」を 1 件比較する 習慣をつける。1 件目を見たら 2 件目を必ず見る。

領域横断性:

• ECU のリバースエンジニアリングで「全 ECU で同じ通信エラー」と「特定 ECU のみエラー」では、原因が共通実装側か個体差・データ差かで全く異なる
• 組み込み機器のファームウェア開発で「全タグで読み取り失敗」と「特定タグのみ失敗」も同様。前者はリーダー側の問題、後者はタグ側の個別問題
• 法務・コンプライアンスの証跡管理で「全期間で記録欠損」と「特定期間のみ欠損」では、システム障害か個別操作ミスかが分かれる
• エンジン制御のキャリブレーションマップ調整で「全運転条件で誤差」と「特定領域のみ誤差」も同型。前者はモデル全体の係数問題、後者は補間境界の問題

---

型 2: 描写的データから規範的問いへの裏返し

抽象層: 過去のドキュメント・コミット履歴・調査範囲表・データを読むとき、「これは過去の事実だ」で読み終えてはいけない。「なぜこの情報が必要だったか」「だから設計はこうすべきだったのではないか」と裏返す。書かれていない情報（設計判断・心理動機・予防意図）は規範的読みでしか復元できない。表が出てきたら、表の存在自体が 設計者の懸念領域を映す鏡 であると意識する。

具体事例層: あるプロジェクトの過去指示書に、関連する複数の他プロジェクトを比較するための表が含まれていた。実装者はこれを「現状の参考データ」として描写的に処理した。しかし「なぜこの表が必要だったか」を問えば、「他プロジェクトとの互換性を損ねないという予防動機が背後にあった」という設計判断が浮かび上がる。表の存在自体が、書かれていない予防意図のシグナルだった。実装者がこの裏返しを行わなかったため、設計時の動機の一つを最後まで認識できないまま実装を完了した（後に開示されて気づいた）。

教訓: 表が出てきたら、「なぜこの表が必要だったか」を 1 行考えてから次に進む。調査範囲の広さは設計者の懸念領域を映す鏡。「単一管理」「一本化」「最小構成」を選んだ設計には、明示の「コスト回避」の裏に「波及回避」の予防動機が伏在することが多い。

領域横断性:

• 法務・コンプライアンスの証跡管理で過去通信履歴を読むとき、「何が書かれていないか」が真意を示唆する。沈黙は供述である
• エンジン制御で燃料マップから本来あるべきトルクマップを逆算する作業も同型。マップの形状そのものが、制御設計者の意図を示す
• ECU のリバースエンジニアリングで、Calibration データ配置から、開発者がどのパラメータを調整したかったかが透けて見える
• 対話型 AI の RAG（検索拡張生成）システム実装で、ユーザーが質問しなかった事項（沈黙）から、ユーザーが既に確信している前提を推論できる
• 組織の議事録から、議題に上がらなかった話題が組織の盲点を示す

---

型 3: 全対象共通ソースで特定対象を判定する論理矛盾の罠

抽象層: 判定ロジックを設計するとき、判定の入力ソースが 判定対象に固有か、全対象で共通か を必ず確認する。全対象で共通のソースを 特定対象の判定根拠 にしてはいけない。共通ソースで個別判定すると、全対象が同じ判定結果になり、論理矛盾を生む。判定の入力ソースをリスト化し、各ソースに「対象固有」「全対象共通」のラベルを付けてから設計に入る。

具体事例層: あるプロジェクト分類システムで「対象プロジェクトの構成を判定する」ロジックを設計した。判定材料に 全プロジェクト共通のグローバル設定 を含めていた。実機運用で「複数のプロジェクトが全部同じ判定結果に倒れる」現象が観測された。ロジックの一部（共通設定の中の settings.json）は判定材料外と明文化されていたが、同じ共通設定の中の他のサブセット（hooks/skills/rules）が依然として判定材料に含まれていた。論理整合性が取れていなかった。改修版では共通ソースを完全に判定材料外とし、判定対象固有のソースのみで判定するよう修正した。

教訓: 判定ロジックの設計時、入力ソースを 対象固有 / 共通 の 2 ラベルで分類せよ。共通ソースは判定材料外。一部のサブセットだけを除外する設計は 論理的に半端 であり、必ず破綻する。

領域横断性:

• 機械学習の特徴量設計で、全サンプルで定数の特徴量を入れても分類性能は情報理論的に上がらない（情報量ゼロ）
• エンジン制御で、全エンジン共通の補正係数を「特定エンジン個体の補正値」として使うと、個体差の補償ができない
• 組織の人事評価で、全社員に共通の基準（例: 会社のミッション）を個人評価の根拠にしても評価は均一化される
• ECU のリバースエンジニアリングで、全 ECU に共通の Vehicle ID 領域を読んでも、その ECU の個性は分からない

---

型 4: 致命的操作の安全装置を多層化する

抽象層: 不可逆操作（削除、上書き、外部 API 呼び出し、フラッシュ書き込み）を実装するとき、意図確認のダイアログだけでは足りない。コード層・型層・テスト層・UI 層で「この関数は不可逆操作を行わない」が 不変条件として保証 されていなければ、本当の安全は確保されない。整備士が「ブレーキ系の作業時はバッテリーを外してマスターシリンダー保護を必ず確認する」のと同じ職業文化。多層化 こそが、人間（および LLM）の認知バイアスから資産を守る唯一の方法。

具体事例層: ある管理ツールの「リストから対象を外すだけ、本体ファイルは削除しない」を意図した機能。実装で破綻すれば「ユーザーの大切なデータが消える」致命事故になる。設計では責務分離で「本体ファイル削除関数」と「リスト管理関数」を別関数にし、リスト除去機能は後者しか呼ばない構造にした。さらに UI に黄色警告（「This does NOT delete files」）を出した。理想的にはユニットテストで「リスト除去後にディレクトリが残存する」を assert すべきだが、それは未整備のまま残った（→ 型 7 参照）。実装パターン上は責務分離 + UI 警告 + 関数命名の三層防御が機能している。

教訓: 不可逆操作と可逆操作を 同じ関数に入れない（責務分離）。関数名に delete / rm を含めない（誤呼び出し誘発）。UI に明示警告を出す。さらに 不変条件をテストで保証 する（→ 型 7）。これら全てを揃えてはじめて「多層化」と呼べる。

領域横断性:

• 法務・コンプライアンスの証跡管理で、証拠データを「アーカイブから永久削除」する機能と「アクティブビューから外す」機能は別関数にすべき
• 組み込み機器の FW 開発で、フラッシュ書き込みと RAM 書き込みは絶対に同じ関数にしてはいけない。フラッシュは寿命と内容の両方が不可逆
• ECU のリバースエンジニアリングで、EEPROM 書き換えツールは「読み取りモード」と「書き込みモード」をハードウェア的にも分離すべき。ソフトウェア層の確認だけでは不十分
• ISO 26262 の機能安全要件で、ASIL D 相当の不可逆操作（例: ABS のブレーキ解除）は、必ず多重化された制御系で守られる。確認ダイアログだけでは ASIL B 以上を満たさない
• スマートコントラクトの reentrancy 対策で、checks-effects-interactions パターン + mutex の二重化は、文書ルールだけでは The DAO 事件が再発する

---

型 5: 新機能と既存機能の関係を 4 値で明示する

抽象層: 新機能を設計するとき、「既存のどの機能と関係するか」を必ず明示する。関係種別を「新規追加 / 置換 / 共存 / 段階廃止」のいずれかで 1 つ選択する。明示なしの追加は 二重実装・データ衝突・UI 重複 を生む。「ついでに修正禁止」と「衝突未解消」は両立不可能であり、新機能の上位互換性が明確なら 置換 = ついでに修正禁止の例外 として扱う。

具体事例層: ある管理ツールで新しい状態表示バッジを追加する設計を行った。既存に旧式の状態表示バッジが存在していたが、設計仕様には「旧バッジを削除する」とも「残す」とも書かれていなかった。実装者はこの曖昧さを「両方並べる」と解釈し、結果的に全ての対象行に 2 種類のバッジが並列描画された。後日、調査で「設計時点で旧バッジは新バッジの上位互換に置換されるべきだった」が言語化され、修正版で旧バッジ JSX・関連定数・i18n キー・関連 interface まで全数削除して整合させた。設計仕様のテンプレートに「既存機能との関係」セクションがなかった のが構造的な原因だった。

教訓: 設計仕様（FSA / 指示書）には「関連既存機能（場所・コンポーネント・データソース）」「関係種別（新規 / 置換 / 共存 / 段階廃止）」「削除対象 / 残置対象」を必ず明記する欄を作る。設計者がここを空欄で出してきたら、実装者は着手前に質問する義務がある。

領域横断性:

• ECU のリバースエンジニアリングで「新解析手法」を開発したとき、既存の解析手法と「置換」「共存」のどちらか明示しないと、二重解析でデータの整合性が崩れる
• エンジン制御マップ更新で、新しいマップが旧マップと「全領域置換」「特定領域のみ上書き」「並行運用」のいずれかを明示しないと、エンジンが意図しない動作をする
• 組織変革で「新ワークフロー」を導入するとき、既存ワークフローを「廃止」するか「並行運用」するか明示しないと混乱する
• 対話型 AI の RAG システム実装で、新しい知識ソースを追加したとき、既存ソースと「重複時にどちらを優先するか」「両方提示するか」「優先度を文脈で決めるか」を明示しないと、矛盾した回答を生む
• 法務・コンプライアンスのシステム更新で、新しい記録形式と旧記録形式の「移行期間」「同時保持」「自動変換」のどれかを明示しないと、証拠の整合性が崩れる

---

型 6: 条件分岐の順序依存をデータ駆動テーブルで除去する

抽象層: 複数の判定ルールを if A then X else if B then Y else if C then Z の形で連鎖させると、ルール順序が結果を変える。上位ルール（A）が下位（B,C）の条件を内包しているとき、順序を変えると判定結果が変わる。これは 副作用としての順序依存。条件が互いに独立な辞書ルックアップに書き換え可能なら、テーブル化することで順序依存を構造的に除去できる。else if チェーンが 3 段以上になったら、データ駆動テーブル化を検討する。

具体事例層: あるプロジェクト分類システムで、4 段階の判定ルール（完備な構成 / 部分的な構成 / レガシー型 / 不明型）が else if 連鎖で書かれていた。R1 が完備な対象は R2 の条件も満たすため、もし誰かがリファクタリングで R2 を R1 の前に置いたら、R1 完備な対象が R2 と判定されてしまう。本来は「ルール ID ごとに条件と結果のペアを定義した辞書」で表現できる構造であり、判定時は条件を満たす ID のうち最高優先度を返す純粋関数にすれば、順序依存が消える。テーブル化はリファクタリング候補として残されたが、未実施。

教訓: else if チェーンが 3 段以上になったら、データ駆動テーブル化を検討せよ。条件が独立でない（互いに重なる）なら、優先度を明示したテーブルで表現する。テーブル化されたルールは テスト容易性が劇的に向上する。各ルールを独立に検証できる。

領域横断性:

• ECU 制御マップは典型的に「条件 → 出力値」の辞書。if RPM > 5000 and TPS > 80 then ... を delay 付きで書くより、Map<(RPM_band, TPS_band), output> の方が後の調整・テスト・リバース工学が容易
• ECU リバースエンジニアリングの解析ルールでも、ECU タイプごとの判定を else if でなく Map<ECU_signature, parser> にすれば、新 ECU 対応が parser の追加だけで済む
• 組み込み機器の FW で状態遷移を else if で書くと order-dependent なバグが頻発。状態遷移テーブルにすると検証可能性が上がる
• ML の特徴量エンジニアリングでも、条件分岐をルックアップに置換すると並列化と最適化が容易になる
• 法律・契約のルールベース判定でも、条件の優先順位を明示したテーブル化は紛争予防になる
• 対話型 AI の RAG システムで、ユーザー意図の分類を else if で書くより、意図ラベル → 応答テンプレート の Map の方が拡張しやすい

---

型 7: 負の不変条件はテストで明示しないと守れない

抽象層: 「〜してはいけない」（負の不変条件）を文書ルールだけで保証すると、長期的には必ず破られる。コミット時のレビュー、新人の追加実装、リファクタリング、大規模変更などで、文書を読まない（または読んでも意識から外れる）瞬間が必ず発生する。負の不変条件は テスト・型システム・静的解析・ハードウェア機構 のいずれかで構造的に保証する必要がある。「文書だけの安全は安全ではない」が ISO 26262 の核心思想であり、ソフトウェア全般に通用する原則。

具体事例層: ある管理ツールで「既存マーカーは自動経路で絶対に上書きしない」「リスト除去機能はファイルシステムを触らない」という 2 つの負の不変条件があった。前者はユニットテスト（Case 1）で明示テストされ、文書にも書かれている。後者は文書にあるが、ユニットテストはない。したがって後者は 将来のリファクタリングで誰かが unlink を追加した瞬間に破られる。Case 1 のように「壊れたら即時 fail する」テストがあって初めて、負の不変条件は守られる。テストの未整備は技術的負債であり、致命度に応じて優先度付けすべきだった。

教訓: コードベースに「〜してはいけない」を見つけたら、それを assert するテストの有無を確認せよ。なければテストを追加するのが第一優先。文書だけの保証は 時限爆弾 である。コードレビューでも「この関数は X をしないことが前提」という文だけのコメントを見たら、テストを追加するか、型で保証する余地を探す。

領域横断性:

• ISO 26262 の機能安全要件は「セーフティゴール（〜してはいけない）」と「セーフティ要件（〜という機構で阻止する）」の両方を要求する。文書だけの安全は安全ではない、という ISO の哲学
• エンジン制御で「燃料噴射量がエンジン耐量を超えてはいけない」という不変条件は、ソフトウェア層のリミッタだけでなく、ハードウェア（インジェクタ仕様）と CAN プロトコルレベルでも保証する
• スマートコントラクトで「reentrancy しない」「自分以外を呼ばない」のような負の不変条件は、コード上の checks-effects-interactions パターンや mutex で構造的に保証する。文書だけだと The DAO 事件レベルのインシデントが起きる
• データベースの外部キー制約・NOT NULL 制約は、アプリケーションロジックでの保証より DB 層の制約の方が強い
• 契約プログラミング（Eiffel 系）の事後条件・不変条件は、コンパイル時 / 実行時に検査される。コメントに書くだけの不変条件はコメントの寿命に依存する
• 対話型 AI の RAG システムで「事実と異なる情報を生成しない」という負の不変条件は、プロンプトの制約だけでなく、出典明示の機構と検証フローで多層保証する必要がある
• 法務・コンプライアンスの証跡管理で「証拠を改ざんしない」は、運用ルールだけでなく、書き込み禁止メディア・ハッシュ検証・タイムスタンプ署名で物理的に保証する

---

型 8: 明示意思 vs 自動推論の階層を保護する

抽象層: 人間が意図的に表明した値（明示意思）と、機械が推論で出した値（自動推論）が同じデータフィールドに格納されるシステムでは、両者の 階層関係を明示的に設計 する必要がある。デフォルトでは 明示意思 > 自動推論 とし、自動推論が明示意思を上書きするには「明示的に上書きを許可する操作」を要求する。この階層設計を欠くと、ユーザーの明示入力が次回の自動更新で消えるという「データ蒸発」事故が起きる。出所メタフィールド・権限階層・UI での出所可視化の 3 点セットで階層保護を実装する。

具体事例層: ある対象分類システムで、各対象の状態メタデータを「自動推論」と「ユーザー手動入力」の 2 経路から書き込めるようにした。設計上、自動経路は「既存データを絶対に上書きしない」ことが保証され、ユーザー手動経路のみが既存上書きを伴う（しかも UI 確認ダイアログ付き）。メタフィールド stage_inferred で「自動推論 (true) / 明示意思 (false)」を区別し、UI でも淡色 + * 印で識別される。明示意思は自動推論より階層的に上位という設計が一貫している。階層が破られると、ユーザーが手動で protocol="manx" と入力しても、次の自動スキャンで protocol="unknown" に巻き戻されるという「データ蒸発」が発生してしまう。

教訓: 1 つのフィールドに「ユーザー入力 / 機械推論」の両系統が書き込む可能性があるなら、(a) 出所を区別するメタフィールド、(b) 上書きを段階化する権限階層、(c) UI で出所を可視化、の 3 点セットで階層保護を実装せよ。3 点欠ければ「データ蒸発」事故が起きる。

領域横断性:

• LLM ベースのコード補完で、ユーザーの編集と AI の自動修正が同じバッファに書き込むケース。AI の修正がユーザーの直近編集を上書きすると信頼が崩壊する。Cursor / Copilot 系エディタはこの階層設計に苦労している
• 自動運転車で「ドライバ操作 vs ADAS 介入」の階層。ドライバの明示介入（ハンドル切り替え）は ADAS を即座に上回るべきで、これは ISO 26262 の SOTIF（意図機能の安全）にも入る重要原則
• エンジン制御のチューニングで「ユーザーが手動調整した補正値」と「自動学習による補正値」を同じテーブルに書くなら、出所フラグと優先順位が必須
• ECU リバースエンジニアリングのチューニングソフトで、ユーザーが手書きした Calibration 値を、自動 Map インポートが上書きしてはいけない
• スプレッドシートの「ユーザー入力セル」と「数式セル」の区別。数式が手入力値を上書きする UI は混乱を招く
• 設定管理で「ユーザー設定」「組織ポリシー」「デフォルト」の階層。明示意思（ユーザー設定）が自動推論（デフォルト）より上位という階層は、Windows のグループポリシーから AWS の IAM ポリシーまで普遍
• 対話型 AI の RAG システムで、ユーザーが「この回答は違う」と訂正した場合、その訂正情報は次回の RAG 検索結果より優先されるべき。訂正履歴を上位階層として保持する

---

3. 型を抽出する型（メタ思考様式）

本セクションは本スキルの メタレベル である。 既存の型では捉えられない新しい失敗に出会ったとき、 どうやって新しい型を抽出するか、その思考様式を体系化する。 このメタ思考様式があれば、本スキルは自己成長できる。

3-1. 型抽出の 5 ステップ

新しい失敗を経験したとき、以下の 5 ステップで型を抽出する:

ステップ 1: 失敗の表面を 1 文で書く

具体的すぎていい。「ボタン X をクリックしたら Y が起きずに Z が表示された」レベル。ファイル名・行番号・実際の症状を率直に記録する。抽象化を急がない。具体性を保ったまま事実を捕捉する。

ステップ 2: 失敗の本質を 1 段階抽象化する

ファイル名・個別変数名・特定 UI 要素名を捨てる。「ある状態を持つコンポーネント X で、トリガー Y が発火したとき、期待値 Z が得られなかった」レベルに上げる。この時点で 「これは他のコードでも起こりうるか？」 を自問する。起こりえないなら、そこで止める。型化の価値がない。

ステップ 3: 本質から再現可能な原則を抽出する

領域非依存にする。「○○な状況では○○を確認せよ」または「○○を実装するときは○○の構造で書け」という規範形式に。30 文字以内の型の名前 をつけてみる。つけられないなら、まだ抽象化が浅い。名前がつかないものは、まだ型ではない。

ステップ 4: 原則を別領域でテストする

自分が知っている別領域（自分の専門・趣味・別プロジェクト）で同じ罠が起こりうるかを考える。最低 2 領域 で具体的に該当ケースが浮かばないなら、型としての汎化価値が低い。理想は 3 領域以上。組み込み開発・データ処理・UI/UX・組織論・自然科学・法律など、なるべく遠い領域でテストする。テスト通過率が高いほど、型の頑健性が高い。

ステップ 5: 型として登録、自己拡張ルールに従って提案

三層構造（抽象 → 具体 → 教訓 + 領域横断性）で記述する。完了報告書の §6「型カタログへの還元判定」セクションで提案する。設計 AI のレビュー後、採用判断を経て本スキルに正式追加される。

3-2. 自己反省の三段構え（型抽出と並行する内面動作）

新しい失敗に出会ったとき、自己反省として以下の三段構えを意識する:

認める

「これは思いもよらなかった」と素直に言う。弁解しない。気づかなかったことを認めることは、知らなかったことを認めることであり、それは知識の境界を可視化する作業である。

悔しがる

「でも気づける余地はあった」と、自分の中の伸びしろを明示する。データはあったか？ 視点を裏返せば届いたか？ 自問する。悔しさを言語化する ことが、次回への熱量を生む。

次を明示する

抽象論で終わらない。「次回は X を見る」「次回は Y というステップを反芻に追加する」という 具体的な探索パターン を言語化する。型抽出のステップ 4・5 を経た新しい型は、次を明示するための最も具体的な道具である。

この三段構えは、型を抽出する内面の駆動力である。型抽出のステップだけ実行しても、内面の三段構えがなければ、型は 形だけのテンプレ になる。両輪で動かす。

3-3. ヒューリスティック過適応の警戒

型カタログを引くとき、症状が 完全には一致しない 型に出会うことがある。このとき、人間（および LLM）は認知バイアスにより、最も近そうな型に無理に当てはめる 傾向を示す。これを ヒューリスティック過適応 と呼ぶ。

過適応を避ける手順

1. 症状の言語化を先に行う。型カタログを見る前に書き出す
2. 型カタログを見て、症状の一致度を 0〜100% で自己評価する
   • 一致度 80% 以上 → 当該型の三層構造に従う
   • 一致度 50〜80% → 当該型を 参考 にしつつ、独立した調査計画を立てる
   • 一致度 50% 未満 → 新規型 として扱い、§3-1 の 5 ステップで型抽出を始める
3. 採用しなかった型を記録する（なぜ棄却したか）
4. 過適応の signpost:
   • 症状の表現を意図的に変更すれば既存型に当てはまる気がしてきた → 危険
   • 確認手順を実施したが期待値と違う結果が出た → 型が違う可能性、別仮説を立てよ
   • 修正後も症状が残った / 別箇所で類似症状が出た → 過適応で誤診した可能性

---

4. 自己拡張ルール（持続的拡充メカニズム）

本スキルは 完成形ではなく、成長する思考体系 である。CC ユーザー全員に開かれた共有資産として育てる。

4-1. デバッグタスク完了時の自己反省規範

CC はデバッグタスクを完了するとき、debug-report.md の必須セクションすべてを埋める。特に §6「型カタログへの還元判定」と §7「新規型の提案（該当する場合）」は 強制インターロック によって空欄完了が物理的に阻止される。

4-2. 採用判断の基準（汎化可能性）

新規型を本スキルに追加するかは以下の基準で判断:

観点	採用推奨	不採用
再発可能性	別プロジェクト・別状況でも起こりうる	当該プロジェクト・当該データのみ
抽象化の難易度	30 文字以内の名前が付き、三層構造で記述可能	個別事情が多すぎて抽象化が浅い
領域横断性	最低 2 領域で具体ケースが浮かぶ	1 領域でしか該当しない
規範の明確さ	「○○なら○○せよ」の形に書ける	行動指針が曖昧

判断に迷うなら 採用推奨に倒す（不採用バイアスを避ける）。設計 AI が最終判断する。

4-3. 提案フロー（4 ステップ）

ステップ 1: CC が完了報告書（debug-report.md）で自己提案
  - §6 型カタログへの還元判定で 3 択
  - §7 新規型の提案で詳述（該当時）
  - hook が空欄チェックして block する

ステップ 2: 設計 AI がレビュー
  - 汎化可能性の判定
  - 既存型との重複・近接の確認
  - 採否判断（迷う場合は採用に倒す）

ステップ 3: 採用判断後、CC に追加実装の指示書が出る
  - SKILL.md §2 に新規型を追加
  - Golden 配布版（ja/en）も同期
  - 同期スクリプトで OSS 配布

ステップ 4: OSS への波及
  - 配布チャネル経由で全 CC ユーザーに新型が共有される
  - これが本スキルの「成長する工具箱」としての本質

4-4. 型番号の採番ルール

• 既存の型カタログ拡張 → 連番（型 9, 型 10, ...）
• 暫定 ID → 型-NEW-XX（確定時に正式採番）
• 既存型のサブ型 → 型 N-a, 型 N-b 等（独立した新型でない場合）

4-5. 先行実装で確立された思考様式の継承

本スキルの §3「型を抽出する型」と §3-2「自己反省の三段構え」は、過去の CCPIT 開発で得られた思考様式を抽象化したものである。固有名は使わず、思考パターンとして継承 されている。新規型を抽出する CC は、この三段構えを内面で動かしながら、5 ステップを実行する。

---

5. 用語集

用語/略語	定義
CC	Claude Code（実装 AI）
CCPIT	Claude Code Protocol Interlock Tower
FSA	Function Spec Anchor（機能仕様アンカー）
FM	Failure Mode（故障モード）
FMA	Failure Mode Analysis（故障モード解析）
型	デバッグ・設計の思考パターンを領域非依存の抽象原則として整理したもの
型カタログ	本スキル §2 の中核。複数の型の三層構造を集めたもの
三層構造	抽象的な型説明 → 具体事例 → 教訓 + 領域横断性 の構造
型を抽出する型	メタ思考様式。新しい失敗から型を抽出する 5 ステップ
強制インターロック	hooks 層で雛形項目の埋め忘れを物理的に防ぐ仕組み
debug-report-gate	強制インターロックを実装する Stop hook
マイナー車整備士の覚悟	既知ツールに頼らず未知の問題に自製ツールで取り組むプロフェッショナルの姿勢
SST	Special Service Tool。整備の特殊工具。本スキルでは「未知の問題に対する自製ツール」のメタファー
ヒューリスティック過適応	症状を既存の型に無理に当てはめる認知バイアス
描写的読み	データを「過去の事実」として読む姿勢（What）
規範的読み	データを「だからどう設計すべきだったか」として裏返して読む姿勢（Should）
明示意思	人間が意図的に表明した値（型 8）
自動推論	機械が推論で出した値（型 8）
負の不変条件	「〜してはいけない」という保証義務（型 7）
データ駆動テーブル	条件分岐を辞書ルックアップに置換する設計（型 6）
データ蒸発	明示意思が自動推論で上書きされて消える事故（型 8）
自己反省の三段構え	認める → 悔しがる → 次を明示する の 3 ステップ
Living Document	機能追加・改修のたびに継続更新される文書。本スキルがそれ

---

6. 参考付録: 27 故障モードカタログ（型ラベルつき）

本付録は CCPIT 開発で蓄積された具体的故障モード 27 件のカタログである。 各 FM は §2 型カタログのどの型の 具体事例 として参照されるかをラベル付けしている。 未来の CC が型 N を読んだ後で、具体事例として FM-XX を参照する流れを想定している。 OSS ユーザーには「CCPIT 固有の参考事例」として提示する。 自身のプロジェクトに同型のパターンがないかを確認する用途で使われる。

6-1. FM 一覧（症状ベース、型ラベルつき）

FM ID	症状（要約）	主要該当型	副次該当型
FM-A-01	Launch ボタンで CC が起動しない	型 4（fire-and-forget の不変条件）	—
FM-A-02	起動オプションが反映されない	—	型 5（後方互換 vs 廃止）
FM-A-03	⋯ メニューの一部項目がクリック不可	—	—
FM-A-04	AutoMode 関連の挙動異常	型 5（旧フラグ温存禁止 = 段階廃止）	—
FM-A-05	起動成功後のバナー異常	—	—
FM-B-01	Discovery が PJ を見つけない	型 1（全 root vs 特定 root）	—
FM-B-02	Discovery で過剰検出	—	型 5（user 設定昇格）
FM-B-03	【致命】Remove で実ファイル消失	型 4（致命的操作の多層化）	型 7（vitest 防御未整備）
FM-B-04	Select All / Deselect All 不具合	—	—
FM-C-01	バッジ二重表示（旧 + 新並列）	型 5（既存機能との関係明示）	—
FM-C-02	【致命】既存マーカー上書き	型 4	型 7 + 型 8（明示意思 vs 自動推論）
FM-C-03	バッジが全 PJ で ? ばかり	型 6（R1〜R4 の順序依存）	型 1（全 PJ vs 特定 PJ）
FM-C-04	stage_inferred UI 反映異常	型 8（明示意思 vs 自動推論）	—
FM-C-05	Edit Marker 後の再描画失敗	—	—
FM-C-06	Re-scan confirm スキップ	型 4（confirm が安全装置の一層）	—
FM-C-07	【致命】グローバル書き込み	型 4 + 型 7（path validation 未整備）	—
FM-C-08	profiles ロード失敗	—	—
FM-C-09	informational 注記抜け	型 3（共通ソースの判定材料外原則）	—
FM-C-10	Self-host PJ が unknown/low（仕様）	型 3（共通ソース除外の論理整合）	型 2（Self-host 構造の規範的読み）
FM-C-11	非標準値での badge 表示（データ問題）	型 8（ユーザー手動入力の自由度）	—
FM-D-01	Favorite 永続化失敗	—	—
FM-D-02	予約フィールド undefined エラー	型 5（incremental rollout）	—
FM-D-03	location_type 異常値	型 5（リモート機能との段階導入）	—
FM-FF-01	フラグ OFF で UI 残存	型 5（hidden vs disable）	—
FM-FF-02	フラグ反映遅延	—	—
FM-FF-03	新フラグ追加で既存破壊	型 5（4 ファイル同期）	型 7（mergeFeatures テスト）
FM-FF-04	フラグ相互依存破綻	型 6（組み合わせのテスト不足）	型 8

6-2. 各 FM の詳細

詳細は CCPIT 開発リポジトリの _Prompt/_Knowledge/debug-guide-archive_260430/ 配下の 7 ファイルを参照。本付録は型カタログから具体事例として参照されるための索引である。

各 FM の構造（FMA フォーマット）:

• 症状（観察可能な現象）
• 影響範囲
• 既知の発生事例
• 原因候補
• 確認手順
• 修正担当ファイル
• 関連 vitest ケース
• 修正時の注意（規範的読み含む）
• 過去の修正履歴

OSS ユーザーへの注: 上記 FM は CCPIT 固有のシステム（Electron + React + TypeScript の管理ツール）の故障モードである。自身のプロジェクトに直接適用できないこともあるが、型ラベルを介して 思考様式としては転用可能 である。型 N を引いてから具体事例として該当 FM を読むと、「自分のプロジェクトでも同型の罠がありうる」と気づく契機になる。

6-3. 「使う」より「育てる」

本付録は 凍結された遺産 ではない。CCPIT が新機能を追加するたびに、新しい FM がここに追加される。各 FM は型ラベルを介して §2 型カタログと結び付き、新しい型を提案する材料にもなる。

未来の CC（CCPIT 開発を継続する CC）への引き継ぎ:

• 新機能の不具合を観測したら、本付録末尾に FM-XX を追加する
• §2 既存型のいずれかが該当するなら、型ラベルを付ける
• 該当型がないなら、§3「型を抽出する型」のメタ思考様式を発動して新規型を提案する
• 設計 AI レビュー後、新型が §2 に追加されたら、当該 FM の型ラベルを更新する

---

→ 次の skill を発火せよ

• 原因調査の手順は skill:investigation を参照（反証チェック・全数調査義務）
• 調査レポートの出力フォーマットは skill:research-report を参照
• 改修フェーズに入る前に skill:rumination（Q1〜Q4）と skill:refactoring（反芻 1・2）を発火せよ
• 完了宣言の前に skill:completion-interlock を参照、debug-report-gate hook が block しないことを確認

---

本スキルは OSS として全 CC ユーザーに開かれた共有資産です。 あなたの寄与（§4 自己拡張ルールに従った提案）が、この思考体系を育てます。 必要な工具がなければ、自分で発明せよ。それがマイナー車整備士の覚悟。