--- name: create-verification-skill description: "生成一个按用户方式驱动应用的项目本地验证技能,适用于任何语言、框架或平台。用于 /create-verification-skill、‘为这个仓库做一个控制技能’,或项目尚无脚本化方式证明 UI、CLI、服务行为时。" disable-model-invocation: true --- # 创建验证技能 在 Claude Code 中,每个会话在遵循此技能前,先阅读一次 [Claude Code 适配器](../../docs/harness/claude-code.md)。它将 pstack 技能中的 Cursor 名称映射到 Claude Code。 每个严肃项目都需要用脚本驱动真实应用并证明行为:启动应用,像用户一样操作一个功能,并记录证据。本技能把这种能力生成为适配仓库的项目本地技能(`.cursor/skills/verify-/`)。生成内容是写给下一个智能体,不是人:一个从未见过应用的智能体会在任务中途冷启动阅读它。 ## 1. 询问仓库,而非用户 从代码库回答以下问题,只有无法观察的内容才询问用户: - **界面:** 用户实际接触什么?Web UI、CLI/TUI、桌面应用、API、移动应用、库?仓库可有多个,选主要界面并记录其他界面。 - **运行:** 应用如何本地启动?优先仓库文档中的开发命令(包脚本、Makefile、README 快速入门)。记录端口、环境变量、种子数据、认证。 - **驱动:** 智能体如何通过程序交互?优先现有驱动设施,包括 Playwright/Cypress 规格、expect 脚本、PTY 辅助工具、可 curl 的端点、调试端口。之后才选通用配方:Web 和 Electron 用浏览器/CDP,CLI/TUI 用 tmux/PTY 驱动,服务用普通 HTTP。 - **观察:** 能捕获什么证据?截图、终端记录、响应正文、日志、退出码、数据库状态。 - **隔离:** 两个实例能否并行运行(端口、数据目录、配置档案)?不能时在生成技能中说明:拒绝同时驱动共享实例,比破坏用户会话好。 如果当前检出内容无法原样构建或启动,先修复或精确报告,再生成;对着损坏基线写技能会教出错误步骤。启动被无关的缺失资源阻塞时(API 从不提供的静态目录、样例配置),生成技能可以创建它,但明确标为验证脚手架,并在清理时移除。 ## 2. 生成技能 写 `.cursor/skills/verify-/SKILL.md`,包含 YAML frontmatter(`name: verify-`,以及说明应用、界面、何时使用的 `description`;没有 frontmatter 技能不会注册),并包含以下章节。每节都基于调查实际发现,不保留占位符: - **启动:** 启动验证应用的精确命令,以及如何判断就绪(日志行、提示符)。必须能从空数据目录达到可用状态,包括迁移与种子数据。就绪意味着可用,不只是进程响应。数据库健康检查通过时,初始化脚本可能还在运行。包含停止方法。短生命周期 CLI/TUI 无需持续服务器:启动指构建一次二进制或安装依赖,然后每次驱动在独立 PTY 或 tmux 会话开始。 - **诊断:** 一个只读检查,回答“这个实例值得驱动吗”:进程在运行、版本或构建正确、端口归本次运行所有、认证有效。任何情况不对时智能体先运行它。 - **驱动:** 用仓库真实选择器或命令编写驱动配方,不用示例。优先稳定定位(ARIA 标签、数据属性、提示字符串、路由路径),不优先坐标和 Tab 顺序。 - **证据:** 证明要记录什么、放在哪里。说明证据标准:操作真实用户路径,不用内部 setter 或仅测试端点;记录动作及其结果状态,不只最终屏幕;与可见内容一起验证副作用(写出的文件、插入的行、发出的消息);仅在生产边界本已隔离外部系统时使用模拟。安全路径是 dry-run 或测试模式时,通过观察文件、网络、git 引用验证它实际跳过什么,不信名称;有些 dry-run 仍访问网络或打开浏览器。 - **清理:** 如何停止本次创建的实例。不要按进程名杀进程,只终止自己启动的。清理删除实例与临时状态,不删除证据;证明产物在技能指出的位置保留,跨越清理存活。 - **辅助工具:** 随技能提供的脚本必须可执行,调用方式在技能正文展示。读者要反向研究才能用的工具不是辅助工具。 ## 3. 建立初始功能图 创建 `.cursor/skills/verify-/features/README.md`,再给每个可识别的用户功能建一份文件。先从路由、命令、菜单或文档挑前 3 至 5 个。遵循 [`references/feature-map-example/`](references/feature-map-example/) 的形态,包含 README 索引和每功能一文件。每份文件从用户视角回答:功能是什么、如何到达、如何用驱动设施操作、什么可观察最终状态能证明它可用。四个 H2 是 `Sub-features`、`How to get to it (user POV)`、`Driving it with `、`Gotchas`。若种子数据缺少旅程前置条件,旅程应报告失败,并把原因写进该功能 `Gotchas`。绝不弱化旅程以求通过。功能图是仓库持续维护的验证来源;图中列出其他入口时,仅驱动一个方便入口的证明不完整。 ## 4. 交付前证明生成的技能 按生成说明端到端运行一次:启动、诊断、驱动一个已映射功能、记录证据、清理。一个功能足够;功能图用于后续覆盖其余部分。清理后确认指定位置的证据仍在;吞掉证据的清理会让本步失败。修复失败项,每次失败迭代后也运行生成的清理,避免破损尝试遗留进程与端口。从未执行的生成技能只是草稿,不是交付物。若在真实目标的替代环境中证明(容器替代新 VM、本地技术栈替代远端),列出替代环境执行而目标不会自动执行的每个设置步骤。真实目标运行覆盖前,这些步骤保持未验证。 ## 5. 提供维护循环 指向 `/maintain-verification-skill`,用于应用变化时保持功能图真实。只有用户询问时才建议频率。