app-verification

应用验证

在产品自己的代码仓库中构建一套所有 Agent 都能使用的工具链，用来运行该产品并验证相关声明：包括 verify CLI、doctor 命令、每个 worktree 一个隔离实例、从用户视角编写的功能地图、种子数据和测试账号，以及优先复现问题的交接流程。这套工具链位于目标代码仓库中，而非此技能中；此技能负责搭建并维护它，让每个打开该仓库的 Agent 都以相同方式运行应用，而不是每次都编写一次性脚本。

• **是：**搭建项目本地验证工具链（Create 模式），以及运行或扩展现有工具链（Maintain 模式）：verify CLI 的契约、功能地图格式、验证记录、每个 worktree 的隔离与种子数据、逐步升级到计算机使用的最省力方法，以及问题交接格式。
• **不是：**针对固定 UI 规则目录进行临时浏览器探测（ui-verification；此技能的 verify 可以将这些探测作为多项检查之一调用）、整个代码仓库的模块边界与强制执行工具（codebase-architecture；此技能的 CI 配置遵循其强制执行顺序）、精简现有测试套件（test-audit），或针对单项功能制定计划（planning）。

调用方式

Create 模式会修改目标代码仓库，Maintain 模式则会驱动该仓库的真实运行实例；只有明确点名时才会运行这两种模式，而不会响应宽泛的“检查应用”提示——这种情况可能更适合较轻量的技能。如果宿主支持，请在已安装副本的 frontmatter 中添加 disable-model-invocation: true。这是宿主扩展字段，不是可移植字段，因此此源文件不包含该字段（agent-skills-creator 的 references/format-specification.md 说明了原因）。具有等效显式调用设置的宿主也应采用相同方式设置。

目录

• 模式
• 工具链契约
• Create 模式
• Maintain 模式
• 参考资料
• 注意事项
• 相关技能
• 致谢

模式

根据现有内容选择模式，并说明选择了哪一种。

模式	适用情况	输出
Create	代码仓库中尚无 verify CLI、doctor 命令或功能地图	一套可用的工具链，已通过真实功能完成一次端到端验证，并交接给 Maintain 模式
Maintain	工具链已存在，需要在本次会话中运行、添加功能或调查问题报告	clean / changed / blocked 结果，或一份优先复现问题的交接记录

复制以下内容以跟踪进度：

App verification progress:
- [ ] Mode chosen and stated (Create / Maintain)
- [ ] doctor run first, read-only, before any drive
- [ ] Isolation confirmed: own port, own database, own browser profile; refused (not fell back to) the main instance
- [ ] Every path in scope checked or named as a skip with a reason
- [ ] Native/desktop paths, if any, verified with computer use as the last-resort method, not the first
- [ ] Outcome stated: clean / changed / blocked, or a reproduce-first handoff

Harness 契约

两种模式都围绕同一组三条命令构建，并将它们放在目标仓库的技能文件夹中（例如 .claude/skills/verify-<app>/，或该宿主对应的项目技能目录），这样每次会话都能通过同一路径找到这些命令。

命令	作用	必须满足
doctor	执行一次只读检查，回答“这个实例是否值得驱动”：工具链、隔离、端口、数据库、迁移、种子数据、构建新鲜度，以及 Harness 所需的驱动程序（浏览器、计算机操作）	不做任何更改。任何检查失败都以非零状态退出，每条失败信息都指出确切的修复方法。对于依赖已失败的检查，输出 blocked by <id>，而不是引发一连串看似无关的失败。提供 --json，供调用方根据结果分支处理
seed	加载固定的测试账户和演示数据	具备幂等性：可安全地运行两次，也可安全地对已有种子数据的数据库运行。若数据库不是本地实例或主实例，则拒绝写入种子数据
verify	按特性映射为本次更改列出的检查执行验证，优先采用成本最低的方法，并写入证明记录，说明运行了什么、覆盖了什么、跳过了什么以及原因	特性列出的每条路径都必须有对应检查，或有明确说明的跳过项。检查失败，或源文件更改未归属任何特性时，以非零状态退出

doctor 和 verify 是独立命令：前者用于只读分诊，后者负责驱动并报告。合并它们会让每次快速只读检查都被缓慢的检查掩盖。

创建模式

references/create-mode.md。访谈仓库（界面、运行、驱动、观察、隔离），根据上述契约搭建 doctor、seed、verify 和特性映射，在编写第一个特性文件前配置好隔离，为排名前三到五的特性添加种子数据，然后从头到尾验证生成的 Harness，之后才能宣布完成。未经实际运行的 Harness 只是草稿，不是交付成果。

维护模式

references/maintain-mode.md。每次会话都先运行 doctor，在首次驱动前以及任何一次驱动失败后都要运行。选择一种结果并明确说明：clean（无需更改）、changed（提交一个针对 Harness 本身、已验证修正的 PR 或提交，绝不修改产品代码），或 blocked（准确指出阻碍因素）。如果维护运行发现了真实的产品缺陷，应报告该缺陷；不得悄悄在 Harness 中修补绕过它。

此模式负责两项较轻量的探测技能不会负责的工作：限定范围的证明（每条列出的路径都经过检查，或附有原因后跳过，并记录在证明文件中；references/maintain-mode.md），以及优先复现的缺陷交接，其首行必须精确为 Reproduced、Reproduced but already fixed on main 或 Could not reproduce（references/bug-handoff.md）。

参考资料

仅在适用时加载。

参考资料	模式	阅读时机
references/create-mode.md	创建	从零搭建测试框架，或调整 doctor 或 verify 时
references/maintain-mode.md	维护	运行或扩展现有测试框架、读取或写入证明记录，或审计测试框架是否偏离时
references/feature-map-format.md	两者	编写或读取功能文件、重命名功能 ID，或构建功能地图的完整性检查时
references/verification-ladder.md	两者	为路径选择方法、将路径标记为 manual，或判断原生／桌面路径是否需要使用计算机时
references/worktree-isolation.md	两者	设置或检查端口、数据库、环境文件和浏览器配置文件的隔离，或创建测试账户并设置快捷登录时
references/reusable-checks.md	两者	添加可重复使用的 API 请求、场景断言、经检查的清理操作或捕获适配器时
references/bug-handoff.md	维护	调查错误报告时

注意事项

• 仅供开发使用的快捷登录方式或固定的测试账户密钥，一旦随产品启用发布，就会成为生产后门；添加前应先将其设为受控启用，并按照 references/worktree-isolation.md 验证防护措施。
• verify --fast（仅 CLI 检查）只是开发便利功能，绝不能单独作为合并门槛；跳过所有浏览器和计算机使用检查的运行，不能等同于完整验证，证明记录会注明运行模式。
• 第二份功能地图一旦出现，两份地图就会开始偏离。每个应用只保留一份规范地图；如果更轻量的探测技能也会跟踪路由或组件，应指向这份地图，而不要再创建一份平行地图。

相关技能

• ui-verification：针对固定 UI 规则目录进行范围明确的浏览器探测，每次处理一个发现。本技能的 verify 可以针对其覆盖的路径调用这些探测；但对于逐条规则审计，它不能取代这些探测。
• codebase-architecture：涵盖整个代码库的模块边界、CI 防护措施，以及本技能自身 CI 接线所遵循的强制执行顺序。
• test-audit：对持久测试套件进行全套精简，这与此处的功能地图是不同的工作。为差异中的新测试添加门槛属于 tidy。
• planning：针对单个功能制定计划；新功能的计划是其功能文件的起点。

仅限维护：evals/evals.json 保存了任何修改此技能的人都会用到的行为场景和路由提示词。验证运行期间不会加载该文件。

致谢

本技能基于 Lauren Tan 的 pstack create-verification-skill 和 maintain-verification-skill（MIT）：先访谈再生成的方法、基于结果的维护循环，以及优先复现的交接方式均出自她。本技能将该方法推广到一家公司的约定之外，并增加了可由机器检查的证明契约。请注明出处；本技能并非复制其中任何一个文件。