1natsu Hunk

Hunk Review

Hunk に同梱された公式スキル（hunk-review）へ接続するためのラッパー。人間がこのコマンドを打つだけで、パス解決・セッション確認・上流スキルの読み込みまで済ませ、レビューに入る。

上流スキルが正本。 このラッパーとコマンドの綴り・オプションが食い違ったら、読み込んだ上流スキルに従う。Hunk の CLI は更新されるが、このラッパーは追従しない。

初回接続

1. セッションを確認する

hunk session list --json

• セッションがある → 工程3へ。
• hunk コマンドが見つからない → 未インストール。その旨を伝えて終了する。
• 「No active Hunk sessions」 → ここで人間に起動を頼む前に、サンドボックスを疑う。Hunk はローカルデーモン経由で通信するため、エージェントのサンドボックスが localhost を塞いでいると、TUI が動いていてもセッションが無いように見える。ネットワーク制限を外して1度だけ再試行し、それでも空なら工程2へ。

2. セッションが無いとき

TUI は人間のもので、エージェントは hunk diff / hunk show を起動しない。次のように依頼して待つ:

別のターミナルで、レビューしたいリポジトリのルートで hunk diff を実行し、そのウィンドウは開いたままにしてください。起動したら教えてください。

代替手段に流れないこと。 git diff を自分で読んでレビューを書き始めるのは、このスキルの目的（人間が Hunk の画面で変更を見ながら AI の注釈を受け取る）を壊す。人間の起動を待つか、明示的に別のやり方を指示されるまで進めない。

3. 上流スキルを読み込む

hunk skill path

出力されたパスのファイルを読む。パスにはバージョン番号が含まれる（例: .../hunk/<version>/libexec/skills/hunk-review/SKILL.md）ため、過去のセッションで見た値や記憶したパスを再利用せず、毎回このコマンドで解決する。

解決に失敗した場合のみ、同一ソースから生成された公開版 https://www.hunk.dev/docs/hunk-review-skill.md を取得して代用し、インストール版ではなく公開版を使ったことを人間に伝える（差異が出うるため）。

4. レビューを進める

セッション選択・構造の把握・navigate・コメント投入は、読み込んだ上流スキルの手順に従う。

ただし注釈を失わせる操作は独断で実行しない。session reload は表示を差し替えるだけでなく、それまでに積まれた注釈を破棄する。人間が書いた注釈も一緒に消え、対象を元に戻しても復活しない。comment clear / comment rm も同様なので、必要になったら理由を添えて確認を取る。

同じことは Hunk の外の操作でも起きる。git add や commit でレビュー対象の差分が変われば、範囲外に出た注釈は失われる。レビュー中のステージやコミットを自分から仕掛けず、人間に頼まれた場合も注釈が消えることを先に伝える。

以降のやりとり

このスキルはセッションの初回に1度だけ呼ばれる。以降の往復は自然言語で行うので、ここから先はレビューが終わるまで有効な常設の指示として扱う。人間が往復のたびにこのスキルを再実行することは想定しない。

人間が「コメント確認して」等と言ったら、hunk session comment list --repo . --type user で人間の注釈を読み、内容に沿って次の行動を取る。

返す場所を注釈の性質で使い分ける。

• 質問・方針の相談・設計の議論 → 会話で答える。Hunk の note は人間が diff を読む場所であって、議論のスレッドを読む場所ではない。長文の検討をそこへ書き込まない
• コードに紐づく指摘・所見 → 該当行へ navigate してから note を置く
• 修正の実施 → コードを直し、直した旨は会話で伝える。Hunk の表示を差し替える必要があれば session reload を提案する（人間の視界を奪うので承認を取る）

自分以外の所見を載せるときは --author で人格を分ける。 Hunk へ書き込めるのはセッションの AI だけなので、誰の所見であっても代理で置くことになる。出典を入れないと、実装した本人の弁明と第三者の指摘が同じ重みで並び、人間が「誰の言い分か」で重みづけできなくなる。

値は note の見出しにそのまま使われる（coderabbit-cli note - …）ので、句ではなく短い人格名を選ぶ。

所見をどこから調達するかは問わない。サブエージェントでも外部のレビューツールでも人間の口述でもよく、--author で区別が付いていれば手段は自由に選んでよい。