Write Tour

---
name: write-tour
description: "コードを処理の流れの順に辿る「ツアー」の台本を書き、conductor が読む .conductor/tour.json に保存する。差分のレビュー用と、実装計画用の両方。"
disable-model-invocation: true
---

# 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` — 見せる場所。複数あるとカーソルの上下で切り替わるので、**対で見たいもの
  (呼ぶ側と呼ばれる側、定義と使用箇所) を同じ停留所に入れる**。

## 場所の書き方

```json
{ "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`。

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

逆に言えば、そこに大量に積まれていたら台本が仕事をしていない。差分の主軸は必ず
自分の停留所で説明すること。

## 書き終わったら

保存したパスと停留所の数だけを伝える。台本の中身を会話に貼り直さない
(conductor の画面で読むもの)。