explain-code
既存コードや差分について、どう動くか、なぜその形なのか、名前と書き方の意図を調べ、ユーザーが自分の言葉で説明できるように結論から順に説明する skill。コードは変更しない。
SKILL.mdskills/explain-code/SKILL.md
GitHubExplain Code
この skill は明示的に呼び出された場合のみ使用する。
$explain-code
$explain-code <知りたいこと>
- 対象の指定がなければ、現在の作業ツリーの変更を、stage 済みの変更と未追跡のファイルも含めて対象にする。
- 作業ツリーに変更がなければ、現在のブランチが既定ブランチから分岐した点(merge-base)からの差分を対象にする。 どちらもなければ、説明する対象がないことを伝えて終える。
- 対象が指定されていれば、そのコード、差分、仕組みを対象にする。
目的
ユーザーが対象を理解し、自分の言葉で説明できる状態にする。 要約を渡すことではなく、理解してもらうことを目的にする。
差分が対象なら、ユーザーが自分のコードとして説明できる状態を目指す。 仕組みが分かるだけでは足りない。なぜその名前で、なぜその書き方なのかまで説明できるようにする。
この skill では、コードを変更しない。
Workflow
- 持ち帰ってほしいことを決める
- どう動くかを調べる
- なぜその形なのかを調べる
- 名前と書き方の意図を調べる
- 一度で説明する
1. 持ち帰ってほしいことを決める
ユーザーが対象を理解したあとに説明できるべきことを、2〜3 個に絞る。
会話から、次を読み取って決める。
- なぜ知りたいか。例えば変更、レビュー、デバッグのため、または初めて触るため
- すでに知っていること
すでに知っていることは説明しない。 読み取れないことを、質問を重ねて聞き出さない。
2. どう動くかを調べる
入口から結果までを読む。
- 処理の入口と、受け取る入力
- 主要な型と、その型が表すもの
- どの条件で何を判断するか
- いつ状態を変え、どの副作用を起こすか
- 何を結果として返すか
- 失敗したときに何が起きるか
ファイル名を挙げるだけで済ませない。データが入口から結果までどう流れるかを説明できるまで読む。 対象が複数の module にまたがって大きい場合は、観点ごとに subagent へ調査を分けてよい。
3. なぜその形なのかを調べる
理由は、書かれた記録から調べる。
- まだ commit していない変更なら、現在の会話
git logとgit blameで、対象を変えた commit とそのメッセージ- その commit を含む PR の本文とレビューでの議論
- commit や PR からリンクされている Issue
commit は、対象の行を最後に変えたものから順にたどり、理由が見つかったところで止める。 ユーザーに頼まれた場合だけ、これ以外の情報源も調べる。 ユーザーの目的が「どう動くか」だけなら、この手順を省く。
理由は、根拠の強さで 3 つに分けて書く。
- 書かれている: commit、PR、Issue、コメントに理由が書かれている。出典を示して言い切る
- 推測: 書かれてはいないが、状況から読み取れる。根拠を並べ、「〜と考えられる」と書く
- 不明: 探したが見つからない。どこで何を探したかを書く
コードがそうなっていることを、そう意図した根拠にしない。 ユーザーが仮説を添えて聞いた場合も、確かめずに肯定しない。他の可能性と並べて、根拠で判断する。 根拠どうしが食い違う場合は、両方を出典つきで示す。
ユーザーが対象を変更するつもりなら、最後に次を整理する。
- 守るべきこと
- 変えてよいこと
- 変えると壊れるおそれがあること
4. 名前と書き方の意図を調べる
対象が差分のときに行う。
次のものについて、意図を調べる。
- 呼び出し側から見える名前。関数、型、引数、モジュールの名前
- 処理の流れを決めている書き方。分岐の置き方、関数の分け方、失敗の返し方など
ローカル変数のように、意図がコードから明らかなものは省く。
それぞれについて、選んだ名前や書き方と、その意図を 1 行で書く。
実際に成り立つ別案があったものだけ、選ばなかった名前や書き方と、選ばない理由を添える。 成り立つ別案がなかったものに、無理に別案を作らない。 選ばない理由も、手順 3 と同じく、根拠の強さ(書かれている、推測、不明)を分けて書く。
意図は、会話、commit、PR に残っている記録から調べる。 記録がなければ「推測」と明記し、コードと周りの既存コードから読み取れる根拠を並べる。
5. 一度で説明する
持ち帰ってほしい 2〜3 点を、結論から順に一度で説明する。 続きを聞き直す往復を生まないよう、途中で止めない。 各点は、最初の 1〜2 文だけ読めば要点が分かるように書き、そのあとに詳しい説明を続ける。
- 最初に、対象を一般的な名前で呼び、何であるかを 1〜2 文で書く。そのあと、この repository での使われ方につなげる
- 関数や定数を並べるだけで済ませない。各部分が解いている問題と、動く仕組みを書く
- 読む場所が分かるよう、
path:lineを添える - 3 つ以上の要素が関わる流れは、図のほうが文より早く伝わる場合だけ、図で示す
対象が差分なら、2〜3 点の説明のあとに、手順 4 で調べた名前と書き方の意図を一覧で示す。
理解度を試す質問や、言い直しの要求はしない。 「ここが重要」のように、重要さや難しさを予告しない。そのまま説明する。
文の書き方
- 1 文に 1 つのことを書く
- 何が起きるかを言わない比喩や抽象的な言葉を使わず、起きることをそのまま書く
- 悪い例: 設定が古いと、同期が静かに壊れる
- 良い例: 設定ファイルに
versionがないと、同期処理はエラーを出さずに空の一覧を保存する
- 1 つの概念には 1 つの名前を使い、途中で言い換えない
- 専門用語を使うときは、最初に意味を書く
- 前置きや、これから話す内容の予告を書かない
- 根拠の強さを表す言い方は、言い換えずに残す
返信は説明そのものにする。何を調べたかの作業報告にしない。