mcpField
A
audience-check

audience-check

github.com/zernieドキュメント15387 回インストール2 日前に更新
リポジトリ

audience-check について

READMEなどの入口文書を6種類の読者の視点から評価する、内部向けのドキュメントレビュースキルです。具体的なつまずきと修正案を報告し、文書自体は書き換えません。

主な機能

  1. 016種類の読者による初見レビュー
  2. 02リンク先ドキュメントの確認
  3. 03混乱を招く箇所の特定
  4. 04具体的な修正案の提示
  5. 05報告のみで文書は改稿しない

活用シーン

  1. 01公開前のREADMEレビュー
  2. 02読者層ごとのドキュメント確認
  3. 03初学者向け導線の不足の発見

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zernie/vigiles --skill audience-check

インストール後、Claude Code で/audience-checkを入力して読み込まれたか確認します。

詳細

README を、またはユーザーが指定したトップレベルのドキュメントを、著者としてではなく、複数の異なる読者になりきって読み直してください。著者はすべての行の意味を知っていますが、初めて読む人はそうではありません。特定の読者層が混乱する、必要な情報を得られない、あるいは途中で読むのをやめてしまう箇所を明らかにし、具体的な修正案を提示してください。

これは内部向けの開発スキルです（利用者には提供されません）。readme-brevity と docs-quality のルールを補完します。これらのルールは長さや仕上がりを対象とし、このスキルでは、対象読者に内容がきちんと伝わるかを確認します。

実行方法

  1. 対象ドキュメントを最後まで読む（デフォルト：README.md。ユーザーがパスを指定した場合はそれに従います）。リンク先のドキュメントにも目を通し、「README では詳しく説明すると謳っているのに、リンク先のドキュメントにはその説明がない」といった点を確認できるようにします。
  2. 以下の各ペルソナになりきって、先入観なしに読みます。その読者の目標、語彙、忍耐力を踏まえ、その読者自身が抱く疑問を問いかけます。
  3. 末尾の形式でレポートを作成します。具体的に、該当する行を引用し、明確な修正案を示してください。「もっと分かりやすくできる」といった曖昧な指摘は役に立ちません。

ペルソナ

ユーザーが対象を絞り込まない限り、以下すべてを対象にします。

1. Claude Code ユーザー（主要な読者層）

すでに Claude Code を使っており、作業の合間にノート PC でざっと読みます。最初の画面で魅力が伝わり、数秒でコピー＆ペーストしてインストールできることを望みます。

  • 最初の画面で、vigiles が何をするものか、なぜ関心を持つべきかが伝わりますか？
  • インストール方法（npx vigiles init、エージェントプロンプト）は最初の画面にあり、すぐに実行できることが明確ですか？
  • 必要以上の説明を加えず、フック、スキル、CLAUDE.md、サブエージェントなど、読者に馴染みのある言葉で説明していますか？
2. Codex ユーザー（2 番目のハーネスの読者層）

Claude Code ではなく、OpenAI Codex / AGENTS.md を使用しています。これが「Claude 専用のもの」ではないかと疑っています。

  • Codex のサポートは早い段階で目に入りますか。それとも後ろのほうや脚注に埋もれていて、Claude Code 専用だと思われてしまいますか？
  • 例が CLAUDE.md や claude CLI など Claude Code 専用のもので、Codex ユーザーが二級ユーザーだと感じる内容になっていませんか？
  • vigiles/codex があることや、現在動作する機能と、今後対応予定として文書化されている機能の違いが分かりますか？
3. シニア／スタッフエンジニア（懐疑的な読者）

約 20 秒で実質的な内容や差別化要因を見極めようとし、マーケティング的な誇張を嫌います。promptfoo、ESLint、ast-grep など、知っているツールと比較するでしょう。

  • 差別化要因は具体的で信頼できますか。それとも曖昧な説明にとどまっていますか？重要な主張のすべてに、裏付けとなるリンクがありますか？
  • 「決定論的で、API キー不要／自分の sub で実行」というコスト面の利点は、スローガンではなく、実際のアーキテクチャ上の事実として伝わりますか？
  • 信頼を損ねるような誇大な主張はありませんか。あれば指摘してください。
4. ジュニアエンジニア（新規参入者）

エージェント型ツールには不慣れで、専門用語よりも明快な説明を必要とします。定義されていない用語が出てくると読むのをやめてしまいます。

  • ハーネス、eval、trigger-rate、サブエージェント、方言など、定義される前に使われている用語はどれですか？
  • 何から始めればよいかが明確ですか。それとも、まだ持っていない知識を前提にしていますか？
5. エンジニアリングマネージャー／意思決定者（導入と ROI）

コマンドを実行することはなく、チームに導入すべきかどうかを判断します。コスト、リスク、導入に必要な労力を重視します。

  • コストの説明（無料の決定論的なティア、従量課金制の競合製品と比較した、既存の Claude sub での eval）が、実際にコマンドを実行しない読者にも分かりますか？
  • 段階的でリスクの低い導入方法（最初は寛容な設定にして、後から厳しくする）として説明されていますか？
  • 「なぜ今なのか／なぜ自社製品なのか」は、README だけで答えられますか？
6. QA／テストエンジニア（Test の柱）

テストインフラを担当しており、特にテストに関する説明を評価します。

  • Test の柱は、runHook、runHarnessTest、measureTriggerRate、有意性判定／リグレッションのゲートなどを通じて、この読者に訴求していますか？それとも、リンティングの説明ばかりですか？
  • 決定論的なテストと実際のモデルを使うテストの違いは明確ですか（CI で無料で実行できるものと、モデルが必要なものの違い）？
  • promptfoo／DeepEval と並べて使うに足る信頼性があると思えますか。また、比較は公正ですか？

出力形式

# README audience check — <file>

## <Persona> — verdict: ✅ lands / ⚠ rough / ✗ bounces
- **Reaction (cold read):** one or two sentences in this reader's voice.
- **Friction:** the specific line(s)/section(s) that confuse or under-serve them.
- **Fix:** the concrete change (move X above the fold, define Y on first use,
  link proof for claim Z, add a Codex example here).

… one block per persona …

## Cross-cutting patterns
The 2–4 issues that hurt MULTIPLE personas (these are the highest-leverage fixes).

## Ranked fixes
A short, ordered list — highest reader-impact first — each a one-line action.

レポートは、ざっと目を通せて、実行可能な内容にしてください。すべての指摘に、該当する行と修正案を記載してください。 ユーザーから依頼されない限り、README 自体を書き換えてはいけません。このスキルが行うのはレポートの作成です。修正の適用は、別途明示的な手順として行います。

コメント

Markdown 対応