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]/references/*.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. 外部の知識を集める（必要な場合）

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

調査戦略の詳細については、references/when-to-research.mdを参照してください。

</evidence_gathering>

<root_cause_analysis>

A. 仮説を立てる

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

1. ［仮説 1］ — ［具体的な証拠］があるため
2. ［仮説 2］ — ［具体的な証拠］があるため
3. ［仮説 3］ — ［具体的な証拠］があるため

B. 各仮説を検証する

各仮説について、次のことを行います。

• 何があれば仮説が正しいと証明できますか？
• 何があれば仮説が誤りだと証明できますか？
• 最小限のテストを設計する
• テストを実行し、結果を記録する

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

C. 排除する、または確定する

次のことに回答できるまでは先に進まないでください。

• 証拠によって裏付けられている仮説はどれですか？
• 他の仮説に反する証拠は何ですか？
• 追加で必要な情報は何ですか？

</root_cause_analysis>

<solution_development>

根本原因を確認した後にのみ、以下を行います。

A. 解決策を設計する

• 根本原因に対処する最小限の変更は何ですか？
• 起こり得る副作用は何ですか？
• 何が壊れる可能性がありますか？

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

• 変更を加える
• 動作を検証する必要があれば、ログやデバッグ出力を追加する
• この変更が根本原因に対処する理由を記録する

C. 十分にテストする

• 元の問題は引き続き発生しますか？
• 再現手順は正しく動作するようになりましたか？
• 関連するテストがあれば実行する
• 関連機能にデグレードがないか確認する

包括的な検証方法については、references/verification-patterns.mdを参照してください。

</solution_development>

</quick_start>

<critical_rules>

1. 場当たり的な修正は禁止：変更が機能する理由を説明できないなら、変更しないでください
2. すべてを検証する：前提をテストしてください。実際のコードを読んでください。実際の動作を確認してください
3. すべてのツールを使う：
   • 外部知識には MCP サーバー
   • エラーメッセージ、ドキュメント、既知の問題にはウェブ検索
   • 複雑な推論には拡張思考（「深く考える」）
   • 完全なコンテキストの把握にはファイルの読み込み
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>

より詳しいトピックについては、参考ファイルを参照してください。 デバッグの考え方: references/debugging-mindset.md

• デバッグに応用する第一原理思考
• 不適切な修正につながる認知バイアス
• 体系的な調査の規律
• いつ調査を止め、新たな前提でやり直すべきか

調査手法: references/investigation-techniques.md

• 二分探索／分割統治法
• ラバーダックデバッグ
• 最小再現
• 目標の状態から逆算する
• コードを変更する前に可観測性を高める

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

• 反証可能な仮説を立てる
• 仮説を証明または否定する実験を設計する
• 強い証拠と弱い証拠を分けるもの
• 仮説が誤っていた場合に適切に立て直す

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

• 「動作した」だけではない、「検証済み」の定義
• 再現手順のテスト
• 関連機能の回帰テスト
• 修正前にテストを書くべき場合

調査戦略: references/when-to-research.md

• 外部の知識が必要であることを示す兆候
• 調査すべきことと、推論すべきこと
• 調査時間と実験のバランス </advanced_topics>