code-walkthrough

コードの解説

検証済みのツアーを使用します。まず実際のコードと出力を確認し、その後、変更しない Navi ツアーに沿って注目点を案内します。

セッションを準備する

1. termctrl、Neovim 0.10 以降、および navi.nvim が利用できることを確認します。

2. プロジェクトのルートで Neovim を前面に表示した状態で起動します。

   termctrl run walkthrough -- nvim
   

3. 別のプロセスから Terminal Control を使い、同じセッションを調べて操作します。可能な場合は Terminal Control MCP 経由で interact を使用してください。それ以外の場合は、termctrl show、termctrl send、termctrl wait を使用します。

4. 表示されているターミナルの幅が狭すぎる場合は、ツアーを作成する前にサイズを変更します。発表または録画中はサイズを一定に保ちます。

人とエージェントが同じ状態の Neovim 画面を見ており、エージェントが Terminal Control を通じて画面を確認できれば、セッションの準備は完了です。

説明の筋道を決める

1. ゴールが不明確な場合は、視聴者が最後に何を理解し、何を説明できるようになってほしいかを尋ねます。
2. 関連するコードを読み、現在の動作を証明できる最小限のコマンドを実行します。
3. 実際に表示された結果を確認します。予想や記憶に基づいてメモを書かないでください。
4. 概念上の筋道を一つ選びます。たとえば、公開された動作から、その動作を生み出す仕組みへ進み、最後に観測された結果を示す流れが有効です。

概要、失敗の診断、実装の解説、修正を一つの流れにまとめないでください。計画した各停止位置が、一貫した一つの問いに答えるために必要なら、筋道は定まっています。

変更しないツアーを一つ作成する

ツアーが一時的なものなら、ソースツリーの外に JSON ファイルを作成します。一意で安定したパターンにはリテラルパターンを使用し、正確な位置が重要な場合に限り行番号を使用します。

[
  {
    "file": "src/example.test.ts",
    "pattern": "it(\"updates subscribers\"",
    "end_pattern": "expect(runs).toBe(2)",
    "message": "The public contract starts here: one write must cause one additional run."
  },
  {
    "file": "src/example.ts",
    "pattern": "export function notify",
    "end_pattern": "subscriber()",
    "message": "The implementation reaches every subscriber through this loop."
  }
]

変更せずに読み込みます。

:NaviLoad /absolute/path/to/tour.json

次のルールを適用します。

• アシスタントの応答ごとに作成できるツアーは最大一つです。
• 表示したツアーは変更しないものとして扱います。同じ応答内で停止位置やメモを書き換えないでください。
• 実装の詳細に入る前に、動作または呼び出し箇所から始めます。
• 隣接する行が一つの単純な仕組みを成す場合は、範囲指定の停止位置を一つ使用します。
• 複数の停止位置を使うのは、異なる場所を結ぶ明確な筋道がある場合に限ります。
• 説明の大部分は、短く自然な Navi のメモに記載し、チャットは簡潔に保ちます。
• 動作の説明に役立つ場合は、要点となる検証済みの出力を簡潔に記載します。
• 検証結果が説明を否定する場合は、そこで止めてその旨を伝えます。ツアーをクリアまたは置き換えるのは、次の応答に限ります。

すべての停止位置が解決され、最初の停止位置が表示され、そのメモが検証済みのコードと出力に一致していれば、ツアーは完成です。

ツアーを発表する

進行を任せてほしいと頼まれない限り、ペースは視聴者に委ねます。

]n           next stop
[n           previous stop
<leader>np  pick a stop
<leader>nc  clear the tour

以下は推奨されるキー割り当てであり、Navi のデフォルト設定ではありません。利用できない場合は、:NaviNext、:NaviPrev、:NaviPick、:NaviClear を使用します。

アクティブなツアーを置き換えずに、質問を受け付けます。追加の説明では現在の範囲に焦点を当てたり、出力を確認したりできますが、別の概念上の筋道は、後のツアーで扱います。

OBS で録画する

自然な進行、ナレーション、ウィンドウの枠、その他の視覚的なコンテキストを含め、人向けの発表を成果物にする場合は OBS を使用します。

1. termctrl run を含むターミナルウィンドウの Window Capture ソースを追加します。
2. 録画前に、無関係なタブ、プロンプト、通知、個人情報を含むパスをクロップして除外します。
3. 録画時と同じようにメモが折り返されるよう、ツアーを作成する前にターミナルのサイズ、フォントサイズ、OBS のキャンバス、キャプチャ範囲を設定します。
4. 短いテスト録画を行います。テキストの読みやすさ、マイク音量、ターミナルのコントラスト、Navi のメモが切れずに収まっていることを確認します。
5. OBS の録画を開始して変更しないツアーを発表し、最後のフレームが十分な時間表示されて読めることを確認してから録画を停止します。

この方法では、OBS が主な録画手段です。Terminal Control は引き続き、エージェントの操作と検証に使用します。

ターミナルの証跡を保持する

ユーザーが OBS による全画面のプレゼンテーションではなく、ターミナル上での再生、スクリーンショット、またはデバッグの証跡を必要としている場合は、Terminal Control のアーティファクトを使用します。

• termctrl save walkthrough --format png --out artifacts/current を使うと、いつでも現在の画面をキャプチャできます。

• セッションの開始時に記録を有効にしておく必要があります。すでに実行中のフォアグラウンドセッションに、現時点では記録を追加できません。

• ターミナル上で再生できる記録を作成するには、プレゼンテーションの前に --record を指定して意図的に再起動します。

  termctrl run walkthrough --record artifacts/walkthrough.termctrl -- nvim
  

• 重要な場面にマーカーを追加し、セッション終了後に記録を確認するか、エクスポートします。

  termctrl mark walkthrough contract
  termctrl mark walkthrough mechanism
  termctrl markers artifacts/walkthrough.termctrl
  termctrl video artifacts/walkthrough.termctrl --out artifacts/walkthrough.mp4
  

ユーザーがそのアーティファクトを明示的に必要としていない限り、秘密情報が含まれる可能性のあるターミナルへの入力、ソース、パス、出力を記録または保持しないでください。

終了

ユーザーが開いたままにすることを希望していない限り、ツアーを消去してセッションを停止します。

:NaviClear

termctrl stop walkthrough

検証済みの動作、提示した一連の操作、保持したアーティファクトのパスを報告します。閲覧者が一連の操作を完了し、ターミナルセッションが要求された最終状態になり、約束したすべてのアーティファクトが確認されていれば、ウォークスルーは完了です。

ツールの参照先

• Terminal Control：https://github.com/anomalyco/terminal-control
• Navi：https://github.com/kitlangton/navi.nvim