3
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

AI に作らせた Skill を「期待値」で評価する

3
Posted at

はじめに

こんにちは。KDDIテクノロジーのRioriverです。

私たちのチームは、AI を使った開発の進め方を調べて試し、そこで作ったハーネスや Skill を社内の開発チームへ広げる活動をしています。自分たちで使うぶんには、使いながら直していけば済みます。しかし、ほかのチームに使ってもらうときは、「ちゃんと動くの?」「使い物になるの?」と聞かれたときに根拠を示せるようにしておきたいところです。

この記事では、チームで作った Claude Code の Skill を社内に展開するにあたって、その品質をどう示すかを考えた話を書きます。たどり着いたのは、AI と一緒に作ったものを人がすべて読んで確かめるのではなく、人が判断できる「期待値」に置き換えて確かめる、というやり方です。

想定している読者は、Skill やプロンプトを AI と一緒に作っていて、その品質を人に説明する必要がある人です。

この記事のサマリー:

  • AI と一緒に作った Skill を、人がすべて読んで確かめるのは難しい。そこで「この質問にこう答えたら、このファイルにこう書かれる」という対応を一覧にした。この記事ではこれを期待値と呼ぶ。一覧なら、人が読んで合っているかを判断できる
  • 一覧を書いてみると、選んでも出力が変わらない選択肢や、定義のない言葉が Skill に混ざっているのが見つかった
  • 一覧ができれば、そのとおりに動くかの照合は AI に任せられた

2026年11月時点の内容です。

setup-project という Skill を作った

Claude Code をプロジェクトに入れるとき、最初に CLAUDE.md やルール、Skill を用意する必要があります。ただ、何をどこまで書けばよいかはプロジェクトによって違い、慣れていない人には手が止まりやすいところです。

そこでチームで、この最初の設定を手伝う setup-project という Skill を作りました。/setup-project を実行すると、次の流れで進みます。

  1. 最初に、プロジェクトの性格など、全体の方針に関わることを聞く
  2. プロジェクトのソース、設定ファイル、CI、git の履歴などを調べる
  3. 調べても分からなかったことだけを質問する
  4. 回答をもとに、何を作るかを提案し、承認をもらう
  5. 承認されたものを生成する(CLAUDE.md、.claude/rules/ のルール、Skill、.claude/settings.json、.mcp.json、参考ドキュメントなど)
  6. フォーマッタや CI など、足りない環境の整備を提案する
  7. 生成したものが動くかを確かめ、やったことを状態ファイルに記録する

質問は Claude Code の選択式の質問(AskUserQuestion)で出します。選択肢ごとに「選ぶとどうなるか」の説明を付けるようにしています。たとえば、プロジェクトの性格を聞く質問は次のようなものです。

☐ プロジェクトの性格

このプロジェクトの性格に近いものはどれですか?

❯ 1. 商用(運用中)
     本番ユーザーがいて、リグレッションが実害になる
  2. 商用予定(開発中)
     品質は必要だが、まだ壊してよい
  3. 社内ツール・長期運用
     障害の実害は小さいが、長く保守する
  4. PoC・実験
     使い捨て前提
  5. Type something.

ソースを読めば分かることは聞きません。たとえば古いバージョンのライブラリを使い続けているのが見つかった場合は、その理由がコードから読めないので、「変更禁止(意図的に固定)」「将来変更予定(提案歓迎)」「不明」のどれかを聞きます。回答によって、AI がそのライブラリの更新を提案してよいかが変わります。

やったこと・見送ったことは状態ファイルに記録されます。2回目以降に実行すると、前回から変わったところだけを聞き直します。

Skill の品質を確かめにくい理由

setup-project は AI と一緒に作りました。SKILL.md と参照ファイルを合わせるとかなりの分量になり、全部を読んで「これで正しく動く」と言い切るのは現実的ではありません。

しかも、出力は実行するたびに変わります。正解の出力が1つに決まらないので、ベンチマークのように点数を出すこともできません。

AI に作らせるほど、作ったものの良し悪しを人が判断できなくなっていきます。そこで、Skill そのものを評価するのはやめて、人が読んで判断できる形に置き換えることにしました。それが期待値です。

期待値の形

期待値は「この質問にこう答えたら、このファイルのこの場所に、この内容が書かれる(書かれない、質問が出ない)」という対応で書きました。たとえば次のような行です。

質問 回答 期待される出力
プロジェクトの性格 商用(運用中) CLAUDE.md の「必ず守る制約」に、テスト必須と後方互換への注意が入る
プロジェクトの性格 PoC・実験 生成物が CLAUDE.md、メンテナンスガイド、状態ファイルの3つだけになる。Skill やフックについての質問が出ない
秘匿情報や、触ってはいけない場所 .env と infra/prod/ は変更禁止 パス単位の編集禁止ルールが .claude/rules/ に作られ、.claude/settings.json の permissions.deny でも遮断される
ブランチ名・PR・コミットの規約 厳密な規約はない git-rules.md が作られない
予定している技術スタック(コードがまだない場合) 未定 CLAUDE.md に「未確定。技術選定のときは必ずユーザーに確認する」と書かれる

生成される文章の一言一句は AI が書くので、毎回変わります。そこは判定しません。見るのは「決められた内容が、決められた場所に、決められた強さで書かれているか」です。

この一覧なら、Skill の中身を知らない人でも1行ずつ読んで「それで合っている」「いや、そこは違う」と言えます。一覧の下書きは AI に任せ、人は一覧を読んで判断することに時間を使いました。

選んでも出力が変わらない選択肢が見つかった

期待値を作る前に、Skill の質問と選択肢を上司とレビューしました。そこで引っかかったのが、先ほどのプロジェクトの性格を聞く質問です。

「商用(運用中)と商用予定って、選ぶと何が違うの?」という指摘です。言われてみると、その場では説明できませんでした。

そこで、全部の質問について「選択肢ごとに出力がどう変わるか」を AI に洗い出させ、それを読んで確認しました。

その結果、「商用(運用中)」と「商用予定」を区別する決まりは、SKILL.md にも参照ファイルにも書かれていませんでした。どちらを選んでも、Skill の中では同じ扱いです。違いが出るとしたら、実行する AI がその場でどう解釈するか次第で、差が出る保証はありません。4択に見えて、実際は「商用系 / 社内 / PoC」の3通りにしか分かれていませんでした。

「この回答は CLAUDE.md のトーン全体に反映する」という記述もありました。しかし「トーン」が具体的に何を指すのかは、どのファイルにも定義されていませんでした。それらしい言葉が書いてあるだけで、期待値として確かめようがありません。

AI が作った Skill は、選択肢がきれいに並んでいて、いかにも設計されているように見えます。それでも、実際には何も分岐していない選択肢や、中身の定義されていない言葉が混ざっていました。SKILL.md を読んでいるだけでは気づけず、「選ぶと何が変わるのか」を期待値として1行ずつ書こうとして初めて見えました。

そこからは、同じ観点で全項目を点検しました。選んでも差が出ない選択肢や、反映先が曖昧で期待値を書けない箇所を AI に洗い出させ、レビューしながら仕様を直しています。

プロジェクトの性格の質問は、選択肢ごとに何が変わるかを対応表として仕様に書きました。一部を抜き出すと次のとおりです。

商用(運用中) 商用予定(開発中) 社内ツール・長期運用 PoC・実験
生成物の範囲 フル フル フル CLAUDE.md、メンテナンスガイド、状態ファイルだけ
CLAUDE.md の「必ず守る制約」 テスト必須。後方互換・データ移行・本番設定の変更への注意 テスト必須。後方互換の縛りは書かない 主要機能へのテストを推奨。可読性・保守性を重視 「速度優先。過剰な抽象化・防御的コードは書かない」
自動整形フックの提案 追加を推奨 中立 中立 聞かない

こうして4つの選択肢それぞれに、選ぶ意味ができました。表の1マスがそのまま期待値の1行になります。

照合は AI に任せる

期待値の一覧ができれば、あとはその通りに動くかを確かめるだけです。

照合は AI に任せました。期待値が「このファイルのこの場所に、これが書かれる」という形になっていれば、人が1件ずつ見なくても、AI や機械で照合できます。実際には、期待値の一覧を渡したうえで、次のように頼みました。

テストケース・試験書のようなものを作り、それが行われているかをテスト、
結果がレポートとしてまとめられている状態にしたいです。
サンプルとするプロジェクト、テストケース、それぞれの結果の出力、
そしてまとめのレポートまで出してください。

AI は期待値の一覧をもとに試験書を作り、性格の違うサンプルプロジェクトを用意して Skill を実行し、生成物が期待値どおりかを1行ずつ判定したレポートを返してきます。人はそのレポートを読んで、期待値と合わなかったところを確認します。

人が全部を見なくても、評価の基準を人が持っていて、そのとおりに動くかを確かめられれば、AI が作ったものでも信用する根拠になります。

なお、この方法で分かるのは期待値どおりに動くかどうかまでです。生成された設定が実際の開発で役に立つかは、使ってみて確かめる必要があります。

skill-creator の eval との関係

Anthropic が公開している skill-creator(Skill を作るための Skill)にも、Skill を評価する仕組みがあります。テスト用の依頼文を Skill ありと Skill なしの両方で実行し、出力をアサーションで採点して、合格率、所要時間、トークン数を比べるものです。

アサーションは「軸ラベルがある」のように、出力が満たすべき条件を書いたものです。先に基準を決めておき、照合は機械的に回す、という点は今回のやり方と同じ考え方です。AI が作ったものを評価するには、人が基準を持ち、照合は機械に任せる。Anthropic 自身も、Skill 作りの道具にこの仕組みを組み込んでいます。

まとめ

  • AI に作らせた Skill は、人が読んでも良し悪しを判断しにくい。そこで「この回答なら、ここにこう書かれる」という期待値の一覧に置き換えた。一覧の下書きは AI に書かせても、人が読んで判断できる
  • 期待値を書こうとして、選んでも出力が変わらない選択肢や、定義のない言葉が見つかった。AI が作ったものには、それらしく見えて中身のない部分が混ざる
  • 基準を人が持っていれば、作るのも照合するのも AI に任せられる
3
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
3
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?