| name | .claude/skills/troubleshooting-guides/SKILL.md |
| description | 問題解決を効率化するトラブルシューティングガイドの設計スキル。
📚 リソース参照:
このスキルには以下のリソースが含まれています。
必要に応じて該当するリソースを参照してください:
- `.claude/skills/troubleshooting-guides/resources/problem-classification.md`: Problem Classificationリソース
- `.claude/skills/troubleshooting-guides/templates/diagnosis-flow-template.md`: Diagnosis Flowテンプレート
- `.claude/skills/troubleshooting-guides/templates/error-explanation-template.md`: Error Explanationテンプレート
- `.claude/skills/troubleshooting-guides/scripts/validate-diagnostic-flow.mjs`: Validate Diagnostic Flowスクリプト
|
| version | 1.0.0 |
Troubleshooting Guides スキル
概要
このスキルは、ユーザーが自力で問題を解決できるよう支援する
トラブルシューティングガイドの設計・作成技術を提供します。
診断フロー、エラー分類、段階的な解決策の提示方法を扱います。
問題解決パターンの体系化
診断フロー設計原則
- 症状の分類: 問題を明確なカテゴリに分類
- 原因特定チェックリスト: 段階的に原因を絞り込む質問セット
- 解決方法の優先順位付け: 成功率と難易度に基づく順序
- エスカレーションパス: セルフサービス解決不可時の明確な誘導
診断フローチャート構造
問題発生
↓
症状の特定
↓
カテゴリ分類 ─┬─ 接続問題
├─ 認証問題
├─ データ問題
└─ 操作問題
↓
原因の特定（チェックリスト）
↓
解決策の適用
↓
解決？─┬─ Yes → 完了
└─ No → 次の解決策 or エスカレーション
エラー分類体系
プロジェクト標準エラーコード
| コード範囲 |
カテゴリ |
ユーザー対応 |
| 1000-1999 |
Validation Error |
入力を修正して再試行 |
| 2000-2999 |
Business Error |
権限・リソースを確認 |
| 3000-3999 |
External Service Error |
時間をおいて再試行 |
| 4000-4999 |
Infrastructure Error |
サポートに連絡 |
| 5000-5999 |
Internal Error |
即座にサポートに連絡 |
ユーザー向けエラー説明テンプレート
## エラー: [エラーコード] [エラー名]
### 意味
[ユーザーが理解できる言葉でエラーの意味を説明]
### 原因
[考えられる原因をリストアップ]
### 解決方法
#### 方法 1: [最も一般的な解決策]
1. [手順 1]
2. [手順 2]
#### 方法 2: [代替の解決策]
1. [手順 1]
2. [手順 2]
### 解決しない場合
[サポートへの連絡方法]
FAQ 構造設計
FAQ 組織化パターン
# よくある質問（FAQ）
## カテゴリ: [機能/操作別]
### Q: [ユーザーが実際に使う言葉での質問]
**A**: [簡潔な回答]
[必要に応じて詳細説明]
**関連**:
- [関連する FAQ]
- [関連するドキュメント]
効果的な FAQ 質問の書き方
| 悪い例 |
良い例 |
| 「認証について」 |
「パスワードを忘れた場合はどうすればよいですか？」 |
| 「エラー対処」 |
「「接続できません」というエラーが表示されたらどうすればよいですか？」 |
| 「設定変更」 |
「通知メールの受信を停止するにはどうすればよいですか？」 |
FAQ 優先順位付け
| 基準 |
説明 |
重み |
| 頻度 |
問い合わせ件数 |
高 |
| 影響度 |
業務への影響 |
中 |
| 緊急性 |
即座の対応が必要か |
中 |
| 自己解決可能性 |
ユーザーが自分で解決できるか |
高 |
解決策の記述
段階的解決手順
### 解決方法
#### ステップ 1: [最も簡単な確認]
- [ ] [確認項目]
- 結果: [期待される結果]
→ 解決した場合は完了。解決しない場合は次へ。
#### ステップ 2: [次の確認/操作]
- [ ] [確認項目]
- 結果: [期待される結果]
→ 解決した場合は完了。解決しない場合は次へ。
#### ステップ 3: [より詳細な対応]
...
解決策の優先順位
- 自己解決可能: ユーザーが単独で実行可能
- 設定変更: 管理者権限が必要だが自己解決可能
- 再起動/リセット: サービス影響があるが自己解決可能
- サポート連絡: 専門的な対応が必要
エラーメッセージ解説
解説構造
## エラー: "[エラーメッセージ全文]"
### これは何ですか？
[専門用語を使わない説明]
### なぜ起こりましたか？
[最も一般的な原因]
- [原因 1]
- [原因 2]
### どうすればよいですか？
**今すぐできること**:
1. [即座に試せる対処法]
**それでも解決しない場合**:
1. [追加の対処法]
### データへの影響
[作業中のデータがどうなるか]
### 予防方法
[今後同じエラーを避けるには]
検索性の最適化
キーワード設計
<!-- 検索用キーワード（非表示） -->
[//]: # "keywords: ログイン, 接続, エラー, 認証, パスワード"
症状ベースのインデックス
## 症状から探す
### 「○○ できない」
- [ログインできない](#login-issues)
- [ファイルを保存できない](#save-issues)
- [データが表示されない](#display-issues)
### 「○○ が遅い」
- [ページの読み込みが遅い](#slow-loading)
- [処理が終わらない](#long-processing)
### 「○○ が表示される」
- [エラーメッセージが表示される](#error-messages)
- [警告が表示される](#warnings)
トラブルシューティングチェックリスト
ガイド品質チェック
ユーザビリティチェック
スクリプトリファレンス
# 診断フロー検証
node .claude/skills/troubleshooting-guides/scripts/validate-diagnostic-flow.mjs docs/troubleshooting/
# 検証項目:
# - エラーコードの一意性（1000-5999範囲）
# - 診断ステップの存在
# - 解決策の存在と成功率
# - 内部リンクの有効性
# - 診断フローの完全性
リソース参照
| リソース |
パス |
内容 |
| 診断フローテンプレート |
.claude/skills/troubleshooting-guides/templates/diagnosis-flow-template.md |
診断フローチャート作成用 |
| エラー解説テンプレート |
.claude/skills/troubleshooting-guides/templates/error-explanation-template.md |
エラーメッセージ解説用 |
| 問題分類ガイド |
.claude/skills/troubleshooting-guides/resources/problem-classification.md |
問題カテゴリ分類の詳細 |
| 診断フロー検証 |
.claude/skills/troubleshooting-guides/scripts/validate-diagnostic-flow.mjs |
トラブルシューティングドキュメント検証 |
関連スキル
.claude/skills/user-centric-writing/SKILL.md: ユーザー中心ライティング.claude/skills/tutorial-design/SKILL.md: チュートリアル設計.claude/skills/information-architecture/SKILL.md: ドキュメント構造設計