この記事は、編集レビューのプロセスをエージェントのスキルに変えた経緯を記録したものである。レビューの対象はコードではなく文章であり、その点でこの wiki のエージェント型コードレビューに関する記録とは珍しい隣人の関係にある。ここでもエージェントがレビュアーの役割に置かれるが、エージェントに適用させるのは、明示的なルールファイルとして書き起こされたチーム自身の編集上の知見である。
述べられている問題は、抽象的な量ではなく集中である。2 人が年間およそ 100 本の記事をレビューしており、そのため作業は特定の個人に依存し、時間がかかり、指摘漏れが生じて修正の往復が繰り返されやすい。機械的な校正は GitHub Actions 上の textlint のチェックですでにカバーされていたため、チームが埋めようとしたのは、ルールベースの lint では表現できないレビューの観点だった。
要点
- スキルは意図的に 2 つに分けられている。手順と出力形式を定める短い
SKILL.mdと、レビューのルールそのものを記したrules.mdである。著者はルールファイルこそが実質的な部分だとしている。 - ルールは一から書かれたわけではない。GitHub CLI で収集したリポジトリ内の 3 年分の過去のレビューコメントを Claude Code に与えてルールの草案を作らせ、その草案を人手で洗練させた。著者は、蓄積されたレビューの履歴を掘り起こせる資産として提示している。
SKILL.mdはスキルのツールをファイルの読み込みと URL の取得に制限している。後者は、レビューの一環として記事のリンク切れをスキルが確認できるようにするためである。- スキルはブログ執筆用のリポジトリに置かれており、著者の報告ではプロジェクトスキルとして自動的に有効になる。レビュアーは、手元にない記事についても URL を与えることでスキルに対象を指定でき、スキルは GitHub CLI を通じてそれを取得する。
- 出力形式はスキルの定義で固定されている。行番号、観点、修正の要約、そして修正前後を示す diff ブロックであり、スキルには実際の問題だけを報告し、「問題なし」の項目は省くよう指示されている。
- 著者は、ルールでカバーされていない観点の例として、スキルが行頭の余計なスペースを検出したことを報告している。また、誤ったファイル名を検出したことを意外な事例として特に挙げている。広く知られたサービス名の範囲を超えていたからである。
- カバー率は直接測定されたのではなく推定されたものである。過去の 30 件のプルリクエストのレビューコメントをルールファイルと照らし合わせて分類したところ、およそ 75% がカバーできることが示唆された。残りの 4 分の 1 は、文章の圧縮や再構成、表現が適切かどうか、どこに説明を加えるべきかといった、コンテキストを要する判断だとされている。
- 指摘は提案として扱われ、自動的には適用されない。著者はその理由を具体例で示している。スキルは誤った URL を正しく特定したが、日本語のドキュメントの代わりに英語のドキュメントを提案し、それを人が修正しなければならなかった。
- ルールは一律にではなく、人間の判断とともに適用される。記事は口語的な表現の例を挙げている。ルールはそれを推奨していないが、書き手の気持ちがよりよく伝わるイベントレポート記事では、チームはそれを残している。
- 機密情報や推測可能な情報が記事に入り込んでいないかを確認する責任も人間に残されている。著者はこのカテゴリーを委ねようとはしていない。
- 著者は、ルールファイル内の例文は、特定の記事が識別できないよう、生成された草案から人手で書き換えたと述べている。
背景
他の選択肢ではなくスキルを選んだ理由についての記事の議論は、能力ではなく運用モデルに関するものである。ブラウザベースのアシスタントでは記事の本文を行ったり来たりコピーする必要がある。同じ仕組みをレビューチームだけでなく書き手のセルフレビューにも使える。ルールを GitHub に置けば誰でもプルリクエストで変更を提案できる。そして任意利用から始めれば、何かを自動化する前に精度を高めていける。チームは、Claude Code GitHub Actions や Devin にプルリクエストへ自動でコメントさせるよりもこちらを明確に好み、任意利用から始めて徐々に精度を上げることを望んだ。
効果についての著者の主張は慎重に述べられており、その多くはスループットではなくレビュアーの注意に関するものである。修正案を考える時間が減り、レビューの観点が個人の経験やスキルに依存しにくくなり、細部を委ねることで構成や読みやすさに注意を向けられるようになった。カバー率の数字は、過去のコメントを分類して導いた推定値として示されており、実際に使われているスキルの測定値ではない。また書き手による利用は始まったばかりで、セルフレビューはまだ必須ではないとされている。
表明されている今後の意向には、レビュー結果をルールにフィードバックすること、Claude Code 以外のツールへの対応の可能性（著者は、ルールを別ファイルにしておくことで移植可能になると指摘している）、そして関心があればスキルをオープンソース化することが含まれる。いずれも実施済みとは報告されていない。この記事が応用している基盤の仕組みについては、Agent Skills と Claude Code を参照。