Back to Details

audience-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Re-read the README — or whichever front-door doc the user names — as several different readers in turn, not as the author. The author knows what every line means; a first-time reader does not. The job is to surface where a specific audience gets confused, under-served, or bounces, and to propose concrete fixes.
This is an INTERNAL dev skill (not shipped to consumers). It complements the 
readme-brevity
and 
docs-quality
rules: those govern length/polish; this checks whether the content actually lands for who it's for.
以多个不同读者的身份重新阅读README（或用户指定的任何入门文档），而非以作者的视角。作者清楚每一行的含义，但首次阅读的用户并不了解。这项工作的目的是找出特定受众感到困惑、需求未被满足或会放弃阅读的地方，并提出具体的修复方案。
这是一项内部开发技能（不面向消费者发布）。它是
readme-brevity
和
docs-quality
规则的补充：后者管控文档的长度/打磨程度；而这项技能则检查内容是否真正契合目标受众的需求。

How to run it

如何运行

  1. Read the target doc in full (default: 
    README.md
    ; honor a path the user gives). Also skim the docs it links to, so "the README promises depth the doc doesn't deliver" is checkable.
  2. For each persona below, do a cold read — adopt that reader's goals, vocabulary, and patience. Ask their questions, not yours.
  3. Produce the report in the format at the end. Be specific: quote the exact line, name the exact fix. Vague notes ("could be clearer") are useless.
  1. 完整阅读目标文档（默认：
    README.md
    ；需遵循用户指定的路径）。同时浏览文档中链接的其他内容，以便检查“README承诺了文档未提供的深度内容”这类问题。
  2. 针对以下每个角色进行冷启动阅读——代入该读者的目标、词汇量和耐心程度。站在他们的角度提问，而非你自己的。
  3. 按照末尾的格式生成报告。内容要具体：引用确切的行，明确具体的修复方案。模糊的注释（如“可以更清晰”）毫无用处。

The personas

受众角色

Run all of these unless the user scopes to a subset.
除非用户限定了子集，否则需覆盖所有角色。

1. Claude Code user (the primary audience)

1. Claude Code 用户（核心受众）

Already lives in Claude Code; skimming on a laptop between tasks. Wants the WOW in the first screen and a copy-paste install in seconds.
  • Does the first screen land what vigiles does and why they'd care?
  • Is the install path (
    npx vigiles init
    , the agent prompt) above the fold and obviously runnable?
  • Does it speak their language (hooks, skills, CLAUDE.md, subagents) without over-explaining?
日常使用Claude Code；在任务间隙用笔记本电脑快速浏览。希望在第一屏就能看到亮点，并能在几秒内复制粘贴完成安装。
  • 第一屏是否清晰传达了vigiles的功能和他们为何需要它？
  • 安装步骤（
    npx vigiles init
    、agent提示）是否在首屏可见，且明显可运行？
  • 是否使用他们熟悉的语言（hooks、skills、CLAUDE.md、subagents），且不过度解释？

2. Codex user (the second-harness audience)

2. Codex 用户（次要工具受众）

Uses OpenAI Codex / 
AGENTS.md
, not Claude Code. Skeptical that this is "a Claude thing."
  • Is Codex support visible early, or buried/footnoted so they assume it's CC-only?
  • Are the examples CC-only (CLAUDE.md, 
    claude
    CLI) in a way that makes a Codex user feel like a second-class citizen?
  • Would they know 
    vigiles/codex
    exists and what works vs. what's a documented follow-on?
使用OpenAI Codex / 
AGENTS.md
，而非Claude Code。对这是“Claude专属工具”持怀疑态度。
  • Codex支持是否在早期就可见，还是被隐藏在脚注中，导致他们误以为仅支持Claude Code？
  • 示例是否仅针对Claude Code（CLAUDE.md、
    claude
    CLI），让Codex用户感觉自己是二等公民？
  • 他们是否知道
    vigiles/codex
    存在，以及哪些功能可用、哪些是已记录的后续开发内容？

3. Senior / staff engineer (the skeptic)

3. 资深/高级工程师（持怀疑态度者）

Scans for substance and differentiation in ~20 seconds; allergic to marketing fluff. Will mentally compare to tools they know (promptfoo, ESLint, ast-grep).
  • Is the differentiation concrete and credible, or hand-wavy? Does every load-bearing claim link to proof?
  • Does the "deterministic, no API key / runs on your sub" cost angle come through as a real architectural fact, not a slogan?
  • Anything that reads as overclaiming will cost trust — flag it.
在约20秒内快速浏览，寻找实质内容和差异化优势；反感营销话术。会在心里将其与他们熟悉的工具（promptfoo、ESLint、ast-grep）进行比较。
  • 差异化优势是否具体可信，还是含糊其辞？每个关键主张是否都链接到证据？
  • “确定性、无需API密钥/在你的子系统上运行”的成本优势是否作为真实的架构事实呈现，而非口号？
  • 任何夸大其词的内容都会损害信任——请标记出来。

4. Junior engineer (the newcomer)

4. 初级工程师（新手）

New to agentic tooling; needs clarity, not jargon. Bounces on undefined terms.
  • Which terms are used before they're defined (harness, eval, trigger-rate, subagent, dialect)?
  • Is there a clear "what do I do first" path, or does it assume context they lack?
刚接触agent类工具；需要清晰的说明，而非行话。遇到未定义的术语就会放弃阅读。
  • 哪些术语在定义前就被使用了（harness、eval、trigger-rate、subagent、dialect）？
  • 是否有明确的“第一步该做什么”的指引，还是假设他们具备相关背景知识？

5. Engineering manager / decision-maker (adoption + ROI)

5. 工程经理/决策者（采用与投资回报率）

Won't run a command; deciding whether the team should adopt. Cares about cost, risk, and effort.
  • Is the cost story (free deterministic tiers, evals on the existing Claude sub vs. metered per-token competitors) legible to a non-runner?
  • Is adoption framed as incremental/low-risk (start permissive, tighten later)?
  • What's the "why now / why us" — is it answerable from the README alone?
不会运行命令；决定团队是否应该采用该工具。关注成本、风险和投入。
  • 成本说明（免费确定性层级、基于现有Claude子系统的评估 vs. 按令牌计费的竞品）对非技术使用者是否易懂？
  • 采用是否被描述为渐进式/低风险（从宽松模式开始，之后再收紧）？
  • “为何现在采用/为何选择我们”的问题能否仅通过README找到答案？

6. QA / test engineer (the Test pillar)

6. QA/测试工程师（测试支柱）

Owns test infra; evaluates the testing story specifically.
  • Does the Test pillar speak to them — 
    runHook
    , 
    runHarnessTest
    , 
    measureTriggerRate
    , significance/regression gating — or is it all about linting?
  • Is the deterministic-vs-real-model split clear (what runs in CI free vs. what needs a model)?
  • Would they trust it next to promptfoo/DeepEval, and is the comparison honest?
负责测试基础设施；专门评估测试相关内容。
  • 测试支柱是否针对他们的需求——
    runHook
    、
    runHarnessTest
    、
    measureTriggerRate
    、显著性/回归门控——还是全是关于代码检查的内容？
  • 确定性模型与真实模型的区分是否清晰（哪些可在CI中免费运行，哪些需要模型支持）？
  • 他们是否会信任它与promptfoo/DeepEval配合使用，且对比是否客观？

Output format

输出格式

undefined
undefined

README audience check — <file>

README受众检查 — <文件名>

<Persona> — verdict: ✅ lands / ⚠ rough / ✗ bounces

<角色> — verdict: ✅ 适配 / ⚠ 待优化 / ✗ 受众放弃

  • 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 …
  • 反馈（冷启动阅读）: 用该读者的语气写1-2句话。
  • 痛点: 让他们感到困惑或需求未被满足的具体行/章节。
  • 修复方案: 具体的修改措施（将X移至首屏，首次使用Y时给出定义，为主张Z添加证据链接，在此处添加Codex示例）。
… 每个角色对应一个区块 …

Cross-cutting patterns

跨角色共性问题

The 2–4 issues that hurt MULTIPLE personas (these are the highest-leverage fixes).
影响多个角色的2-4个问题（这些是优先级最高的修复点）。

Ranked fixes

优先级修复列表

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

Keep the report scannable and ACTIONABLE: every finding names a line and a fix.
Do not rewrite the README in place unless the user asks — this skill REPORTS;
applying the fixes is a separate, explicit step.
简短的有序列表——按对读者的影响程度从高到低排列，每个条目为一行操作说明。

报告需易于浏览且**可执行**：每个发现都要指明具体行和修复方案。除非用户要求，否则不要直接重写README——这项技能仅负责**报告**；应用修复方案是单独的明确步骤。