explain-code

既存コードや差分について、どう動くか、なぜその形なのか、名前と書き方の意図を調べ、ユーザーが自分の言葉で説明できるように結論から順に説明する skill。コードは変更しない。

SKILL.md

GitHub

Explain Code

この skill は明示的に呼び出された場合のみ使用する。

$explain-code
$explain-code <知りたいこと>
  • 対象の指定がなければ、現在の作業ツリーの変更を、stage 済みの変更と未追跡のファイルも含めて対象にする。
  • 作業ツリーに変更がなければ、現在のブランチが既定ブランチから分岐した点(merge-base)からの差分を対象にする。 どちらもなければ、説明する対象がないことを伝えて終える。
  • 対象が指定されていれば、そのコード、差分、仕組みを対象にする。

目的

ユーザーが対象を理解し、自分の言葉で説明できる状態にする。 要約を渡すことではなく、理解してもらうことを目的にする。

差分が対象なら、ユーザーが自分のコードとして説明できる状態を目指す。 仕組みが分かるだけでは足りない。なぜその名前で、なぜその書き方なのかまで説明できるようにする。

この skill では、コードを変更しない。

Workflow

  1. 持ち帰ってほしいことを決める
  2. どう動くかを調べる
  3. なぜその形なのかを調べる
  4. 名前と書き方の意図を調べる
  5. 一度で説明する

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 つの名前を使い、途中で言い換えない
  • 専門用語を使うときは、最初に意味を書く
  • 前置きや、これから話す内容の予告を書かない
  • 根拠の強さを表す言い方は、言い換えずに残す

返信は説明そのものにする。何を調べたかの作業報告にしない。