dogfood

亲自试用

亲自试用是指由真人操作实际应用，逐一体验面向用户的各项功能，并评估所见内容。交付物是用例目录和渲染后的用户指南——以应用自身的渲染效果为依据，每项功能用一行用例表示，并标注需求 ID 和用例类型。请构建这些产物；聊天消息不是交付物。只包含顺畅路径的指南不算完成。

用例分类（每份指南都使用这些类型）

kind	含义	典型来源
happy	功能按预期实现其用途	需求中的主要用户故事
edge	边界／空值／重复项／最大长度／空白字符	同一 ID 或相邻标准中的边界条件
error	用户可见的失败路径（校验提示、4xx 消息、保留的输入）	需求中的错误标准
nonbehavior	不得发生的情况	范围外内容；否定式 SHALL
persist	重新加载／重新打开／重启客户端后仍然保留	声明“持久保留”的标准或由存储负责的状态
visual	布局、颜色、空状态文案、观感——由真人目测	表现层需求；不写入服务器
journey	将多个原子用例串联起来的多步骤工作流（可选，每份指南 ≤2 个）	跨用户故事的用户路径

此处不要编造混沌、负载、竞态或安全模糊测试套件——这些不属于单人用户试用。只有在 UI 提供相应入口时，才测试权限／角色用例（对于该角色的设置，用 edge 或 error）。

1. 确定每项功能的范围 — 覆盖门槛

阅读功能的 requirements.md、design.md 和 tasks.md。列出所有用户可观察到的功能。还要包含同一用户工作流中的相邻功能，不要只覆盖新功能。

覆盖规则（第 4 节完成前，必须全部满足）：

1. 每个面向用户的需求 ID 至少有 1 个用例。
2. 每个功能区域（指南中的一个章节）至少有 1 个 happy 用例，并且至少有 1 个非顺畅用例，类型为 edge | error | nonbehavior | persist。
3. 对于用户可能尝试的每项范围外内容／刻意不实现的行为，都要有一个 nonbehavior 用例（或在交接说明中明确注明：没有面向用户的尝试方式——已跳过）。
4. 每项声明具有持久性的标准都要有一个 persist 用例（或者用 happy／edge 用例，其 Expect + backend 能证明重新加载／存储后的状态——最好单独列出 persist 行，以免遗漏）。
5. 如果该区域的规格中没有边界、错误、非行为或持久性相关内容，请在该章节下写一行：覆盖例外：规格未提及边界／错误／非行为／持久性——不要编造产品行为。如果三份规格材料中存在边界条件，这项例外就不能作为免检理由；记录例外的目的是如实说明，便于搜索。

当某个 ID 或其相邻标准提到了边界条件时，每个 ID 只有一个顺畅路径用例并不足够。

完成标准：满足上述覆盖规则，或已在指南中逐项写明所有例外。

2. 以真实代码为依据编写每个用例

针对每个用例阅读代码，了解用户实际会看到的内容：准确用词（关键词、命令名称、标签）、键盘快捷键和实际渲染效果——包括从源代码（主题令牌、CSS）中查明的徽标颜色、提示样式和图标，绝不凭猜测。若代码揭示了实际存在的限制（例如分隔符变暗而非移除，或某种状态尚无 UI），用例中要如实说明。

3. 启动实际应用并找到可靠的观察方式

使用 docs/agents/project.md 中的 Run locally (dev) 命令启动应用（如果缺少该命令，请查明并记录——参见 acceptance-ui）。提前说明任何功能受限的区域：需要密钥的功能、尚未构建的子功能。没有 UI 界面的行为也要编写用例——并提供真实的观察方式（例如 devtools 中的 invoke(...) 或只读数据库查看），切勿虚构界面。完成标准：应用正在运行，且每项尚不可见的行为都有观察方法。

4. 编写用例 + 渲染外壳（不要自行编写 CSS）

编写内容的唯一事实来源（SSOT）是用例文件，而不是手工编写的 HTML。

1. 编写 .skills/<slug>-dogfood.cases.yaml（不确定时，读取同级的 references/cases-schema.md 了解架构）。每个用例都必须包含所有必需字段：id、req、kind、title、setup、try、expect、backend （backend 是服务端断言，或字面值 presentational）。

2. 使用已纳入版本控制的外壳渲染面向用户的指南 — 不要加载 design-page，也不要自行设计配色方案或布局，除非用户明确要求定制：

   python3 <skill-root>/scripts/dogfood render .skills/<slug>-dogfood.cases.yaml \
     -o .skills/<slug>-dogfood.html
   

   将 <skill-root> 解析为此技能的安装路径（在此 monorepo 中： skills/acceptance/dogfood）。外壳位于 shell/guide.html — CSS/JS 会适配主题，包含类型标签、人类可操作的 localStorage 勾选项，以及供旧版读取器使用的 data-* 属性。

3. **覆盖率自检：**按章节统计各 kind 的用例数量。如果任何能力领域都没有非 happy 类型的用例，也没有 Coverage exception 行，则在交付前补上缺失的用例。

可选：最多添加两行 journey；它们不能替代原子级覆盖。

绝不要只交付聊天中的检查清单。默认路径绝不要重新生成完整的自定义 HTML 页面 — 正确路径是用例 + render。

完成标准：用例 YAML 和渲染后的 HTML 已保存到明确路径，覆盖率达标，且每个用例都包含所有必需字段。

5. 交接

提供两个路径（用例 YAML + HTML），以及最快的入门方式 — 一次约 30 秒的初次检查，让功能运行起来（通常是第一行 happy 用例）— 然后说明功能降级情况和覆盖率例外。告知用户，HTML 中的复选框勾选只是可选的本地 localStorage 便利功能。如果应由 Agent 运行指南，请提供 drive-dogfood 名称以及用例（或 HTML）路径 — 进度将记录在 CLI 台账中，而不是通过指南上的 Chrome 勾选项记录。

完成标准：制品已保存到磁盘，内容有依据，符合 §1 覆盖率门槛，且每个用例都包含所有必需字段。

自我辩解

想法	实际情况
“在聊天中给出 Markdown 检查清单就够了”	它无法保存勾选状态，无法显示正在核对的真实徽章，还会随着滚动消失。交付内容应为用例 + 渲染后的指南。
“我会用 design-page 为这个功能设计独特布局”	默认使用已纳入版本控制的外壳。只有用户提出要求时才进行定制。
“他们用的是原生桌面应用，不是浏览器，所以不适合用制品”	制品是配套参考资料，可在应用旁边保持打开状态；应用是原生应用，不代表应该把指南直接放进聊天中。
“我会用文字描述徽章”	用户会对照自己实际 SEE 到的内容进行检查。应呈现真实效果，否则 Expect 无法验证。
“每项需求一个 happy 用例就够了”	覆盖率门槛要求包含非 happy 类型用例（或书面例外）。只有 happy 用例只是演示，不是 dogfood。
“边界情况应该放进单元测试，而不是指南”	Dogfood 面向用户。如果用户可能遇到该边界情况，就应列出对应的一行用例。
“更差的情况指的是负载、混沌或模糊测试”	这些属于其他测试框架。Dogfood 中的更差情况包括 edge、error、nonbehavior、persist。

危险信号

• 手写完整的 HTML/CSS 页面，而不是使用用例 YAML + dogfood render
• 任一用例缺少 backend / setup / kind
• 章节只有 happy 用例，且没有可搜索的覆盖率例外
• 告诉 Agent 只能通过 HTML localStorage 勾选项标记进度