はじめに
こんにちは。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 を実行すると、次の流れで進みます。
- 最初に、プロジェクトの性格など、全体の方針に関わることを聞く
- プロジェクトのソース、設定ファイル、CI、git の履歴などを調べる
- 調べても分からなかったことだけを質問する
- 回答をもとに、何を作るかを提案し、承認をもらう
- 承認されたものを生成する(CLAUDE.md、
.claude/rules/のルール、Skill、.claude/settings.json、.mcp.json、参考ドキュメントなど) - フォーマッタや CI など、足りない環境の整備を提案する
- 生成したものが動くかを確かめ、やったことを状態ファイルに記録する
質問は 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 に任せられる