# Debug Root Cause

> バグの調査・修正をするとき。「このバグ直して」「エラーの原因を調べて」「なぜか動かない」等で使う。再現 → 切り分け → 根本原因の特定 → 回帰テスト → 修正 → 水平展開の順で進め、原因を説明できないまま症状だけ消す対症療法で終わらせない。

- Skill: `turntuptechnologies-ai/debug-root-cause` (Agent Skill)
- Install (CLI): `npx skillmds@latest add turntuptechnologies-ai/debug-root-cause`
- Raw SKILL.md: https://api.skillmd.com/api/skills/turntuptechnologies-ai/debug-root-cause/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: turntuptechnologies-ai (https://skillmd.com/u/turntuptechnologies-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/turntuptechnologies-ai/debug-root-cause

---


# バグ調査・修正（debug-root-cause）

## このスキルがやること

バグを「再現を観測してから、原因を説明できる状態にして、テストで再発を防いで」直す。推測で直す・症状だけ消すのを防ぐための順序の固定。

## 手順

1. **再現する**: 最小の再現手順を確立し、失敗を**実際に観測**する。再現できないうちは修正に進まない。
   - 再現できない場合 → ログ・エラーメッセージ・環境差（OS/バージョン/データ）・発生条件の情報収集に戻る。それでも不能なら「再現不能」と、分かったこと・足りない情報を報告して指示を仰ぐ。
2. **切り分ける**: 疑わしい範囲を半分に絞る操作（`git bisect`・入力の最小化・レイヤー境界での観測など）を繰り返す。
3. **根本原因を特定する**: 「そのコードが、その入力で、なぜその症状を起こすか」を**一文で説明できる**状態まで。症状が消えた ≠ 原因が分かった。
4. **回帰テストを書く**: 修正の**前に**バグを踏む失敗するテストを書き、red であることを確認する。
   - テストが書けない領域（環境依存・UI 目視等）→ 理由を報告し、手動再現手順を修正の説明に記録する。
5. **修正する**: 根本原因に対する最小の変更。テストが green になることを確認する。
6. **水平展開を確認する**: 同じパターンのバグが他に無いか（同じ関数の他の呼び出し元、コピペされた類似コード、同じ誤った前提を持つ箇所）を grep 等で確認する。

## 報告フォーマット

必ずこの構成で報告する:

```markdown
## 症状
<何が起きていたか（再現手順つき）>

## 根本原因
<一文で。例: `parseDate()` がタイムゾーン無しの文字列を UTC として解釈するため、JST 環境で日付が 1 日ずれる>

## 修正内容
<何をどう変えたか（path:line）>

## 回帰テスト
<追加したテストと、修正前 red → 修正後 green を確認した旨。書けなかった場合は理由>

## 水平展開
<同種の箇所を確認した結果（あり→どうしたか / なし）>
```

## ルール・コツ

- **修正候補が複数思いつく段階は、まだ原因が特定できていないサイン**。修正に進まず切り分けに戻る。
- 「とりあえず try/catch」「とりあえず null チェック」は症状隠しになりやすい。なぜその値が来るのかを一段遡ってから判断する。
- `git bisect` 中に作業ツリーを変更しない。開始前に未コミット変更が無いことを確認する。
- 再現に本番データや外部サービスが必要な場合は、勝手に触らずユーザーに確認する。
- 修正とリファクタを混ぜない。修正過程で見つけた別の問題は create-issue で起票する。

## 完了条件

以下を全て満たしたら完了。**満たせない項目があれば、黙って省略せず理由を報告する。**

- [ ] 修正前に失敗（再現）を実際に観測した（再現不能の場合はその旨と収集した情報を報告した）
- [ ] 根本原因を一文で説明した
- [ ] 修正前に失敗し修正後に通る回帰テストを追加した（不能な場合は理由と手動再現手順を報告した）
- [ ] 水平展開の確認結果を報告した
- [ ] 報告フォーマットの全節（症状/根本原因/修正内容/回帰テスト/水平展開）を埋めた

## 補足

- 社名・内部 URL・認証情報などの固有情報は扱わない。
- 修正を PR にする場合は pre-pr-checks → create-pr へ続ける。