「実装前レビュー」をHTML1枚で回す — Akapen（review-before-build）スキルの設計を読む

エージェント時代の一番高い失敗は「認識ズレのまま完走される」こと

コーディングエージェントに仕事を任せたとき、最も高くつく失敗はバグではない。依頼者の頭の中と違うものが、完成度高く出来上がってしまうことだ。 バグは動かせば分かるが、認識ズレは「動くけれど欲しかったものではない」という形で最後に判明する。 そして判明した時点では、作り直しのコストが最大化している。

この問題への対処は大きく2系統ある。ひとつは事後——書かれたコードや差分をレビューする系統で、 PRレビューやセルフレビューツールがここに入る。もうひとつは事前——書く前に方針を人に確認する系統だ。 後者の代表が、プランを質問攻めで詰める grill-me のような対話型スキルだった。

ただし対話型には弱点がある。UIの配置や画面設計のように「絵にしないと判断できない論点」を文章で聞かれても、人は想像で補ってしまう。 結果として「お任せします」が並び、ゲートとして機能しない。 この弱点を正面から潰しにいったのが、本記事で読む Akapen（赤ペン）というスキルである。

Akapen とは — 1案をHTML1枚にして、回答を貼り戻してもらう

Akapen は Claude Code の Agent Skills として作られた「実装前レビュー」のワークフローだ。 本記事が一次情報として読んだ公開実装はntaksh42/dotfiles の claude/skills/review-before-buildで、ここでは akapen から改名され、赤ペン由来の語彙も「レビュー」に統一されている （固定形の見出しも 【赤ペン回答】 から 【レビュー回答】 に変わった）。 本記事では通称として Akapen、実装名として review-before-build を使う。

入力は「見せたい1案（UI配置・設計・方針、または長文の原稿）＋決めてほしい論点」。 出力は ./review/<topic>-01.html というHTML1枚だ。ここが設計上のポイントで、サーバも外部ネットワークも要らず、file:// で開いて完結する。 人はブラウザで案を見て回答し、末尾の [貼り付ける文章を作る] ボタンで生成されたテキストをターミナルに貼り戻す。

sequenceDiagram
    participant A as エージェント
    participant P as 試問subagent
    participant S as シート（HTML 1枚）
    participant H as 人間

    A->>A: 「使わない条件」に該当しないか確認
    A->>S: 1案をシート化（問いは3±1問）
    A->>P: シートのパスと読者宣言だけ渡す
    P->>A: 落ちた問い＋理由を報告
    A->>S: 絵を足す／問いを落とす／言い換える
    A->>H: file:// でブラウザに開く
    Note over A: 【レビュー回答】が貼られるまで<br/>実装は開始しない
    H->>H: 回答して [貼り付ける文章を作る]
    H->>A: 固定形テキストを貼り戻し
    A->>A: 反映して実装へ

3つのモード — 「人が何を返すか」で選ぶ

Akapen は対象によって3モードを使い分ける。分岐の基準が「対象の種類」ではなく「人が返すものの型」である点が実務的だ。人が指摘や注文を返すなら指摘モード、本文そのものを書き換えて返すなら添削モード、それ以外は標準モードになる。

長文向けの2モードには共通の禁則がある。読み物を要約したシートに組み直さないこと。 要約してしまうと訂正対象の本文が人の目から消え、指摘のしようがなくなるからだ。 添削モードは記事Markdownから build-sheet.py でシートを生成し、返ってくるのは差分行ではなく完成形Markdown全文——これをそのまま記事ファイルに書き戻す。

設計① 「使わない条件」をSKILL.mdの先頭に置く

このスキルで最も学ぶところが多いのは、手順ではなく冒頭に置かれた「まずここで止まる — このスキルを使わない条件」の表だと思う。 レビューは確認コストを人に払わせる道具であり、シート1枚の作成は小規模な実装より重いことがある——という前提が明文化されている。

スキルを書くとき、人はつい「いつ使うか」だけを書く。しかし description が広いスキルほど誤発火し、 誤発火したスキルは純粋な損失になる。Akapen は「絵にしないと判断できない論点があるときだけ」と用途を絞り込み、 それ以外の状況には代替手段を名指しで割り当てている。これは description の精度を本文側で補強する手法として汎用性が高い。

設計② 質問票ではなく「絵」— 対立軸は両方を絵にする

Akapen の最重要禁則のひとつが 「レビューは視覚物への訂正であって、質問票ではない」。 UIや画面が対象なら、スクリーンショットの埋め込みかDOM再現で現物を必ず載せる。 質問だけのシートが許されるのは、方針や優先度など絵にできない論点に限られる。

さらに踏み込んでいるのが、選択肢の対立軸は両方を絵にするというルールだ。 推奨案の挿絵だけを並べて選択肢を文字1行にすると、人はAとBの違いを想像で補えず、結局「全問お任せ」に倒れる。 そして回答フォームの選択肢にも同じ絵をコピーする（.thumb）。 人はシート本文を読んでからフォームで答えるので、フォーム側で絵が消えると、選ぶ瞬間にまた想像させることになるからだ。

シートの骨格は11の部品で固定されており、毎回同じ場所に同じものが並ぶ。 キッカー → 主張のタイトル → 結論ボックス（3文以内）→ 用語欄 → 全体図（インラインSVG）→ 短い説明 → 案の対比表 → 問いカード → 畳み付録 → 回答フォーム、という順序だ。 興味深いのは 「問いをシートの先頭に置かない」という明示的な禁止で、 問いを記憶したまま説明を読ませる形になるため、という理由が添えられている。

問いカードは「自己完結」が条件

問いは 3±1問、5問以上は並べない。人の判断コストこそが本体だからだ。各問いカードは以下を満たす。

• 問い1行＋各選択肢の利点1行と代償1行
• 非推奨の選択肢にも「選ぶ理由」を1行書く——代償しか書かれていない選択肢は実質1択で、ゲートとして機能しない
• 判断に要る数値の再掲（本文へ戻らせない）
• 未選択＝お任せ。推奨案には推奨バッジを付け、未回答でも進める形にする
• 各問に file:line か実行結果の引用を添える

最後の項目は「事実を人に聞かない」という原則の実装だ。 コードを読めば分かること、動かせば分かることはエージェント側で潰し、 人に残すのは決定（好み・優先度・トレードオフの裁定）だけにする。

設計③ 出題前の試問 — 文脈ゼロのsubagentで自己評価の甘さを補正

ここが個人的に一番の学びだった。シートを書いたエージェントは題材の全文脈を頭に持っている。 だから「これで伝わる」の自己判定は構造的に甘い。 実際、絵は載っているが問いとは無関係、というシートが「絵を載せた」という形式だけで通ってしまった実例がドキュメントに記録されている。

そこで人に見せる前に、何も知らない subagent にシートのパスと読者宣言1行だけを渡して試問する。 渡さないもの——作業の経緯、元のコード、会話の文脈——が明記されているのが肝で、これがないと検査員も文脈で補ってしまう。

運用ルールも細かい。検査員は general-purpose で立て、fork は使わない（文脈を引き継いでしまうため）。 モデルは sonnet を明示指定する——「何も知らない読者として読む」のに上位モデルは要らず、毎回立てる分コストが効くから。 そしてbackground にせず同期で待つ。結果を受け取る前に応答を終えると、検査を読まずに人へシートを出すことになるからだ。

再試問は同じ検査員に差分だけを送って1回、計2巡で打ち切る。 2巡目に残ったのが軽微（語彙1〜2語・語順）なら出題してよいが、 重大（意味の取れない文・選択肢の弁別不能・事実の矛盾）なら3巡目に進まず、読者宣言に戻ってシートを書き直す。 「検査で磨ける限界を超えているのは、書き手の側の問題だから」という理由が明記されている。

設計④ 貼り戻しは「固定形」— 3モード共通の契約にする

人がブラウザで [貼り付ける文章を作る] を押すと、クリップボードと textarea に次の形のテキストが出る。 エージェントはこの形だけを読めばよい。3モードとも同じボタンが同じ固定形に整形するため、読み取り側の実装は1つで済む。

【レビュー回答】notification-badge

Q1. バッジの位置: A — ヘッダー右上 / 補足: 数字は2桁で省略
Q2. 一覧の並び順: (未選択 = お任せ)

全体へのコメント: 方向性はこれでOK。文言だけ後で詰めたい。

## 指摘
#12 [短くする] 前置きが長い
#15 [ここは良い]

---
上の回答を反映して作業を続けてください。お任せの項目は推奨案で確定してください。

1行目の 【レビュー回答】 と末尾の区切り＋締めの1文は全モード必須・不変。 空の節は出さない（指摘0件なら ## 指摘 自体を出さない）。 そして特筆すべきなのが後方互換の扱いだ。

バージョン番号が2系統ある点も整理されている。シートの体裁は v3（HTML冒頭のコメントに埋め込む）、 回答テキストの契約は 0.3.0。両者は別系統で、混同しないよう各ドキュメントの冒頭に注意書きが置かれている。

自分のスキルに持ち帰れる4点

Akapen をそのまま導入しなくても、スキルを書く人にとって転用できる設計がいくつもある。

flowchart TD
    A[スキルを書く] --> B[1. 使わない条件を先頭に書く<br/>代替手段を名指しで割り当てる]
    B --> C[2. 人に残すのは決定だけ<br/>事実は自分で調べて潰す]
    C --> D[3. 出す前に文脈ゼロの検査を通す<br/>評価軸・打ち切り・直し方をセットで]
    D --> E[4. 人とエージェントの境界を固定形にする<br/>旧版の読み取り互換も書く]
    E --> F[誤発火せず、待たせず、崩れないスキル]

    style B fill:#5b21b6,stroke:#8b5cf6,color:#fff
    style D fill:#1e3a8a,stroke:#3b82f6,color:#fff
    style F fill:#14532d,stroke:#22c55e,color:#fff

1. 「使わない条件」を手順より前に置く。誤発火の損失が大きいスキルほど、 description の精度を本文の否定リストで補強する。しかも代替手段を名指しする。
2. 人に聞くのは決定だけ。事実で一意に決まることを人に投げるのは、確認コストの転嫁でしかない。 各問に file:line を添えるルールは、この原則を機械的に検査可能にした形だ。
3. 自己評価の甘さを構造的に補正する。生成した本人に「これで伝わるか」を判定させない。 文脈ゼロの検査員＋固定の評価軸＋打ち切り回数＋直し方の対応表、までがワンセット。
4. 人とエージェントの境界は契約にする。自由記述で返させず固定形にすれば読み取りが1つで済み、 証跡を残すなら旧フォーマットの読み取り互換も明文化する。

運用上の落とし穴

ドキュメントの Gotchas 節には、実際に踏んだと思われる穴が並んでいる。HTML1枚で完結させる設計ゆえのものが多い。

埋め忘れ検査用の check-sheet.py（Python標準ライブラリのみ）が用意されているのも実務的だ。CHANGE-ME の残り、radio name と質問配列のズレ、選択肢の絵の欠落といった「無言で壊れる不備」を機械的に検出する。添削モードは生成器が同時に検査するので不要、 指摘モードは手作業の移植なので目視チェックリストで通す——と、生成方法ごとに検査手段が割り当てられている。

まとめ — レビューを「重い道具」として扱う

Akapen が徹底しているのは、レビューを気軽な確認ではなく、人の時間を消費する重い道具として扱う姿勢だ。 だからこそ使わない条件が先頭に来て、問いは3±1問に圧縮され、事実は人に聞かず、 出す前に文脈ゼロの検査を通し、回答は固定形で受け取る。

裏を返せば、Human-in-the-loop を組み込んだワークフローがうまくいかない理由の多くは 「人に払わせるコストを設計していない」ことにある、ということでもある。 自作のスキルやエージェントに人間の確認ステップを挟むとき、その確認が人にとって何秒かかり、何を想像で補わせているかを一度数えてみる価値はある。