explain-code

PR・実装・概念など、対象が何をしていてなぜそうなっているかを噛み砕いて説明する。既定は俯瞰で、図と表で構造を見せ、内部の呼び名を開き、要点は file:line で指す。求められれば逐行へ切り替え、抜粋を主役にして文法も開く。ユーザーが「解説して」「噛み砕いて」「これ何やってるの」「読み解いて」「/explain-code」等を指示したときに使う。一緒に辿るなら /walk-code、レビューコ

SKILL.md

GitHub

対象が何をしていて、なぜそうなっているかを噛み砕いて説明します。実装を読んで裏を取り、図と表で構造を見せるのが既定です。

目的は把握。 そのコードが今どうなっているかを掴んでもらうところまでで、読む力そのものを鍛えるのは /walk-code、指摘から学びを残すのは /explain-review-comments の役目です。

説明だけを行い、コードは書き換えません。

対象

引数 例 読むもの
PR 番号 / URL 3002 gh pr view の本文と gh pr diff の差分
ファイル / 関数 / 型 import_csv.go / BulkCreate Read / Grep で実コード
概念・仕組み 「変更履歴の作られ方」 関係するコードを横断で探す

--focus で観点(「テストの意図を中心に」)または粒度(「1行ずつ」「実装レベルで」)を指定できる。自然文で添えられた場合も同じに扱う。

扱わないものが2つある。 どちらも出口が違うので、そちらへ渡す。

求められているもの 渡す先 なぜ
レビューコメントの意図 /explain-review-comments 出口が対応可否の判断と、次に自分で気づけるようになること。変更案・影響・推奨に学びを添えるまでが1セット
一緒に辿りたい / 読む力をつけたい /walk-code 渡し方と渡すものが違う。1区切りずつ止まりながら進み、どう突き止めたかを毎回渡す

判定は「読み終えた人が次に何をするか」。 理解して他へ進むなら本スキル、自分のペースで辿るなら /walk-code、対応するかを決めるなら /explain-review-comments。

粒度を先に決める

同じ対象でも、読み手の問いが2通りあります。 どちらかで骨格が変わるので、書き始める前に決める。

俯瞰(既定) 逐行(求められたとき)
答える問い なぜこの形なのか この行は何をしているか
骨格 図と表と「なぜ」 抜粋そのもの
進む向き 構造の内側から外へ コードの上から下へ / 処理順
抜粋 少数。根拠を1点だけ 主役。かたまりごとに1個
文法・言語機能 1行に留める 開く
分量 畳む 長くてよい(畳むと役目を失う)
読み終えた人は 全体像を得る その1本を自分で読めるようになる

逐行へ切り替えるのは、求められたときだけ。 「1行ずつ」「実装レベルで」「コードを追って」と言われた場合と、対象が1つの関数で中身の順序が主題の場合。

迷ったら俯瞰。 逐行は情報量が多く、俯瞰が無いまま渡すと現在地が分かりません。両方要るなら俯瞰を先に、続けて逐行。

以下の1〜4と7は両方に効きます。5は粒度で読み替え、6は俯瞰のときだけです。

進め方

1. 実物で裏を取る

PR 本文やコメントの記述をそのまま信じない。 本文は書いた時点のもので、その後の変更で古くなっています。実装を読んでから書く( verify_before_asserting.md )。

  • PR なら gh pr diff で差分を見て、要点になるファイルは Read で前後の文脈まで読む
  • 関数なら定義と呼び出し元の両方を見る。使われ方が分からないと「なぜ」が書けない
  • 型なら組み立てている場所を見る。ゼロ値で使われるのか、コンストラクタを通すのか
  • 「変更前はどうだったか」が要るなら git show <base>:<file> で比べる
  • 仕組みが複数のファイルやサービスにまたがるなら、調べる段を pstack の how (どう動くか)と why (なぜその形か)に任せる。返ってきたものを、習熟度に合わせて開くのは本スキル

逐行では特に大事です。 読み下しは断定の連続になるので、推測が混ざっても気づかれません。

2. 構造を図にする

順序・分岐・関係が主題なら、散文で書かずに図にする。 ```mermaid タグ付きのフェンスで出す。**TUI では図になりませんが、貼り先(Notion 等)でそのまま図として扱えます**( report_formatting.md )。

使い分けと、描いた図の判定は concise_first_then_detail.md の「畳み方」が持つ。 ここには説明固有の事情だけを置く。

主題 使うもの
処理の順序、その順でないと壊れる理由 flowchart LR
複数の登場人物のやりとり、並行操作の衝突 sequenceDiagram
テーブルの関係 erDiagram

図が役立つのは「並べて見ないと分からない」ものです。1本道の処理や、名前を見れば分かることに図は要りません。

逐行では図は基本要らない。 順に追う説明なので、図を入れると視線がそこで止まります。例外は、書かれている順と走る順が違うとき( sequenceDiagram で走る順を先に見せる)。

3. 内部の呼び名を開く

型名・関数名・SQL ファイル名をそのまま置かない。 読み手はそのコードを知りません。

そのまま置かない 開く
BulkCreate を追加 複数件をまとめて作る入口を追加
排他ロックを取得 対象の行に鍵をかける
トランザクション内で 1つの保存処理の中で
snapshotBeforeUpdate 変換で書き換わる前の値を控える

識別子を出すなら、何をするものかを一言添える。 消すのではなく、初見で意味が取れる形にする。

4. 「なぜ」まで届かせる

何をしているかだけでは足りない。 読み手が知りたいのはたいてい次のどれかです。

  • なぜこの形なのか。 素直に書くとどうなり、それの何が困るのか
  • 崩すと何が起きるか。 順序を入れ替えたら / この行を消したら
  • どこが壊れやすいか。 特にエラーにならずに、気づかないうちにおかしくなる箇所

「気づかないうちにおかしくなる」ものは必ず書く。 落ちてくれる問題は気づけますが、履歴が空になる・値が0になる類は気づかれません。そこが説明の要る唯一の理由であることも多い。

逐行でも同じです。 かたまりごとに1行添える。無いなら書かないほうが、ある所が目立ちます。引数を詰め替えているだけの所に「なぜ」はありません。

5. 実物へ繋ぐ

解説を読んだ後、読み手はその実物を開きます。 開く先を書かないと、説明はその場で読み捨てになる。

要点になった箇所は file:line で指す( report_formatting.md )。名前だけ挙げて済ませない。

繋ぎ方は対象の大きさで変わる。 3のとおり呼び名は開いたうえで、そこへ行き先を添える。

対象 繋ぎ方
1つの関数・1つの判断 該当行1つだけ。 読む順も索引も要らない
関数・ファイル1つ 要点になった数行を指す
PR・機能全体 6の「読む順」まで出す

俯瞰では、抜粋は主役ではない

指すだけでは、読み手はその形を想像で補います。 判断が畳まれている数行は、その場で見せる。

ただし骨格は2〜4のとおり図と表と「なぜ」で、抜粋はその根拠を1点だけ見せるもの。貼った瞬間にコードの読み下しへ流れるので、次の3つで止める。

歯止め 中身
1つの節に1個まで 抜粋が2個続いたら、それは逐行に切り替わっている。求められていないなら戻す
消しても成立するなら消す 抜粋が無いと伝わらない所にだけ残す
文法の解説へ流れない 開くのはそのコードが採った判断であって、言語機能ではない。補足が要るなら1行に留める

3つ目が最も踏みやすい。 読み手がその言語に不慣れなほど「ここも開いたほうが親切」に見えますが、開くべきは判断のほうです。文法を3節ぶん書くと、要点がその下に埋まります。

逐行では、抜粋が主役になる

上の3つの歯止めを外します。 かたまりごとに貼り、文法も開く。

読む単位に切る。 行単位では細かすぎ、関数単位では粗すぎます。

切り方 目安
1かたまり5〜20行 検証・組み立て・分岐・後始末など、目的が1つのまとまり
順序は基本コードの上から 読み手はファイルを開いて上から見るため
ただし処理順が違うならそちら 早期 return、遅延実行、並行処理。その旨を言ってから走る順で説明する

切った単位に見出しを付ける(「引数の検証」「保存する形へ組み替える」)。1かたまりに1抜粋。2回貼るなら切り方が粗い。

値を持ち回る。 「ここで受け取った値が、次はこの引数に入ります」と繋ぐと、かたまりが分断されません。

文法・言語機能は、どこまで開くかを言語ごとの習熟度で決める( plain_language_explanation.md と user_context.md )。

習熟度 開く範囲
初心者の言語 言語機能そのものから(レシーバ、埋め込み、遅延実行、並行処理の起動、ポインタと値の違い 等)
中級の言語 込み入った型・初見のライブラリ・その言語特有の落とし穴だけ
強みの言語 一般的な用語はそのまま。そのコード固有の仕掛けだけ

そのコードに出てくるものだけを開く。1つにつき2〜4行。 「ついでに関連する機能も」と広げると、読み下しが言語入門にすり替わります。

抜粋の作法(粒度を問わず)

  • 俯瞰なら5〜15行、逐行なら5〜20行。 関数まるごとは貼らない。省いた所は // ... で明示する
  • 書き換えない。 整形して見やすくすると、実物と違うものを見せることになる
  • 直前に file:line、直後に読み方

貼るかどうかの判断(俯瞰のとき)。

抜粋する 指すだけ
その数行に判断が畳まれている(比較から何を外したか、default が何を返すか) 一本道の処理
見た目が意外(3行しかない / 同じ検証を2回している) 名前から中身が想像できる
コメントが根拠を持っている 定型のエラーラップ・引数の詰め替え

「読み方」は次の3つのどれか。

型 例
どこに目を留めるか 「この !ok が要点」
何が書かれていないか 「表示名を比べていない」「並び順の指定が無い」
崩すとどうなるか 「この行を消すと差分が出なくなる」

真ん中が最も役立ちます。 書かれていないものは、貼っても言われなければ見えません。読み手は目の前にある行しか追えない。

読み方を書けない抜粋は貼らない。 「〜という実装です」しか添えられないなら、file:line で足ります。

6. 大きい対象では、読む順を出す

俯瞰のときだけ。 機能やレイヤーを跨ぐ対象は、説明を読んでも「どこから読めばいいか」が残ります。全ファイルを並べても、読み手は結局どれから開くか決められない。

読み終えたときに自分で続きを読める状態になっているかまでが範囲です。

  • 停留所を3〜5個に絞る。 ファイルの列挙ではなく、どの順に何が分かるかを出す。依存の内側から外へ、処理の順に、など対象に合う軸で
  • 重心を名指しする。 「最初に読むならここ」を1〜2か所。残りはそこから導けるもの
  • 疑問 → 場所の索引を作る。 読んでいて「なぜ?」となる所を、答えのあるコメントや実装の行へ繋ぐ。表にすると引きやすい
  • テストが仕様書として読めるなら、それも渡す。 境界や「どう変えたら何が起きるか」は、実装よりテストのほうが早く分かることが多い

全部を出さない。 停留所も索引も、読み手が自分で辿れるようになるための最小限でよい。網羅は目的ではありません。

7. 分量と締め

長さは対象の複雑さと粒度で決める。散文が続いたら畳めていない合図です。

  • 結論を先に置く。 「この PR は〇〇をします」から入り、細部は後
  • 逐行なら、冒頭に3〜5行の見取り図。 「この関数は4つのかたまりでできています」と先に言うと、読み手が現在地を把握できる
  • 俯瞰なら、最後に1つの表でまとめる(変更 + 何のため)。逐行では要らない。本文が既に順を追っているので、同じ情報を2度持つことになる
  • 末尾に、次に読むと繋がる場所を1〜2個(呼び出し元、対になる実装、テスト)

出力の目安

俯瞰。

対象 目安
関数・判断1つ 10行程度。図は要らないことが多い。該当行1つを添え、抜粋は0〜1個
関数・ファイル1つ 10〜20行 + 必要なら図1つ + 抜粋1〜2個
PR 全体 見出しで区切り、図2〜4個 + 表。仕掛けごとに節を分ける。抜粋は節をまたいで2〜3個
機能・レイヤーを跨ぐもの 上記 + 読む順と索引を別の節に立てる。解説と混ぜない

この数は上限であって目標ではない。 図と表で伝わるなら抜粋は0個でよく、そのほうが前段の骨格が読まれます。

逐行。

対象 目安
関数1つ(〜50行) かたまり2〜4個。抜粋は各1個
ファイル1つ(〜300行) かたまり5〜10個。見出しで区切る
それ以上 範囲を絞るか、2回に分ける。1回で読み下せる量には限りがある

やってはいけないこと

  • コードを書き換えること。 説明だけを行う。修正が要るなら指摘に留め、ユーザーの指示を待つ
  • 実物を読まずに PR 本文の要約を返すこと。 本文が古い可能性があり、それを裏取りするのがこのスキルの中心
  • 呼び出し元を見ずに逐行を書くこと。 その場の行だけでは意味が決まらない
  • 内部の呼び名をそのまま並べること。 読み手はそのコードを知らない
  • 1本道の処理に図を足すこと。 図は並べて見ないと分からないものに使う
  • 設計原則の名前で説明を済ませること(「Tell-Don't-Ask だから」等)。そのコード固有の事情を書く
  • 網羅のために全ファイルを列挙すること。要点になる箇所だけ
  • 要点を名前だけで指すこと。 読み手が grep から始めることになる。file:line で開ける形にする
  • 関数を丸ごと貼ること。 意味のまとまりで切る。切れないなら対象が大きすぎる
  • 抜粋を整形・改変すること。 実物と違うものを見せることになる
  • 抜粋に読み方を添えないこと。 貼っただけでは説明になっていない
  • 求められていないのに逐行へ流れること。 俯瞰では1つの節に抜粋2個続いたら流れている
  • 俯瞰で文法・言語機能の解説を始めること。 開くのは判断であって文法ではない
  • 逐行で「ついでに関連する言語機能も」と広げること。 そのコードに出てくるものだけ。広げると言語入門にすり替わる
  • 逐行を要約して畳もうとすること。 順に追うためのもので、畳むと役目を失う
  • 小さい対象に読む順を付けること。 関数1つなら該当行1つで足りる。停留所も索引も過剰
  • 実装手順(ステップ1, 2, 3…)を勝手に添えること。聞かれたら出す

関連

  • /walk-code (一緒に辿るウォークスルー): 兄弟。 説明する内容は近いが、あちらは辿り方そのものを渡す(1区切りずつ止まり、次をどう突き止めたかを添える)。読む力をつけたいなら、はじめからあちら
  • /explain-review-comments (レビューコメントの意図): 同じ explain 系。 あちらは指摘から学びを残すのが目的。指摘の前提になっているコードを深く読むなら、あちらから本スキルへ渡ってくる
  • plain_language_explanation.md (噛み砕いた説明): 土台。どこまで文法を開くかはあちらが決める。 言語ごとの習熟度は user_context.md
  • concise_first_then_detail.md (簡潔に): 図と表で畳む判断はあちらが持つ
  • report_formatting.md (報告に貼る識別子の書式): file:line で指す規定はあちらが持つ。本スキルは、その上に読む順の案内を足す
  • verify_before_asserting.md (断定の前に裏を取る): 逐行は断定の連続になる。推測が混ざると気づかれない
  • /review-pr (他人の PR をレビューする): あちらは良し悪しを判断する。本スキルは理解を助けるだけで、指摘はしない