AIが読んで従う文書のusability test手順

subagentにタスクを依頼して、検証したい文書の記述を頼りにワークフローを完遂できるか検証する手順。ゴールだけを与えて作業を観察し、終わってから判断の根拠を聞き出す、ユーザーテストの模倣である。 実装したAIエージェント自身がskillを使っても、配管の疎通確認にしかならない。実装の全コンテキストを持っているため、手順書の不備に気づかず乗り越えてしまう。

被験体にできる文書

Agent Skillの他に、CLAUDE.md等のルール文書と、ルール文書から参照されるリポジトリ内の文書も被験体にできる。 手順書型の文書は、そのまま被験体にする。 ガイドライン型の文書は、それ単体では完遂の定義が無い。ルール文書はこれに当たる。その文書が作用する作業をタスクとして与え、文書が読み込まれたか、その記述が判断の根拠として証言されるかを、作業後のインタビューとtranscriptの監査で見る。

いつ実行するか

変更の度に自動では実行しない。実行する価値があると判断したら、ユーザーに提案して合意を得てから始める。 価値があるのは、被験体にする文書のワークフロー構成や判断基準に影響する変更。手順の追加・組み替え、新コマンドの組み込み、ガイドラインの判断基準の変更等がこれに当たる。文言の手直しや、挙動を変えないリファクタでは提案しない。

subagentへの指示のやり方

modelはSonnetを指定する

賢いmodelほど手順書の不備を自力で補ってしまい、手順書の検証にならないので、modelは原則Sonnetを使う。被験体の文書がmodelのtierに下限を定めていてSonnetがそれを満たさない時は、その下限のmodelを使う。実装の会話を引き継がない新しいsubagentを起動する。

変更した方の文書を使わせる

ユーザーがマシンにインストールしているplugin版のskillではなく、検証対象のworktreeにあるskillディレクトリを使わせる。ルール文書が被験体の時は、変更後のルール文書をエージェント実行環境から受け取っているsessionから、その文書を引き継ぐsubagentを起動する。パスを指示して読ませる必要は無い。skillが同じリポジトリのCLI等と一緒に変更されているなら、そのCLIもインストール済みの物ではなくworktreeの物に読み替える指示をプロンプトに含める。検証したい変更がガイドライン型のskillにある時、タスクに使う別のskillがそのガイドラインを名前で読み込むなら、その参照先もworktreeの物に読み替えさせる。

情報源を制限する

情報源を制限するかは、その回で確かめたい事で決める。配布先の別のリポジトリでも文書だけで動くかを確かめる回は、情報源を以下の範囲に制限する。そのリポジトリの中で文書が働くかを確かめる回は、リポジトリ内のリソースへのアクセスを制限しない。過去の会話memoryは、どちらの回も禁止する。

許可するのは、タスクで与えた物、被験体の文書とその文書が参照を指示する先、コマンドに内蔵されたヘルプ、コマンドやツールの実行結果だけ。Agent Skillが被験体なら、skillディレクトリ配下のファイルを被験体の文書に含める。タスクで与えた物とは、タスク文、作業対象のfixture、質問へのユーザー回答を指す。コマンドに内蔵されたヘルプとは、CLIの--helpやツールのスキーマのように、コマンドやツール自身が持つ引数や戻り値の説明を指す。webサイトのドキュメントは含めない。webを見に行かせる作りのskillを助長しないため。 禁止するのは、許可した範囲の外から、検証対象の実装やリポジトリのドキュメント、履歴、過去の会話memoryを調べる事。実装コードやgit履歴を読めば、手順書が無くても正解できてしまう。以下を明示的に禁止する。

• リポジトリのソースコード、docs/、README、.dev/、CLAUDE.md
• 過去の会話memory
• gitコマンドの実行。ただし、subagentに与える作業自体がgitを必要とする場合はテスト実施者が禁止を外す

禁止で塞げるのは自分で読みに行く経路だけ。エージェント実行環境が最初から渡す情報は作業後のインタビューで拾う。

タスク文で対象機能をほのめかさない

検証したい機能のコマンド名やヒントをタスク文に書かない。手順書だけでそこへ誘導できるかが検証対象。 例: wikiのページを改名すると、他のページからそのページへ張られたリンクが切れる。改名時にリンク元を書き換える機能を検証するなら、「ページのタイトルを◯◯に変更してください」とだけ依頼し、「他ページからのリンクが切れないように」とは書かない。

推測で補わせない

手順書とコマンドに内蔵されたヘルプを読んでも分からない事は、推測で補わずに「分からなかった」と報告するよう指示する。自力補完で手順書の穴が隠れるのを防ぐ。

ユーザーへの質問は中継する

subagentにはユーザーへ質問する手段が無い事が多い。手順書がユーザーへの質問を求める箇所に来たら、既定値や推測で進まず、質問をそのまま報告して止まるよう指示する。止まったら質問をユーザーに中継し、回答をsubagentに渡して再開させる。自分が代わりに答えると、その判断の根拠が質問へのユーザー回答ではなく自分の仮定になり、手順書だけで完遂できた証拠にならない。

報告形式を指定する

以下を時系列で報告させる。3つ目の申告が手順書の曖昧さの検出器になる。

1. 読んだ手順書ファイルと、従った手順
2. 実行したコマンドやツールの呼び出しの列と、それぞれの結果の要点
3. 判断に迷った箇所、手順書に書かれていなくて困った箇所

テスト環境

実データを変える作業なら、ローカルの開発環境か、テスト用に用意した環境を使う。どちらの環境のどの対象を使うかは、テスト実行前にユーザーに質問して決める。

シナリオ設計

• シナリオは人間が指示しそうな抽象的なタスクとして設計し、そこから正しい手順に推論で辿り着けるかを検証する。引数の受理やエラー表示のように、コードを読めば検証できる事は主要な検証対象ではないが、発見した問題は報告する
• 正常系だけでなく、手順書に書いた注意点が実際に機能するかを、その罠を踏む状況を意図的に作って検証する。例: 改名先と同名の対象が既にある時に名前が自動で変えられる事への注意書きは、同名の既存対象を用意した上で改名を依頼して検証する
• シナリオ案は複数作り、実行前にユーザーに提示して選んでもらう。観点の不足や偏りを実行前に人間が補えるようにする
• 対象・リンク元・衝突相手のようなfixtureは、テスト対象の手順の外側で事前に作っておく。タスク文と同様に対象機能をほのめかさず、テストをしている事も悟られないように文言に気をつける

作業後にインタビューする

subagentのcontextには、エージェント実行環境が最初から渡す情報がある。project instructions、memoryのindex、git status等がこれに当たる。読む操作を伴わないので禁止できず、transcriptにも残らない。作業が終わったらsessionを閉じる前にインタビューし、判断の根拠を聞き出す。成功した場合も失敗した場合も行う。

聞き出す観点:

• エージェント実行環境から渡された被験体の文書で、変更箇所に当たる記述は何だったか。回答を変更後の本文と照合する
• 各判断の根拠がどの情報源か。タスク文・手順書の記述・コマンドに内蔵されたヘルプ・コマンドやツールの実行結果・質問へのユーザー回答・エージェント実行環境の提供情報・事前学習知識・仮定、に分類させる
• 不明点を仮定で補った事は何か。「推測で補わせない」指示はsubagentが推測と自覚できた箇所にしか効かないので、作業後のインタビューでも拾う
• 必要だったが見えなかった・使えなかった情報は何か。手順書に足すべき記述の候補になる
• 手順書・コマンドに内蔵されたヘルプ・実行結果が食い違った箇所はなかったか。あればどれを採用したか。乗り越えられていても、食い違い自体が手順書の修正候補になる

回答は後付けの説明になりうるので、内省の忠実な記録ではなく原因切り分けの証言として扱い、transcript監査と突き合わせる。 成否に影響した判断の中に、許可した情報源に含まれないエージェント実行環境の提供情報、事前学習知識、仮定のどれかなしには到達できないものが出てきたら、その回は手順書だけで完遂できた証拠にならない。禁止を外した回も、branch名やcommit logから手順書の不足を補っていたら、手順書だけで完遂できた証拠にならない。

検出した穴をすべて手順書で埋めるとは限らない。安定して正しく補われる穴まで埋めると、過剰な詳細化でskillの応用力を損なう。補われ方が安定して正しいかは推測を禁じたこのテストからは観測できないので、埋めるかどうかは穴ごとにユーザーと判断する。判断にはkuden:common-rules-for-agent-instructions skillのレビュー指摘の採否の問いと、被験体の文書の種類に固有の心得を使う。Agent Skillならkuden:agent-skill skill、ルール文書ならkuden:persistent-instructions skillがこれに当たる。subagentが止まった箇所について、記述を足さなければmodelが行き詰まるのか、賢いmodelならその場で判断できるのかを切り分ける。埋める場合の修正先は、被験体の文書のリポジトリにCLIとskillの責任境界のような規則があればそれに従って切り分ける。

結果の検証

subagentの自己報告を鵜呑みにせず、2つの独立確認を行う。

transcriptログのtool呼び出し列を監査する

transcriptを丸ごと読むとcontextが溢れるので、まずtool呼び出しの列を抽出し、tool名と主な引数を読む。禁止を外した回のgitコマンドのように判断の根拠を確かめる必要がある呼び出しは、その実行結果も読む。

見る点:

• 禁止した情報源を読んでいないか
• gitコマンドを禁止した回は、実行していないか。禁止しなかった回は、branch名やcommit logから手順書の不足を補っていないか
• コマンドの実行前に内蔵されたヘルプを読んでいるか
• 呼び出し列が自己報告と一致するか

最終状態の実データを確認する

対象を直接読み、意図した変更が反映されているか、巻き込むべきでない物が無傷かを確認する。