revidere

revidere

変更を節に分け、各節に重要度と懸念を付け、全ての変更行がちょうど 1 つの節に属することを目指したレビューを作る。 属しているかはスクリプトが検査し、直しきれなかった漏れはページに出る。 最後に、差分の抜粋と GitHub へのリンクを載せたページを Artifact で出す。

$ARGUMENTS

引数にベース (origin/main など) があれば、手順 1 で --base に渡す。

手順

スクリプトは python3 "${CLAUDE_SKILL_DIR}/scripts/revidere.py" で走らせる (以下 revidere.py)。 標準ライブラリだけで動き、conductor は要らない。スクリプトは利用者の index や作業ツリーに何も書かない。 自分で差分を読むときも、index を書き戻す git diff ではなく git diff-index -p -M を使う。

1. 台帳を作る。 revidere.py prepare [--base <ref>] をリポジトリの中で走らせる。 1 行目に作業 dir (毎回 $TMPDIR の下に新しく作られる) が、続いて範囲と変更位置の台帳が出る。 exit 2 はベースが決められない等の失敗、exit 3 は差分が無い。どちらも出た文をそのまま利用者に伝えて終える。
2. 読む。 今のブランチ以外を読むときは git worktree add で作業コピーを作らない (大きいリポジトリでは 取り出すだけで分単位かかる)。作業ツリーが clean なら git switch で切り替えて回し、終わったら戻す。 出た範囲のとおり git diff-index -p -M <base> を自分で走らせ、変更されたファイルと、必要なら 呼び出し元・呼び出し先まで読む。未追跡ファイルはこの差分に出ないが台帳には載っているので、 台帳にあって差分に出ないパスは新規追加として中身を読む。段階 3 は変更されたコードだけでは書けない。
3. 書く。 下の「レビューの規則」に従った JSON を <作業dir>/review.json に書く。
4. 検査する。 revidere.py check <作業dir>。exit 0 なら次へ。
   • exit 1 (説明もれ): 出た位置を既存の節に足すか新しい節を作り、既に分類できている位置の割り当ては 変えずに、全体を <作業dir>/review.retry.json に書いて revidere.py check <作業dir> --retry。 直した答えは説明もれが減ったときだけ採られる。直しは 1 回だけ。残っても次へ進む (ページに残りが出る)。
   • exit 2 (読めない・欄が欠けている): 名指しされた欄を直して review.json を書き直し、もう一度 check。 2 回直しても通らなければ、出た文を利用者に伝えて終える。
5. ページにする。 revidere.py render <作業dir> が <作業dir>/review.html を書いてパスを出す。
6. 出す。 ページには変更したコードの抜粋がそのまま載る。そのことを利用者に 1 行で伝えてから、 Artifact ツールで review.html を publish し、リンクを返す。Artifact ツールが無いセッションなら、 使えないと伝えて review.html のパスを返す。 同じ会話で別のページ (積んだ PR の他の段など) を出していたら、その後のコミットや動作確認の たびに全ページと積んだ PR の本文を並べ、事実が変わるかを 1 行ずつ書き、変わるものは出し直す。

コードへのリンクは、origin が GitHub で、指す側のコミットが origin に push 済みのときだけ付く。 未コミットの変更や未 push のコミットはリンクの代わりに理由が出る。抜粋はページの中にあるので読める。

レビューの規則

読む人が次の 3 段階でレビューを進められるように、変更を整理する。

段階 1 — 抽象で掴む

毎回同じ 5 欄を同じ順で埋める。PR description ではなく、読む側の型。

• problem — 何が不足・破綻していたか。新機能なら「〜を足したい」もここ
• change — 追加・変更した責務を 1〜2 文。関数名の列挙ではなく責務で書く
• mechanism — 既存の何と新規の何が、どう繋がって動くか
• placement — なぜそのディレクトリ・型なのか。他の候補を退けた理由があれば書く
• scope — ファイル数と、実際に読むべき数