app-verification
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseApp Verification
应用验证
Builds, inside a product's own repository, the harness every agent uses to run that product and prove a claim about it: a verify CLI, a doctor command, an isolated instance per worktree, a feature map written from the user's point of view, seed data and test accounts, and a reproduce-first bug handoff. The harness lives in the target repo, not in this skill; this skill scaffolds and then maintains it, so every agent that opens that repo runs the app the same way instead of writing a throwaway script each session.
- IS: scaffolding a project-local verification harness (Create mode) and running or extending one that already exists (Maintain mode): the verify CLI's contract, the feature-map format, the proof record, per-worktree isolation and seed data, the cheapest-method ladder up to computer use, and the bug-handoff format.
- IS NOT: ad hoc browser probes against a fixed catalogue of UI rules (; this skill's
ui-verificationcan call those probes as one check among several), repo-wide module boundaries and enforcement tooling (verify; this skill's CI wiring follows its enforcement order), pruning an existing test suite (codebase-architecture), or a plan for one feature (test-audit).planning
在产品自身的仓库内构建每个 Agent 运行该产品并验证相关断言所使用的 harness:包括 verify CLI、doctor 命令、逐 worktree 隔离的实例、从用户视角编写的 feature map、seed data 与测试账户,以及先复现的 bug 交接流程。Harness 位于目标仓库中,而不是本 skill 内;本 skill 负责先搭建、后续维护它,使每个打开该仓库的 Agent 都以相同方式运行应用,而不是在每次会话中临时编写一次性脚本。
- IS: 搭建项目本地验证 harness(Create 模式),以及运行或扩展已有 harness(Maintain 模式):包括 verify CLI 的契约、feature-map 格式、proof record、逐 worktree 隔离与 seed data、从成本最低的方法逐级升级到 computer use 的验证阶梯,以及 bug-handoff 格式。
- IS NOT: 针对固定 UI 规则目录的临时 browser probes(;本 skill 的
ui-verification可以将这些 probes 作为多项检查之一调用)、仓库级模块边界与约束工具(verify;本 skill 的 CI 接入遵循其约束顺序)、裁剪现有测试套件(codebase-architecture),或针对单个功能制定计划(test-audit)。planning
Invocation
调用方式
Create mode edits the target repo and Maintain mode drives a real running instance of it; both run only when named, not from a loose "check the app" prompt a lighter skill might serve better. On a host that supports it, add to the installed copy's frontmatter. It is a host extension, not a portable field, so it is not shipped in this source ('s explains why). Hosts with an equivalent explicit-invocation setting should apply it the same way.
disable-model-invocation: trueagent-skills-creatorreferences/format-specification.mdCreate 模式会编辑目标仓库,Maintain 模式会驱动其真实运行的实例;两者都只在被明确调用时运行,不应因宽泛的“检查应用”提示而自动触发,因为轻量 skill 可能更适合处理这类请求。在支持该扩展的 host 上,向已安装副本的 frontmatter 中添加 。这是 host 扩展而非可移植字段,因此不会随此源文件一起发布( 的 解释了原因)。具有等价显式调用设置的 host 应采用相同方式处理。
disable-model-invocation: trueagent-skills-creatorreferences/format-specification.mdContents
目录
Modes
模式
Pick by what exists, and say which you picked.
| Mode | You are here when | Output |
|---|---|---|
| Create | The repo has no verify CLI, doctor command, or feature map yet | A working harness, proven once end to end against a real feature, handed off to Maintain mode |
| Maintain | A harness already exists and needs to run this session, gain a feature, or investigate a bug report | A |
Copy this to track progress:
text
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根据现有内容选择模式,并说明所选模式。
| 模式 | 适用情况 | 输出 |
|---|---|---|
| Create | 仓库尚无 verify CLI、doctor 命令或 feature map | 一个可正常工作的 harness,针对真实功能完成一次端到端验证,并移交给 Maintain 模式 |
| Maintain | Harness 已存在,需要在本次会话中运行、增加功能或调查 bug 报告 | |
复制以下内容以跟踪进度:
text
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 handoffThe harness contract
Harness 契约
Both modes build toward the same three commands, kept inside a skill folder in the target repo (for example or that host's equivalent project-skill location) so the commands live at one path every session finds the same way.
.claude/skills/verify-<app>/| Command | Does | Must |
|---|---|---|
| One read-only pass answering "is this instance worth driving": toolchain, isolation, ports, database, migrations, seed, build freshness, and whichever driver (browser, computer-use) the harness needs | Changes nothing. Exits non-zero on any failure, each failure line naming the exact fix. Prints |
| Loads fixed test accounts and demo data | Idempotent: safe to run twice, safe against a database that already has the seed. Refuses a non-local or main-instance database rather than seeding it |
| Runs the checks the feature map lists for the change, cheapest method first, and writes a proof record of what ran, what it covered, what it skipped, and why | Every path a feature lists gets a check or a named skip. Exits non-zero on a failed check or a changed source file no feature owns |
doctorverify两种模式最终都围绕同一组命令构建。这些命令保存在目标仓库内的 skill 文件夹中(例如 ,或该 host 对应的项目级 skill 位置),确保每个会话都能在相同路径找到它们。
.claude/skills/verify-<app>/| 命令 | 作用 | 必须满足 |
|---|---|---|
| 通过一次只读检查回答“这个实例是否值得驱动”:检查工具链、隔离、端口、数据库、迁移、seed、构建产物是否为最新,以及 harness 所需的 driver(browser、computer-use) | 不更改任何内容。任何失败均以非零状态退出,每条失败信息都指明确切的修复方式。对于依赖项已经失败的检查,输出 |
| 加载固定测试账户和演示数据 | 具备幂等性:可安全运行两次,也可安全作用于已有 seed 的数据库。遇到非本地或主实例数据库时拒绝执行 seed,而不是对其执行 seed。 |
| 按成本最低的优先顺序,运行 feature map 为本次变更列出的检查,并写入 proof record,记录运行内容、覆盖范围、跳过内容及原因 | Feature 列出的每条路径都应有对应检查或具名跳过。若检查失败,或出现没有任何 feature 负责的源文件变更,则以非零状态退出。 |
doctorverifyCreate mode
Create 模式
references/create-mode.mddoctorseedverifyreferences/create-mode.mddoctorseedverifyMaintain mode
Maintain 模式
references/maintain-mode.mddoctorcleanchangedblockedTwo things this mode owns that a lighter probe skill does not: scoped proof (every listed path checked or skipped with a reason, recorded in the proof file; ) and the reproduce-first bug handoff, whose first line is exactly , or ().
references/maintain-mode.mdReproducedReproduced but already fixed on mainCould not reproducereferences/bug-handoff.mdreferences/maintain-mode.mddoctorcleanchangedblocked此模式负责轻量 probe skill 不负责的两件事:范围化验证(每条列出的路径都应经过检查或带原因跳过,并记录在 proof 文件中;),以及先复现的 bug 交接,其第一行必须严格为 、 或 ()。
references/maintain-mode.mdReproducedReproduced but already fixed on mainCould not reproducereferences/bug-handoff.mdReferences
参考资料
Load only when the condition applies.
| Reference | Mode | Read when |
|---|---|---|
| references/create-mode.md | Create | Bootstrapping a harness where none exists, or reshaping |
| references/maintain-mode.md | Maintain | Running or extending an existing harness, reading or writing the proof record, or auditing the harness for drift |
| references/feature-map-format.md | Both | Writing or reading a feature file, renaming a feature id, or building the map's completeness check |
| references/verification-ladder.md | Both | Choosing a method for a path, marking a path |
| references/worktree-isolation.md | Both | Setting up or checking port, database, env-file, and browser-profile isolation, or seeding test accounts and a sign-in shortcut |
| references/reusable-checks.md | Both | Adding repeatable API requests, scenario assertions, checked cleanup, or capture adapters |
| references/bug-handoff.md | Maintain | Investigating a bug report |
仅在条件适用时加载。
| 参考资料 | 模式 | 阅读时机 |
|---|---|---|
| references/create-mode.md | Create | 引导一个尚不存在的 harness,或重构 |
| references/maintain-mode.md | Maintain | 运行或扩展现有 harness、读写 proof record,或审计 harness 是否发生漂移 |
| references/feature-map-format.md | 两种模式 | 编写或读取 feature 文件、重命名 feature id,或构建 map 完整性检查 |
| references/verification-ladder.md | 两种模式 | 为路径选择方法、将路径标记为 |
| references/worktree-isolation.md | 两种模式 | 设置或检查端口、数据库、env-file 和 browser profile 隔离,或 seed 测试账户与登录快捷方式 |
| references/reusable-checks.md | 两种模式 | 添加可重复的 API 请求、场景断言、受检清理或 capture adapter |
| references/bug-handoff.md | Maintain | 调查 bug 报告 |
Gotchas
注意事项
- A dev-only sign-in shortcut or a fixed test-account secret is a production backdoor the moment it ships enabled; gate it and verify the guard per before adding one.
references/worktree-isolation.md - (cli checks only) is a development convenience, never a merge gate on its own; a run that skipped every browser and computer-use check is not the same proof as a full one, and the proof record says which mode ran.
verify --fast - Two feature maps drift the moment a second one exists. Keep one canonical map per app; if a lighter probe skill also tracks routes or components, point at this map rather than growing a parallel one.
- 开发专用的登录快捷方式或固定测试账户密钥一旦在生产环境中启用,就会成为后门;添加前应设置访问门槛,并按照 验证防护机制。
references/worktree-isolation.md - (仅执行 CLI 检查)是一项开发便利功能,绝不能单独作为合并门禁;跳过所有 browser 和 computer-use 检查的运行,与完整运行并不构成相同的验证,proof record 应说明所采用的运行模式。
verify --fast - 一旦出现第二份 feature map,二者就会立即发生漂移。每个应用应保留一份权威 map;如果轻量 probe skill 也会跟踪路由或组件,应让它指向这份 map,而不是再维护一份并行版本。
Related skills
相关 Skill
- : scoped browser probes against a fixed UI rule catalogue, one finding at a time. This skill's
ui-verificationcan call those probes for the paths they cover; it does not replace them for a rule-by-rule audit.verify - : repo-wide module boundaries, CI guardrails, and the enforcement order this skill's own CI wiring follows.
codebase-architecture - : suite-wide pruning of a durable test suite, a different asset from the feature map here. Gating a new test in a diff is
test-audit.tidy - : a plan for one feature; a new feature's plan is where its eventual feature file starts.
planning
Maintenance only: holds the behavioural scenarios and routing prompts for anyone changing this skill. It never loads during a verification run.
evals/evals.json- :针对固定 UI 规则目录执行范围化 browser probes,每次处理一个发现。本 skill 的
ui-verification可以针对相关路径调用这些 probes,但不能在逐规则审计中替代它们。verify - :定义仓库级模块边界和 CI 护栏;本 skill 自身的 CI 接入遵循其约束顺序。
codebase-architecture - :对持久测试套件进行全局裁剪,这与此处使用的 feature map 是不同的资产。在 diff 中为新测试设置门禁属于
test-audit。tidy - :为单个功能制定计划;新功能的计划正是其最终 feature 文件的起点。
planning
仅限维护模式: 保存了供修改本 skill 的人员使用的行为场景与路由提示。验证运行期间绝不会加载它。
evals/evals.jsonCredit
致谢
Builds on Lauren Tan's pstack and (MIT): the interview-then-generate method, the outcome-based maintenance loop, and the reproduce-first handoff are hers. This skill generalizes that method past one company's conventions and adds a machine-checkable proof contract. Credit them; this is not a copy of either file.
create-verification-skillmaintain-verification-skill本 skill 基于 Lauren Tan 的 pstack 和 (MIT)构建:先访谈再生成的方法、基于结果的维护循环,以及先复现的交接流程均源自她的工作。本 skill 将该方法推广到单一公司的惯例之外,并增加了可由机器检查的 proof contract。在此向她致谢;本 skill 并非这两个文件中任何一个文件的副本。
create-verification-skillmaintain-verification-skill