スキル整備に必要なこと

AIエージェント（Claude Code）で管理画面のE2Eテスト仕様書をレビューした話は、前回の記事に書きました。今回はその続きです。同じ運用を十数画面・何十巡と繰り返すうちに、毎回同じ前提を説明し直していることに気づき、レビューの前提そのものをClaude Codeの「スキル」へ落としました。整備してみて必要だと分かったことを書き残します。

作る側と見る側を対にする

作成した11個のスキルのうち、ほぼ半分はレビュー用です。設計とその設計レビュー、コード化とそのコードレビュー、シナリオ設計とそのシナリオレビューというように、対で用意しました。作った本人に自己チェックさせると、自分の解釈の内側で整合してしまい通ってしまいます。観点表を別に持つレビュー側を独立させると、同じAIでも指摘が出ます。

観点表はスキル本体の外に出す

当初は観点をスキル本体に全部書いていましたが、分量が増えるほど読み落としが増えます。そこで観点表を別ファイルへ切り出し、さらに画面の型（フォーム系・一覧系・詳細系）で分割して、担当画面の型だけを読ませる構成にしました。厚く書くより、必要な場面で必要な項目だけが読まれる形のほうが効きます。

二度出た指摘は規約に書き足す

スキル整備の実体はこれです。たとえば「選択肢が複数ある項目を代表1つで済ませている」という指摘は、その画面を直しても次の画面で再発します。そこで選択肢の網羅方針を、設計・設計レビュー・コード化・コードレビューの4スキルすべてに書き込みました。単に選択肢が表示されることを確認するだけでなく、選択肢ごとの分岐挙動——出し分けされる入力欄、変わるバリデーション、遷移先——を個別のケースにすることまで明文化しています。以後は指示しなくても網羅が効くようになりました。

判断基準が工程で逆になることを書く

以前は「設計書と実装が食い違えば実装を正とする」で運用していました。スキルベースの工程では逆に設計書を正とし、差分はNG候補として残して意図的にFAILさせます。正反対なので、どちらの工程での作業かによって判断を切り替える、と書いておかないと必ず取り違えます。実際にこの方針で流したところ、狙いどおり4件がNG候補としてFAILし、27件がパスしました。

検査は自己テスト付きで常設する

仕様書内の相互参照の整合チェックを、その場でスクリプトを書いて済ませていたところ、表の列を位置で取る実装が行末の空セルを拾い、実際には7件の違反があるのに「違反0件」と報告しました。0件は、違反がないのか検査が壊れているのかを区別できません。

そこで常設のチェッカーへ作り直し、列はヘッダー名で特定する、起動時に意図的な違反を仕込んだサンプルで自己テストして検出できなければエラー終了する、参照を1件も抽出できなければ壊れていると判定する、の3点を入れました。保存時にフックから自動で走ります。一方で「番号は実在するが意味的に別の項目を指す参照」のように、機械では判定できない類型もあります。これはチェッカーに持たせず、観点表の項目として残しました。

スコープと版のルールも書く

意外に効いたのが作業範囲の規定です。「網羅できているか確認」という依頼は調査と結果の提示までで止め、追加や実行は別の指示を待ちます。既存の設計書がある画面は上書きせずV2として別ファイルで作り、版番号の指定があればそれに従います。テストの実行は代表1件ではなく該当specを全件通しで流し、並列だと開発バックエンドが不安定になるためワーカーは1本にします。どれも一度伝えれば分かる内容ですが、書いていないと毎回説明することになります。

反復しても0件にはならない

レビューは差分ではなく毎回全体を照合する、とも規定しました。ある詳細画面では4世代・11巡まで回し、修正必須の件数は減っていきましたが0にはなりませんでした。回ごとに見る角度を変えると、新しい型の漏れが出てくるためです。特に効いたのは、ゼロベースで作り直すときに前版のレビュー結果を突合することでした。前版で指摘済みの内容を再発させていた例が、実際に4件ありました。

ただし終盤は、重箱の隅をつつくような修正や、修正してもしなくても大差ない指摘の繰り返しになることもあるため、どこかのタイミングで反復を切り上げる必要があります。