make-verify

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

make-verify

Write

.agents/skills/verify/

, a project skill an agent reads cold, mid-task, to prove a change works in the running product. Every line names a real command, handle, or thing to look at. If the project already has a verify skill, stop and say so.

编写

.agents/skills/verify/

，这是一个项目级 skill，Agent 可在无任何前置上下文时或任务中途读取，以证明某项变更在实际运行的产品中有效。每一行都要指明真实的命令、handle，或需要检查的对象。如果项目已有 verify skill，请停止并说明。

1. Read the repository

From the code, asking the user only what it cannot say, find the surfaces (name the primary one), how to start it and know it is ready, how to drive it (existing harnesses first), what can observe a result, and whether two runs can be isolated.

If the product does not start, fix it or report why before writing anything. For state that cannot be moved, ask the user about a config seam (the smallest setting, defaulting to today's value, in its own commit); what stays shared is out of reach unless the user says otherwise.

从代码中找出 交互面（surfaces）（注明主要交互面）、如何 启动（start） 产品并判断其已就绪、如何 驱动（drive） 产品（优先使用现有 harness）、用什么 观察（observe） 结果，以及两次运行能否 隔离（isolate）。

如果产品无法启动，请先修复，或在编写任何内容之前报告原因。对于无法迁移的状态，向用户询问 config seam（配置接缝：最小的设置项，默认值保持当前值，并单独提交）；除非用户明确允许，否则仍共享的状态不在可操作范围内。

2. Write the skill

.agents/skills/verify/SKILL.md

with

name: verify

. Its description says it starts the product, drives it, and records whether each check passed, and that agents use it on their own before calling a change done: implement-slice finds it by those words. Beside it,

agents/openai.yaml

with

allow_implicit_invocation: true

Body sections:

Start: the command, the ready signal, and the run folder
```
.scratch/verify/<run>/
```
(
```
<run>
```
is a timestamp plus random characters), holding the run's own port and data, and none of the user's settings. Without isolation, refuse any instance the run did not start. List what a run cannot reach, and refuse it.
Doctor: a read-only check that the instance is up, this run's, the current build, signed in. Run it first and whenever something looks off.
Drive: real commands, with handles that survive a redesign: roles, accessible names, labels, routes, flags.
Proof bar: drive the user's real path. Capture the action and the state it led to. Read side effects back. Drive every entry point the map lists. Fake only what production already puts behind a boundary.
Evidence:
```
evidence.md
```
in the run folder holds:
- the commit and branch, and whether the tree was dirty
- the verdict: Done, Done, with n not driven naming them, Not done with the failed checks, or Done once the map changes in this PR
- one section per check: verdict, note, what was captured, every command run with its output
Each check is:
- ```
pass
```
  : the product does what the check says.
- ```
fail
```
  : it does not, and the code is wrong. The note says what happened instead.
- ```
manual
```
  : it does not, and the map is wrong, because the change meant this. The note says why, and the map changes in the same PR.
- ```
not driven
```
  : it needs something a run cannot reach. The note names it, and the check stays with the user.
Stop: stop what this run started, by recorded pid, then confirm doctor says unfit. The run folder stays.

Ship a helper script only for what one command cannot do reliably, such as keeping a browser page alive. It appends every call and its output to

transcript.log

in the run folder, reads state back through a logged command, refuses what the run must not reach, and records the real process pid.

创建

.agents/skills/verify/SKILL.md

，其中包含

name: verify

。其 description 应说明：该 skill 会启动产品、驱动产品，并记录每项检查是否通过；Agent 在将某项变更视为完成之前，应自行调用它：implement-slice 会根据这些描述找到它。旁边还要有

agents/openai.yaml

，其中包含

allow_implicit_invocation: true

。

正文包含以下部分：

Start（启动）：给出命令、就绪信号，以及运行目录
```
.scratch/verify/<run>/
```
（
```
<run>
```
为时间戳加随机字符）。该目录保存本次运行专属的端口和数据，且不得包含用户的任何设置。如果没有隔离能力，应拒绝使用任何并非由本次运行启动的实例。列明本次运行无法访问的内容，并拒绝访问。
Doctor（诊断）：执行只读检查，确认实例已启动、属于本次运行、是当前构建，并且已登录。首次运行时以及任何看起来异常时，都应先执行此检查。
Drive（驱动）：使用真实命令，并采用可在重新设计后仍保持稳定的 handle：role、accessible name、label、route、flag。
Proof bar（验证标准）：沿用户真实路径进行操作。捕获动作及其导致的状态。回读副作用。驱动 map 列出的每个入口点。只有生产环境已经置于边界之后的内容才能使用模拟。
Evidence（证据）：运行目录中的
```
evidence.md
```
包含：
- commit、branch，以及工作树是否处于 dirty 状态
- 判定结果：Done、Done, with n not driven（列出未驱动的项目）、Not done（列出失败的检查），或 Done once the map changes in this PR
- 每项检查一个 section：判定结果、备注、捕获的内容，以及运行过的每条命令及其输出
每项检查分为：
- ```
pass
```
  ：产品行为符合检查说明。
- ```
fail
```
  ：产品行为不符合检查说明，且代码有问题。备注说明实际发生了什么。
- ```
manual
```
  ：产品行为不符合检查说明，且 map 有误，因为这项变更本就应产生该行为。备注说明原因，并在同一个 PR 中更新 map。
- ```
not driven
```
  ：检查需要本次运行无法访问的内容。备注写明具体内容，该检查仍交由用户处理。
Stop（停止）：根据记录的 pid 停止本次运行启动的进程，然后确认 doctor 报告实例不可用。保留运行目录。

仅当单条命令无法可靠完成某项操作时，才提供 helper script，例如让浏览器页面保持存活。它会将每次调用及其输出追加到运行目录中的

transcript.log

，通过已记入日志的命令回读状态，拒绝执行触及禁区的操作，并记录真实进程的 pid。

3. Write the feature map

docs/manual/

, also the user's own checklist, shaped like references/feature-map-example/. Write the top three to five features, copying each "you should see" from what the product showed while you drove it, and fold any existing manual in, keeping every step. The skill points at the map and never copies it.

编写

docs/manual/

，同时作为用户自己的检查清单，结构参照 references/feature-map-example/。选取最重要的三到五个功能，在驱动产品时，将每个功能对应的 “you should see” 复制到 map 中；将任何现有 manual 合并进来，并保留每一个步骤。 skill 只指向 map，绝不复制其内容。

4. Wire it in

Edit existing files:

Add to the project's agent instructions: a change the map describes is done only when a verify run's
```
evidence.md
```
has no failed check, and the map changes in the same PR as the behaviour.
If
```
.claude/skills
```
is missing, commit it as a symlink to
```
../.agents/skills
```
.
Ignore
```
.scratch/
```
.

编辑现有文件：

在项目的 agent instructions 中添加：map 所描述的变更，只有在 verify 运行的
```
evidence.md
```
中没有失败检查后才算完成；map 必须与行为变更在同一个 PR 中更新。
如果缺少
```
.claude/skills
```
，将其作为指向
```
../.agents/skills
```
的 symlink 提交。
将
```
.scratch/
```
加入忽略规则。

5. Prove it

Have a fresh agent (or yourself, if none) follow only the skill and the map: start, doctor, drive one mapped feature, record it, stop. Fix every line that made it guess, and repeat until one clean run leaves its

evidence.md

and nothing running.

让一个全新的 Agent（如果没有，则由你自己）仅依据 skill 和 map 执行：启动、运行 doctor、驱动一个已映射的功能、记录结果并停止。修正所有会让执行者不得不猜测的内容，并重复操作，直到一次干净的运行生成其

evidence.md

，且没有进程仍在运行。

6. Report

The surfaces and which one is driven, the isolation case, every file written, their branch and commit (they must reach the default branch before implement-slice runs), the proving run's folder and verdict, and what the skill cannot drive yet.

报告交互面以及实际驱动了哪一个、隔离情况、所有写入的文件、所在 branch 和 commit（对应改动必须在 implement-slice 运行前进入默认分支）、验证运行的目录和判定结果，以及 skill 目前仍无法驱动的内容。