write-tour

Write a tour

処理の流れの順に停留所を並べた台本を書き、<worktree>/.conductor/tour.json に保存する。 conductor の Explorer 下区画 (t) がそれを読み、カーソルを場所の行に合わせると右の Viewer がその場所を開く。

$ARGUMENTS

何をツアーするか

引数で決める。どちらでも成果物の形は同じ。

• 引数なし — いまの差分 (git diff の範囲) をレビューのために辿る。
• やることが書かれている — その実装計画として辿る。まだ無いコードの話は narration に日本語で書き、places は「そこに手を入れる既存の場所」を指す。

並べる順

重要度順にしない。処理が流れる順に並べる。 入口から始めて、呼ぶ側 → 呼ばれる側 → 戻り先、と辿る。同じファイルに何度戻ってもよい。読む人が「で、次はどこに行くの」と 思わない並びが正解。

git log や変更行の多さで順番を決めてはいけない。実際にコードを読んで、制御が どう流れるかで決める。

停留所の作り方

1つの停留所は「1つ分かること」。10個を超えたら分かることが多すぎるので割る。

• title — その停留所で何が分かるかを一息で。20 字前後。
• narration — 最初の段落に、前の停留所からなぜここに来るのかを書く。「ここで決めた 行き先を、次はこの表から引く」のように、前との繋がりを一文で。番号だけ振られても 読む人は関連が分からない。次の段落になぜそうなっているか。何をしているかは コードが答えるので書かない。 段落の区切りは空行 (\n\n)。単独の改行は折り返しとして繋がれるので、字数で折らない (折り返しは conductor が区画の実幅で行う)。全部で 120 字くらいまで。
• places — 見せる場所。複数あるとカーソルの上下で切り替わるので、対で見たいもの (呼ぶ側と呼ばれる側、定義と使用箇所) を同じ停留所に入れる。

場所の書き方

{ "path": "crates/conductor-tui/src/route.rs", "start": 40, "end": 49 }

• path — worktree ルートからの相対パス。
• start / end — 1 始まり、両端を含む。既定は囲んでいる関数まるごとにする。 2 行だけで足りるならそれでよいが、「この関数のどこにいるのか」が分からない狭さに しない。
• 両方省くとファイル全体を指す。
• side — 省略すると後像 ("new")。削除された行を指すときだけ "old" にし、 start / end には削除前の行番号を書く。

行番号を推測で書かない。 書き終えたら、全ての start / end をファイルの行数と 機械的に照合し、照合した件数と範囲外の件数を報告する。目で確かめたと書くだけに しない。conductor は存在しない行を指す場所に「その行は無い」と表示するので、作り話は そのまま見える。

保存する形

<worktree>/.conductor/tour.json に書く。schema_version は 1。

{
  "schema_version": 1,
  "title": "キー入力の行き先",
  "stops": [
    {
      "title": "キーの行き先を1か所で決める",
      "narration": "分岐が散ると IME の未確定文字が外に漏れる。\n\n既定は consume。",
      "places": [
        { "path": "crates/conductor-tui/src/route.rs", "start": 40, "end": 78 },
        { "path": "crates/conductor-core/src/keymap/context.rs", "start": 35, "end": 50 }
      ]
    }
  ]
}

説明し残しは自分で申告しなくてよい

conductor 側が差分と突き合わせて、どの停留所も触れていない変更を末尾に 「誰も説明していない変更」として自動で連結する。だから漏らしたものを申告する必要は ないし、埋めるために薄い停留所を足す必要もない。