create-verification-skill

创建验证技能

每个严肃的项目都需要一种脚本化方式来驱动真实应用并验证其行为：启动应用、像用户一样体验某项功能，并采集证据。此技能会生成一个针对该仓库定制的项目本地技能（.claude/skills/verify-<app>/）。你编写的生成结果是给下一个 Agent 看的，而不是给人看的：它会在任务进行到一半时首次被一个从未接触过此应用的 Agent 读取。

平台说明。 在 Claude Code 中，生成的技能会放在 .claude/skills/verify-<app>/ 下。在 Codex 或其他运行环境中，请将其写入该运行环境对应的项目技能目录。驱动应用的测试工具（浏览器/CDP、PTY/tmux、HTTP）与平台无关；请通过 codex-tools.md 确认工具名称。

1. 检查仓库，不要询问用户

请从代码库中查明以下信息，只询问用户无法观察到的内容：

• 界面： 用户实际会接触什么？Web UI、CLI/TUI、桌面应用、API、移动应用，还是库？一个仓库可能包含多个界面；请选择主要界面，并注明其余界面。
• 运行： 如何在本地启动应用？优先采用仓库文档中的开发命令（package 脚本、Makefile、README 快速入门）。记录端口、环境变量、种子数据和身份验证信息。
• 驱动： Agent 如何通过编程方式与应用交互？先查找现有测试工具——Playwright/Cypress 测试、expect 脚本、PTY 辅助工具、可通过 curl 访问的端点、调试端口。只有在此之后，才选择通用方案：Web 和 Electron 使用浏览器/CDP，CLI/TUI 使用 tmux/PTY 测试工具，服务使用普通 HTTP。
• 观察： 可以采集哪些证据？截图、终端记录、响应正文、日志、退出代码、数据库状态。
• 隔离： 能否同时运行两个实例（端口、数据目录、配置文件）？如果不能，请在生成的技能中说明：拒绝同时驱动共享实例，也好过破坏用户的会话。

如果当前检出版本无法构建或启动，请先修复问题（或准确报告问题），再生成技能；针对有问题的基础版本编写技能会教错步骤。如果无关的缺失资源阻碍启动（例如 API 根本不会提供服务的静态目录、示例配置），生成的技能可以创建该资源，但必须明确标记为验证脚手架，并在清理时将其移除。

2. 生成技能

编写 .claude/skills/verify-<app>/SKILL.md，添加 YAML 前置内容（name: verify-<app>，以及一个说明 description，写明应用、界面和适用场景——没有前置内容时，技能永远不会注册），并添加以下章节。每一节都必须以访谈实际发现的内容为依据（不得遗留占位符）：

• **启动：**写明用于启动应用以供验证的确切命令，以及如何判断应用已就绪（例如日志行或提示符）。从空数据目录启动时，必须能进入可用状态，包括执行任何迁移和填充种子数据。就绪意味着可以使用，而不只是进程有响应。数据库健康检查可能通过了，但初始化脚本仍在运行。写明如何拆除实例。对于生命周期较短的 CLI 或 TUI，无需保持服务运行：启动即构建二进制文件（或安装依赖）一次，然后在独立的 PTY 或 tmux 会话中分别启动每次操作。
• **检查：**提供一项只读检查，以回答“这个实例值得操作吗？”——进程正在运行、版本或构建版本正确、端口由本实例占用、身份验证有效。当出现任何异常时，Agent 应首先运行此检查。
• **操作：**提供测试框架的操作步骤，使用此代码库中的真实选择器或命令，而不是示例。优先使用稳定的标识（ARIA 标签、数据属性、提示字符串、路由路径），而不是坐标和 Tab 键顺序。
• **证据：**说明要为验证证明捕获哪些内容，以及保存位置。明确证明标准：走通真实用户路径，不使用内部 setter 或仅用于测试的端点；捕获操作和产生的状态，而不只是最终画面；验证副作用（写入的文件、插入的行、发送的消息），并检查可见内容；仅在生产边界已隔离外部系统的地方使用模拟。安全路径为 dry-run 或测试模式时，应通过观察文件、网络、git 引用等内容，验证它实际跳过了什么，而不是只相信其名称：有些 dry-run 仍会访问网络或打开浏览器。
• **清理：**说明如何拆除本次运行创建的实例。切勿按进程名称终止进程；只终止自己启动的进程。清理时删除实例和临时状态，但绝不删除证据：证明产物必须在拆除后保留，并将其位置写在技能中。
• **辅助工具：**技能附带的任何脚本都必须可执行，并且技能正文中要写明调用方法。需要读者自行逆向工程的辅助工具不算辅助工具。

3. 填充功能地图

创建 .claude/skills/verify-<app>/features/README.md，并为你能识别出的每项面向用户的功能各创建一个文件（先从路由、命令、菜单或文档中挑选 3–5 项）。遵循 references/feature-map-example/ 中的结构，包含 README 索引和每项功能对应的文件。每个文件都应从用户视角说明：功能是什么、如何访问、如何使用测试框架操作，以及什么可观察到的最终状态能证明功能正常。四个二级标题分别为 Sub-features、How to get to it (user POV)、Driving it with <harness> 和 Gotchas。如果种子数据缺少某段流程所需的前置条件，该流程应报告失败，并在相应功能的 Gotchas 中说明原因。绝不要为了让流程通过而降低要求。功能地图是代码库中持续维护的验证依据；若地图列出了多个入口，只通过一个方便入口操作的证明并不完整。

4. 交付前证明生成的技能有效

端到端运行一次技能自身的指令：启动、运行 doctor、驱动一个已映射功能（一个就够；这份映射是为了后续运行覆盖其余功能）、收集证据、清理。清理后，确认指定位置仍有证据——如果清理操作删除了证据，就不算通过此步骤。修复所有失败之处，并且每次迭代失败后都运行生成的清理操作，以免失败的尝试遗留进程和端口。未经实际运行的生成技能只是草稿，不是可交付成果。如果你是在真实目标的替代环境中验证的（例如用容器代替全新的 VM，用本地技术栈代替远程技术栈），请列出替代环境执行、而目标环境不会执行的所有设置步骤。在真实目标上运行并覆盖这些步骤之前，它们都仍未经过验证。

5. 提供维护流程

引导用户使用 /maintain-verification-skill，以便在应用发生变化时保持映射准确。只有在用户询问时，才建议维护周期。