app-verification

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

App 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 (
    ui-verification
    ; this skill's
    verify
    can call those probes as one check among several), repo-wide module boundaries and enforcement tooling (
    codebase-architecture
    ; this skill's CI wiring follows its enforcement order), pruning an existing test suite (
    test-audit
    ), or a plan for one feature (
    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(
    ui-verification
    ;本 skill 的
    verify
    可以将这些 probes 作为多项检查之一调用)、仓库级模块边界与约束工具(
    codebase-architecture
    ;本 skill 的 CI 接入遵循其约束顺序)、裁剪现有测试套件(
    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
disable-model-invocation: true
to the installed copy's frontmatter. It is a host extension, not a portable field, so it is not shipped in this source (
agent-skills-creator
's
references/format-specification.md
explains why). Hosts with an equivalent explicit-invocation setting should apply it the same way.
Create 模式会编辑目标仓库,Maintain 模式会驱动其真实运行的实例;两者都只在被明确调用时运行,不应因宽泛的“检查应用”提示而自动触发,因为轻量 skill 可能更适合处理这类请求。在支持该扩展的 host 上,向已安装副本的 frontmatter 中添加
disable-model-invocation: true
。这是 host 扩展而非可移植字段,因此不会随此源文件一起发布(
agent-skills-creator
的
references/format-specification.md
解释了原因)。具有等价显式调用设置的 host 应采用相同方式处理。

Contents

目录

Modes

模式

Pick by what exists, and say which you picked.
ModeYou are here whenOutput
CreateThe repo has no verify CLI, doctor command, or feature map yetA working harness, proven once end to end against a real feature, handed off to Maintain mode
MaintainA harness already exists and needs to run this session, gain a feature, or investigate a bug reportA
clean
/
changed
/
blocked
outcome, or a reproduce-first bug handoff
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 模式
MaintainHarness 已存在,需要在本次会话中运行、增加功能或调查 bug 报告
clean
/
changed
/
blocked
结果,或先复现的 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 handoff

The harness contract

Harness 契约

Both modes build toward the same three commands, kept inside a skill folder in the target repo (for example
.claude/skills/verify-<app>/
or that host's equivalent project-skill location) so the commands live at one path every session finds the same way.
CommandDoesMust
doctor
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 needsChanges nothing. Exits non-zero on any failure, each failure line naming the exact fix. Prints
blocked by <id>
for a check whose dependency already failed instead of a cascade of unrelated-looking failures. Offers
--json
for a caller that branches on the result
seed
Loads fixed test accounts and demo dataIdempotent: 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
verify
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 whyEvery 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
doctor
and
verify
are separate commands: one is read-only triage, the other drives and reports. Merging them hides the read-only fast check behind the slow one every time.
两种模式最终都围绕同一组命令构建。这些命令保存在目标仓库内的 skill 文件夹中(例如
.claude/skills/verify-<app>/
,或该 host 对应的项目级 skill 位置),确保每个会话都能在相同路径找到它们。
命令作用必须满足
doctor
通过一次只读检查回答“这个实例是否值得驱动”:检查工具链、隔离、端口、数据库、迁移、seed、构建产物是否为最新,以及 harness 所需的 driver(browser、computer-use)不更改任何内容。任何失败均以非零状态退出,每条失败信息都指明确切的修复方式。对于依赖项已经失败的检查,输出
blocked by <id>
,避免产生一连串看似无关的失败。提供
--json
,供调用方根据结果分支处理。
seed
加载固定测试账户和演示数据具备幂等性:可安全运行两次,也可安全作用于已有 seed 的数据库。遇到非本地或主实例数据库时拒绝执行 seed,而不是对其执行 seed。
verify
按成本最低的优先顺序,运行 feature map 为本次变更列出的检查,并写入 proof record,记录运行内容、覆盖范围、跳过内容及原因Feature 列出的每条路径都应有对应检查或具名跳过。若检查失败,或出现没有任何 feature 负责的源文件变更,则以非零状态退出。
doctor
和
verify
是两个独立命令:一个负责只读诊断,另一个负责驱动并报告。将二者合并,会让只读的快速检查每次都被较慢的检查流程掩盖。

Create mode

Create 模式

references/create-mode.md
. Interview the repo (surface, run, drive, observe, isolate), scaffold
doctor
,
seed
,
verify
and the feature map per the contract above, wire isolation before writing the first feature file, seed the top three to five features, then prove the generated harness end to end before calling it done. A harness nobody has run is a draft, not a deliverable.
references/create-mode.md
。探查仓库(surface、run、drive、observe、isolate),按照上述契约搭建
doctor
、
seed
、
verify
和 feature map,在编写第一个 feature 文件前先接入隔离机制,为最重要的三到五个 feature 建立初始内容,然后在宣布完成前对生成的 harness 进行端到端验证。没人运行过的 harness 只是草稿,不是可交付成果。

Maintain mode

Maintain 模式

references/maintain-mode.md
. Run
doctor
first, every session, before the first drive and after any failed one. Pick one outcome and say which:
clean
(nothing needed changing),
changed
(one PR or commit of proven corrections to the harness itself, never to product code), or
blocked
(name exactly what blocked it). A maintenance run that finds a real product bug reports it; it does not quietly patch around it inside the harness.
Two 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;
references/maintain-mode.md
) and the reproduce-first bug handoff, whose first line is exactly
Reproduced
,
Reproduced but already fixed on main
or
Could not reproduce
(
references/bug-handoff.md
).
references/maintain-mode.md
。每次会话开始后,先运行
doctor
,且必须在首次 drive 之前以及任何失败之后运行。选择一种结果并明确说明:
clean
(无需修改任何内容)、
changed
(用一个 PR 或 commit 提交已证明正确的 harness 修正,绝不修改产品代码),或
blocked
(准确指出阻塞原因)。维护运行发现真实的产品 bug 时应报告该问题,而不是在 harness 内悄悄绕过问题进行补丁。
此模式负责轻量 probe skill 不负责的两件事:范围化验证(每条列出的路径都应经过检查或带原因跳过,并记录在 proof 文件中;
references/maintain-mode.md
),以及先复现的 bug 交接,其第一行必须严格为
Reproduced
、
Reproduced but already fixed on main
或
Could not reproduce
(
references/bug-handoff.md
)。

References

参考资料

Load only when the condition applies.
ReferenceModeRead when
references/create-mode.mdCreateBootstrapping a harness where none exists, or reshaping
doctor
or
verify
references/maintain-mode.mdMaintainRunning or extending an existing harness, reading or writing the proof record, or auditing the harness for drift
references/feature-map-format.mdBothWriting or reading a feature file, renaming a feature id, or building the map's completeness check
references/verification-ladder.mdBothChoosing a method for a path, marking a path
manual
, or deciding whether a native/desktop path needs computer use
references/worktree-isolation.mdBothSetting up or checking port, database, env-file, and browser-profile isolation, or seeding test accounts and a sign-in shortcut
references/reusable-checks.mdBothAdding repeatable API requests, scenario assertions, checked cleanup, or capture adapters
references/bug-handoff.mdMaintainInvestigating a bug report
仅在条件适用时加载。
参考资料模式阅读时机
references/create-mode.mdCreate引导一个尚不存在的 harness,或重构
doctor
或
verify
references/maintain-mode.mdMaintain运行或扩展现有 harness、读写 proof record,或审计 harness 是否发生漂移
references/feature-map-format.md两种模式编写或读取 feature 文件、重命名 feature id,或构建 map 完整性检查
references/verification-ladder.md两种模式为路径选择方法、将路径标记为
manual
,或判断 native/desktop 路径是否需要 computer use
references/worktree-isolation.md两种模式设置或检查端口、数据库、env-file 和 browser profile 隔离,或 seed 测试账户与登录快捷方式
references/reusable-checks.md两种模式添加可重复的 API 请求、场景断言、受检清理或 capture adapter
references/bug-handoff.mdMaintain调查 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
    references/worktree-isolation.md
    before adding one.
  • verify --fast
    (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.
  • 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
    验证防护机制。
  • verify --fast
    (仅执行 CLI 检查)是一项开发便利功能,绝不能单独作为合并门禁;跳过所有 browser 和 computer-use 检查的运行,与完整运行并不构成相同的验证,proof record 应说明所采用的运行模式。
  • 一旦出现第二份 feature map,二者就会立即发生漂移。每个应用应保留一份权威 map;如果轻量 probe skill 也会跟踪路由或组件,应让它指向这份 map,而不是再维护一份并行版本。

Related skills

相关 Skill

  • ui-verification
    : scoped browser probes against a fixed UI rule catalogue, one finding at a time. This skill's
    verify
    can call those probes for the paths they cover; it does not replace them for a rule-by-rule audit.
  • codebase-architecture
    : repo-wide module boundaries, CI guardrails, and the enforcement order this skill's own CI wiring follows.
  • test-audit
    : suite-wide pruning of a durable test suite, a different asset from the feature map here. Gating a new test in a diff is
    tidy
    .
  • planning
    : a plan for one feature; a new feature's plan is where its eventual feature file starts.
Maintenance only:
evals/evals.json
holds the behavioural scenarios and routing prompts for anyone changing this skill. It never loads during a verification run.
  • ui-verification
    :针对固定 UI 规则目录执行范围化 browser probes,每次处理一个发现。本 skill 的
    verify
    可以针对相关路径调用这些 probes,但不能在逐规则审计中替代它们。
  • codebase-architecture
    :定义仓库级模块边界和 CI 护栏;本 skill 自身的 CI 接入遵循其约束顺序。
  • test-audit
    :对持久测试套件进行全局裁剪,这与此处使用的 feature map 是不同的资产。在 diff 中为新测试设置门禁属于
    tidy
    。
  • planning
    :为单个功能制定计划;新功能的计划正是其最终 feature 文件的起点。
仅限维护模式:
evals/evals.json
保存了供修改本 skill 的人员使用的行为场景与路由提示。验证运行期间绝不会加载它。

Credit

致谢

Builds on Lauren Tan's pstack
create-verification-skill
and
maintain-verification-skill
(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.
本 skill 基于 Lauren Tan 的 pstack
create-verification-skill
和
maintain-verification-skill
(MIT)构建:先访谈再生成的方法、基于结果的维护循环,以及先复现的交接流程均源自她的工作。本 skill 将该方法推广到单一公司的惯例之外,并增加了可由机器检查的 proof contract。在此向她致谢;本 skill 并非这两个文件中任何一个文件的副本。