audience-check

像多位不同的读者一样重新阅读 README，或用户指定的其他入口文档，而不是以作者的视角阅读。作者知道每一行的意思；初次阅读的人并不知道。你的任务是找出特定受众会在哪里感到困惑、得不到所需信息或放弃阅读，并提出具体的修改建议。

这是一项内部开发技能（不会发布给消费者）。它与 readme-brevity 和 docs-quality 规则互补：前者规定篇幅和润色要求；这项技能检查内容是否真正传达给目标受众。

如何运行

1. 完整阅读目标文档（默认为 README.md；尊重用户指定的路径）。同时快速浏览文档链接到的内容，以便核实“README 承诺了深入内容，但链接的文档并未提供”这类情况。
2. 依次以每位用户角色的视角冷读——采用他们的目标、词汇和耐心程度。提出他们会问的问题，而不是你自己的问题。
3. 按文末格式生成报告。务必具体：引用确切的行，指出确切的修改方式。含糊的意见（例如“可以写得更清楚”）毫无用处。

用户角色

除非用户限定范围，否则请检查以下所有角色。

1. Claude Code 用户（主要受众）

日常使用 Claude Code，常在任务间隙用笔记本电脑快速浏览文档。希望第一屏就展现亮点，并能在几秒内复制粘贴安装。

• 第一屏是否清楚说明 vigiles 的作用，以及用户为什么会在意？
• 安装方式（npx vigiles init、Agent 提示词）是否位于首屏，并且显然可以直接运行？
• 文档是否使用他们熟悉的术语（hooks、skills、CLAUDE.md、subagents），又不过度解释？

2. Codex 用户（第二套 Harness 的受众）

使用 OpenAI Codex / AGENTS.md，而非 Claude Code。他们担心这只是“Claude 专属工具”。

• Codex 支持是否足够醒目，还是被埋在文档深处或脚注里，让人以为它只支持 CC？
• 示例是否只面向 CC（CLAUDE.md、claude CLI），以至于 Codex 用户觉得自己是次等用户？
• 用户能否知道 vigiles/codex 的存在，以及哪些功能可用、哪些只是后续规划？

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

会在约 20 秒内扫读文档，寻找实质内容和差异化优势；反感营销话术。他们会在心里将此工具与熟悉的工具（promptfoo、ESLint、ast-grep）比较。

• 差异化优势是否具体可信，还是含糊其辞？所有关键主张是否都链接到佐证？
• “确定性、无需 API 密钥 / 在你自己的 sub 上运行”这一成本优势，是否体现为真实的架构事实，而非一句口号？
• 是否有任何夸大其词、可能损害信任的内容？请指出。

4. 初级工程师（新手）

刚接触 Agent 工具，需要清晰易懂的说明，无法接受未定义的术语。

• 哪些术语在定义前就已出现（harness、eval、trigger-rate、subagent、dialect）？
• 是否明确说明“我该从哪里开始”，还是默认读者具备他们并不具备的背景知识？

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

不会运行命令，只负责决定团队是否采用。关心成本、风险和投入。

• 非执行者是否能看懂成本说明（免费的确定性层级、在现有 Claude sub 上运行 eval，与按 token 计费的竞品对比）？
• 采用方式是否被描述为渐进式、低风险（先采用宽松设置，以后再逐步收紧）？
• “为什么是现在 / 为什么选我们”能否仅凭 README 得到解答？

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

负责测试基础设施，重点评估测试能力。

• Test 支柱是否针对他们展开，涵盖 runHook、runHarnessTest、measureTriggerRate、显著性分析 / 回归门禁，还是内容全都围绕 lint？
• 是否清楚说明确定性测试与真实模型测试的区别（哪些测试可在 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——这项技能只负责生成报告；实际应用修改是单独且明确的步骤。