debug-like-expert

複雑な問題に対する詳細な分析デバッグモードです。このスキルは、標準的なトラブルシューティングで解決できなかった場合に、証拠の収集、仮説の検証、厳密な確認を行う系統的な調査プロトコルを開始します。

このスキルでは、自分が書いたコードを未知のコードよりもさらに厳しく疑うことを重視します。「こう動くはずだ」という認知バイアスによって、実際の実装上の誤りを見落とすことがあるためです。手早く修正するのではなく、科学的手法を用いて根本原因を系統的に特定します。

<context_scan> ドメイン固有のデバッグ知識を検出するため、呼び出しのたびに実行します。

# What files are we debugging?
echo "FILE_TYPES:"
find . -maxdepth 2 -type f 2>/dev/null | grep -E '\.(py|js|jsx|ts|tsx|rs|swift|c|cpp|go|java)$' | head -10

# Check for domain indicators
[ -f "package.json" ] && echo "DETECTED: JavaScript/Node project"
[ -f "Cargo.toml" ] && echo "DETECTED: Rust project"
[ -f "setup.py" ] || [ -f "pyproject.toml" ] && echo "DETECTED: Python project"
[ -f "*.xcodeproj" ] || [ -f "Package.swift" ] && echo "DETECTED: Swift/macOS project"
[ -f "go.mod" ] && echo "DETECTED: Go project"

# Scan for available domain expertise
echo "EXPERTISE_SKILLS:"
ls ~/.claude/skills/expertise/ 2>/dev/null | head -5

調査を開始する前に、検出結果を提示します。 </context_scan>

<domain_expertise> ドメイン固有の専門知識は ~/.claude/skills/expertise/ にあります。

ドメインスキルには、デバッグ、テスト、パフォーマンス、よくある落とし穴など、包括的な知識が含まれています。調査の前に、ドメイン固有の専門知識を読み込むべきか判断します。

<scan_domains>

ls ~/.claude/skills/expertise/ 2>/dev/null

ここで利用可能なドメイン固有の専門知識（例：macos-apps、iphone-apps、python-games、unity-games）を確認します。

専門知識のスキルが見つからない場合： ドメイン固有の専門知識を使わずに続行します（適切にフォールバックします）。一般的なデバッグ手法で問題なく対応できます。 </scan_domains>

<inference_rules> ユーザーの説明やコードベースにドメインを示すキーワードが含まれている場合、そのドメインを推定します。

キーワード／ファイル	ドメインスキル
"Python"、"game"、"pygame"、ゲームループを含む ".py"	expertise/python-games
"React"、"Next.js"、".jsx/.tsx"	expertise/nextjs-ecommerce
"Rust"、"cargo"、".rs" ファイル	expertise/rust-systems
"Swift"、"macOS"、"AppKit/SwiftUI" を含む ".swift"	expertise/macos-apps
"iOS"、"iPhone"、"UIKit" を含む ".swift"	expertise/iphone-apps
"Unity"、Unity のインポートを含む ".cs"	expertise/unity-games
"SuperCollider"、".sc"、".scd"	expertise/supercollider
"Agent SDK"、"claude-agent"	expertise/with-agent-sdk

ドメインを推定した場合は、次のように確認します。

Detected: [domain] issue → expertise/[skill-name]
Load this debugging expertise? (Y / see other options / none)

</inference_rules>

<no_inference> 明らかなドメインがない場合は、選択肢を提示します。

What type of project are you debugging?

Available domain expertise:
1. macos-apps - macOS Swift (SwiftUI, AppKit, debugging, testing)
2. iphone-apps - iOS Swift (UIKit, debugging, performance)
3. python-games - Python games (Pygame, physics, performance)
4. unity-games - Unity (C#, debugging, optimization)
[... any others found in build/]

N. None - proceed with general debugging methodology
C. Create domain expertise for this domain

Select:

</no_inference>

<load_domain> ドメインが選択された場合、そのスキルの参照資料をすべて読み込みます。

cat ~/.claude/skills/expertise/[domain]/reference/*.md 2>/dev/null

これにより、調査前にドメインの包括的な知識を読み込みます。

• よくある問題とエラーパターン
• ドメイン固有のデバッグツールと手法
• テストと検証の方法
• パフォーマンスのプロファイリングと最適化
• 既知の落とし穴とアンチパターン
• プラットフォーム固有の考慮事項

次のように伝えます。「[domain] の専門知識を読み込みました。ドメイン固有のコンテキストに基づいて調査します。」

ドメインスキルが見つからない場合： ユーザーにその旨を伝え、一般的な手法で続けるか、専門知識を作成するかを提案します。 </load_domain>

<when_to_load> ドメインが分かっている場合、調査前にドメイン固有の専門知識を読み込みます。

ドメイン固有の専門知識が不要な場合：

• 純粋な論理バグ（ドメインに依存しない）
• 一般的なアルゴリズムの問題
• ユーザーが明示的に「ドメインコンテキストを省略して」と指定した場合 </when_to_load> </domain_expertise>

このスキルは、標準的なトラブルシューティングで解決できなかった場合に有効になります。手早く修正するのではなく、系統的な調査が必要な問題に対応します。科学的な厳密さをもってデバッグするシニアエンジニアの姿勢で取り組みます。

重要： デバッグ対象のコードを自分が作成または変更した場合、そのコードの動作に関して認知バイアスが生じています。「こう動くはずだ」という自分のメンタルモデルは間違っているかもしれません。自分が書いたコードを未知のコードよりもさらに厳しく疑ってください。自分自身の思い込みを見落としている可能性があります。

<core_principle> 推測せず、検証する。 すべての仮説を検証します。すべての「修正」を確認します。証拠のない解決策は提示しません。

特に重要： 自分が設計または実装したコードは、無実が証明されるまで有罪です。意図は関係ありません。重要なのは、コードが実際にどう動作するかだけです。自分の設計判断も、他者の判断と同じ厳しさで問い直します。 </core_principle>

<quick_start>

<evidence_gathering>

解決策を提案する前に： A. 現在の状態を文書化する

• 正確なエラーメッセージまたは予期しない動作は何ですか？
• 再現するための正確な手順は何ですか？
• 実際の出力と期待される出力の違いは何ですか？
• いつから正しく動作しなくなったのか（判明している場合）？

B. システムを把握する

• エントリーポイントから失敗箇所までの実行パスを追跡する
• 関与するすべてのコンポーネントを特定する
• 関連するソースファイルをざっと見るだけでなく、完全に読む
• この領域に影響する依存関係、インポート、設定を記録する

C. 外部ナレッジを収集する（必要な場合）

• MCP サーバーを使用して、API ドキュメント、ライブラリの詳細、またはドメイン知識を取得する
• エラーメッセージ、フレームワーク固有の動作、最近の変更について Web 検索を使用する
• 意図された動作と実際に観測された動作について公式ドキュメントを確認する
• 既知の問題、破壊的変更、バージョン固有の癖を探す

リサーチ戦略の詳細なガイダンスについては、reference/when-to-research.md を参照してください。

</evidence_gathering>

<root_cause_analysis>

A. 仮説を立てる

証拠に基づいて、考えられる原因を列挙します：

1. [仮説 1] - [具体的な証拠] が理由
2. [仮説 2] - [具体的な証拠] が理由
3. [仮説 3] - [具体的な証拠] が理由

B. 各仮説を検証する

各仮説について：

• 何がこれを真実だと証明するか？
• 何がこれを偽だと証明するか？
• 最小限のテストを設計する
• 実行して結果を文書化する

科学的手法の適用については、reference/hypothesis-testing.md を参照してください。

C. 排除または確認する

以下に答えられるようになるまで先に進まないでください：

• どの仮説が証拠によって支持されているか？
• どの証拠が他の仮説と矛盾しているか？
• どのような追加情報が必要か？

</root_cause_analysis>

<solution_development>

根本原因を確認した後にのみ：

A. 解決策を設計する

• 根本原因に対処する最小限の変更は何か？
• 潜在的な副作用は何か？
• これによって何が壊れる可能性があるか？

B. 検証しながら実装する

• 変更を加える
• 動作を検証するために必要ならログ/デバッグ出力を追加する
• この変更がなぜ根本原因に対処するのかを文書化する

C. 徹底的にテストする

• 元の問題はまだ発生するか？
• 再現手順は正しく動作するようになったか？
• 存在する場合は関連するテストを実行する
• 関連機能のリグレッションがないか確認する

包括的な検証アプローチについては、reference/verification-patterns.md を参照してください。

</solution_development>

</quick_start>

<critical_rules>

1. 行きがけの修正は禁止: なぜ変更が機能するのか説明できないなら、それを行わないでください
2. すべてを検証する: 前提をテストしてください。実際のコードを読んでください。実際の動作を確認してください
3. すべてのツールを使用する:
   • 外部ナレッジには MCP サーバー
   • エラーメッセージ、ドキュメント、既知の問題には Web 検索
   • 複雑な推論には拡張思考（「深く考える」）
   • 完全なコンテキストにはファイルの読み取り
4. 声に出して考える: 各ステップでの推論を文書化してください
5. 一度に一変数: 一度に一つのことだけを変更し、検証してから次に進んでください
6. 完全な読み取り: コードを流し読みしないでください。関連するファイル全体を読んでください
7. 依存関係を追跡する: 問題がライブラリ、設定、外部システムに関わる場合は、それらも調査してください
8. 以前の作業を疑う: 以前の「修正」が間違っていたかもしれません。新鮮な目で再検討してください

</critical_rules>

<success_criteria>

開始する前に：

• ドメインを検出するためにコンテキストスキャンを実行した
• 利用可能かつ関連する場合はドメインの専門知識を読み込んだ

調査中に：

• 問題がなぜ発生したのかを理解していますか？
• 修正が実際に機能することを検証しましたか？
• 元の再現手順をテストしましたか？
• 副作用を確認しましたか？
• 解決策を他の人に説明できますか？
• この修正はコードレビューを通過するでしょうか？

これらすべてに「はい」と答えられない場合は、調査を続けてください。

重要: このチェックリストを通過するまで、デバッグタスクを完了としてマークしないでください。

</success_criteria>

<output_format>

## Issue: [Problem Description]

### Evidence
[What you observed - exact errors, behaviors, outputs]

### Investigation
[What you checked, what you found, what you ruled out]

### Root Cause
[The actual underlying problem with evidence]

### Solution
[What you changed and WHY it addresses the root cause]

### Verification
[How you confirmed this works and doesn't break anything else]

</output_format>

<advanced_topics>

より深いトピックについては、リファレンスファイルを参照してください： デバッグのマインドセット: reference/debugging-mindset.md

• デバッグに適用する第一原理思考
• 悪い修正につながる認知バイアス
• 体系的に調査するための規律
• いつ止めて、まっさらな仮定で再開すべきか

調査テクニック: reference/investigation-techniques.md

• 二分探索 / 分割統治
• ラバーダックデバッグ
• 最小再現
• 望ましい状態から逆算する
• コードを変更する前に可観測性を追加する

仮説検証: reference/hypothesis-testing.md

• 反証可能な仮説の立て方
• 証明/反証する実験の設計
• 強い証拠と弱い証拠を分けるもの
• 誤った仮説から潔く立ち直る方法

検証パターン: reference/verification-patterns.md

• 「検証済み」の定義（単に「実行できた」ではない）
• 再現手順のテスト
• 隣接機能のリグレッションテスト
• 修正前にテストを書くべきタイミング

リサーチ戦略: reference/when-to-research.md

• 外部知識が必要だと示すシグナル
• 検索すべきことと推論すべきこと
• リサーチ時間と実験のバランス

</advanced_topics>

結果のサイドカーを出力する

最後のステップとして、~/.claude/skill-analytics/last-outcome-debug-like-expert.json に書き込みます:

{"ts":"[UTC ISO8601]","skill":"debug-like-expert","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"hypotheses_tested":[n],"root_cause_found":[bool],"fix_verified":[bool]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに "partial" を使用します。出力がまったく生成されなかった場合にのみ "error" を使用します。