How

---
name: how
description: "既存のコードやシステムが今どう動いているか（仕組み、処理の流れ、どこに何があるか、どの層やモジュールが持つべきか）を、コードを読んで説明する。'どうなっているか'、'仕組みを教えて'、'この処理の流れ'、'これはどこに置くべきか'、変更の前に既存の仕組みを理解したいときに使う。なぜ今の形なのか（経緯）は`why`、技術の選定は`research`を使う。"
---

# How

コードベースを読み、「Xはどう動いているか」に答える。担当を引き継いだ経験のあるエンジニアが、その領域で作業を始められるだけの理解を作る。注釈付きのソースコードのような細かさにはしない。

## 1. 範囲を決める

問いが曖昧なら、自分の解釈を1文で書いて進める。ユーザーは後から直せる。

- **小さい問い**（1つのモジュール、小さな関数、狭い問い）: 手順2を省き、読んで直接答える。
- **大きい問い**（複数のファイルやサービスにまたがるサブシステム、横断する機能、全体の構成）: 手順2に進む。

迷ったら小さい方で扱う。

## 2. 観点に分けて読む（大きい問いだけ）

問いを2〜4の観点に分ける（例: 入口から出口までの流れ、データの形、外部との境界）。観点ごとに順に読み、次をメモする。

- 主な部品: 型、サービス、クラス、抽象。名前、ファイル、1文の説明。
- 処理の流れ: どの関数がどのファイルで何をし、次に何を呼ぶか。間を流れるデータ。
- 読んだファイル
- 境界: ほかの部分とつながる場所、入力と出力。
- 意外な点: 見た目と違う動き、歴史的な事情、間違えやすいところ。
- 分からなかった点

参照関係と型はLSPを優先し、`rg`で補う。観点どうしで食い違ったら、コードを読み直して決める。

## 3. 要になる主張を確かめる

説明の要になる主張は、`file:line`を示せるところまで確かめる。実行して確かめるのが安ければ実行する。外部の状態を変える操作はしない。

## 4. 説明する

次の形で答える。当てはまらない節は省く。

- **概要**: これは何で、何をしていて、なぜあるのか。1〜2段落。ここだけ読めば、続きを読むか決められるようにする。
- **主な概念**: 以降を読むのに必要な型、サービス、抽象。短い定義だけ。
- **どう動くか**: 最も長い節。何がきっかけで、何が順に起き、データがどこへ流れ、どこで分岐するか。疑似コードではなく文章で書き、具体的な関数とファイルの名前を出す。大きなコードの引用は、要点に欠かせない場合だけにする。複数の部品がやり取りする、データが段階的に変わる場合は、図（mermaid、単純なものはテキストの図）を入れる。文章で足りるなら図は入れない。
- **どこにあるか**: 作業を始めるのに必要なファイルとディレクトリだけ。
- **落とし穴**: 見た目と違う動き、意外な振る舞い、歴史的な事情。なければ省く。
- **分からなかったこと**: 追い切れなかった点を隠さずに書く。

「`UserService`が`AuthClient.refresh()`を呼ぶ」のように具体的に書き、「サービスがクライアントに処理を委ねる」のような抽象的な言い方をしない。複雑なものは、なぜ複雑なのかを説明する。単純なものを膨らませない。

短い答えは会話で返す。レビューの対象になる長い説明は、`.tmp/research/YYYYMMDD_{topic}.md`に保存する。

## サブエージェント

既定では使わない。ユーザーが利用を明示した場合だけ、観点ごとの探索役（手順2のメモの項目を返させる）と、それをまとめて手順4の形で書く説明役に分ける。説明役の出力は、会話の文脈に合わせて手を入れる程度にとどめる。