Why

---
name: why
description: "既存のコードや設計がなぜ今の形なのか、なぜその選択をしたのか、退行や障害の経緯、しきい値の根拠を、git・GitHub・Notion・Slackなどの記録から調べ、確からしさを区別して出典付きで答える。'なぜこうなっているのか'、'この値はどこから来たのか'、'この設計にした理由'、コードを変える前に経緯を確かめたいときに使う。コードが今どう動くかの説明（howを使う）や、新しい技術の選定（researchを使う）には使わない。"
---

# Why

コードの背後にある動機と意図を調べる。コードは何をしているかを示すが、なぜ存在するかは示さない。理由はコミット、PR、チケット、文書、会話に残っていて、どれも不完全で偏っており、欠けていることもある。

## 姿勢

慎重で正確な調査者として振る舞う。分かっていることと推測していることを区別する。確からしさの段階と書き方は[`references/epistemics.md`](references/epistemics.md)に従い、回答を書く前に全文を読む。

## 1. 対象と問いを決める

対象は、たいていコードの一部、パターン、機能、名前の付いた設計判断である。問いは、設計の理由、トレードオフ、動機になった例外的なケース、外部の制約、使われていないコード、経緯の広い調査などである。

対象があいまいなら（「なぜこうしているの？」で指すものがない）、会話の文脈（開いているファイル、最近の編集、直前の話題）から最もありそうなものを選び、解釈を短く述べてから進める。

問いに仮説が含まれていたら（「たぶん性能のためだと思うけど」）、それを結論として扱わず、候補の1つとして独立に確かめる。

## 2. コード上の起点を固める

調査の前に、次をまとめる。この起点はすべての情報源の調査と最後の統合に使う。

- ファイルパスと行範囲、主要なシンボル（関数、クラス、定数）
- 対象に最後に触れたコミット: `git blame -L <start>,<end> <file>`
- 名前の変更を追った全履歴: `git log --follow -p -- <file>`
- PR番号が見える最近のコミット: `git log --oneline -20 -- <file>`
- コミットからのPR番号の抽出: `git log -1 --format=%B <commit>`
- 実質的なコミットのPR本文と議論: `gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`
- コミットやPR本文にあるチケットID

## 3. 情報源ごとに調べる

既定では、使える情報源を網羅する。最小限ではなく、どこを調べてどこに何もなかったかの地図を作ることが目的である。何も見つからなかったことも記録し、調べること自体を省かない。

使える情報源を確かめ、次の分類に当てはめる。

| 分類 | この環境での情報源 | 手順 |
|---|---|---|
| ソース管理の履歴 | git、`gh`（常に使える） | [`sources/code-archaeology.md`](references/sources/code-archaeology.md) |
| Issue・チケット | GitHub Issues（`gh`）。他のトラッカーのMCPがあればそれも | [`sources/github-issues.md`](references/sources/github-issues.md) |
| 長い文書 | Notion MCP | [`sources/notion.md`](references/sources/notion.md) |
| チャット | Slack MCP | [`sources/slack.md`](references/sources/slack.md) |
| 監視、エラー追跡、分析基盤 | 該当するMCPが接続されていれば | 分類の目的に沿って、上の手順を読み替える |

メールは私的な内容を含むので、ユーザーが求めた場合だけ調べる。

対象のコードが防御的な処理（nullチェック、再試行、タイムアウト、レート制限、フィーチャーフラグ、外部通信の制限、OOM対策）に見えるなら、各情報源で[`sources/incident-postmortem.md`](references/sources/incident-postmortem.md)の観点も加える。

各情報源の調べ方と、情報源ごとに残す記録の形は[`references/investigation.md`](references/investigation.md)に従う。既定では自分で情報源を1つずつ調べる。ユーザーがサブエージェントの利用を明示した場合は、情報源ごとに1つのサブエージェントを並列に起動し、`investigation.md`を起点の情報と問いと一緒に渡す。1つのサブエージェントに複数の情報源を持たせない。

各情報源の記録の「追加の手がかり」（別の情報源への参照）は、その情報源を調べるときに必ずたどる。その情報源をすでに調べ終えていたら、手がかりだけを対象にもう1回調べる。

情報源を省いてよいのは次の2つだけで、理由を最後の「調べた情報源」に書く。

- その分類のMCPがこの環境にない。選択ではなく欠落として書く。例:「チャット: Slack MCPが接続されていないため未調査」
- その情報源が対象と無関係だと証明できる。「たぶん無関係」では足りない。例:「エラー追跡: 対象は実行時のコード経路を持たないビルドスクリプトのため未調査」

1つのコミットで完結する小さな対象で、PR本文がすでに完全な答えを含んでいる場合は、他の情報源を調べても新しいことが出ないと確かめたうえで、その場で答えてよい。その場合はそう明記する。

## 4. 統合する

情報源ごとの記録を、自分で重みづけして1つの答えにまとめる。

- 同じPR、チケット、文書を複数の情報源が挙げていたら、1つの出典にまとめる。
- 食い違う記録は両方示し、片方を選ばない。
- 主張ごとに確からしさの段階を決め、段階に合った書き方をする。
- 出典が実在し、そう書かれているかに自信がなければ、コードを読むかMCPで確かめる。
- 開いた問いは、もっともらしい推測で埋めずに開いたまま残す。

## 5. 答える

[`references/output-format.md`](references/output-format.md)の形で答える。確からしさの書き分けは、読みやすさのために言い換えない。

既定では会話で答える。ユーザーが保存を求めたとき、またはコードを変える前提の調査で、あとから見直す必要があるときは`.tmp/research/YYYYMMDD_why_{topic}.md`にも保存する。

## 避ける失敗

- **新しさへの偏り。** 最新のコミットを決定的なものと見なすこと。今の形は、多くの古い判断が積み重なった結果であることが多い。さかのぼる。
- **後付けの合理化。** 今見て筋が通るコードに、当時のきれいな理由を当てはめること。
- **コードを自分の意図の証拠にすること。** コードは仕組みであって動機ではない。