sdd-verify

基于表面的验证

单元测试只能证明代码实现了测试所描述的行为；这项技能则能验证改动在运行中的应用里确实有效。它会根据改动实际涉及的内容，选择相应的验证方式。

1. 检测涉及的表面（根据差异）

检查改动的 git diff：

• 前端：涉及渲染的 UI，如 .tsx/.jsx/.vue/.svelte/.html/.css/.scss、组件或页面/路由目录、设计令牌、Storybook 等。
• API / 后端：涉及请求处理程序、路由、控制器、解析器、OpenAPI/Swagger 规范、序列化器或 lambda 处理程序。
• 改动可能同时涉及两者——请验证两个表面。

如果都不涉及（纯库/工具链/文档改动），请说明这一点并停止——没有需要驱动的内容；单元测试就是完整的验证门槛。

2. 前端 → chrome-devtools MCP

需要 chrome-devtools-mcp 插件（通过 ToolSearch 加载其工具：+chrome navigate）。

1. 启动开发服务器（或确认其正在运行）——阅读项目的运行/开发脚本；切勿假设端口号。
2. 对受影响的路由调用 navigate_page。
3. 调用 take_screenshot——确认设计能够正常渲染（布局、修改后的组件，没有明显问题）。如果改动有参考设计，请与之对照。
4. 调用 list_console_messages——确保没有新增错误。调用 list_network_requests——确保该视图没有失败的请求。也可以对受影响的页面运行无障碍/Lighthouse 检查。
5. 报告：渲染正常 ✓/✗、控制台无错误 ✓/✗、网络正常 ✓/✗，并附上截图作为证据。

3. API → Playwright 请求脚本

需要 Playwright（kit 安装程序会确认这一点；否则运行 pnpm add -D @playwright/test）。

1. 根据差异和任何 OpenAPI 变更，确定受影响的端点（方法 + 路径）。

2. 在 scripts-dev/ 下编写一个临时脚本（例如 api_smoke.spec.ts），使用 Playwright 的 request 上下文——不要使用浏览器：

   import { test, expect, request } from '@playwright/test'
   test('affected endpoint', async () => {
     const api = await request.newContext({ baseURL: process.env.BASE_API_URL })
     const res = await api.get('/the/affected/path')      // or .post(...) with a body
     expect(res.status()).toBe(200)
     expect(await res.json()).toMatchObject({ /* the shape the delta spec promises */ })
   })
   

3. 使用当前 shell 自己的凭据/环境运行脚本（不要切换角色，也不要扩大 IAM 权限）： npx playwright test scripts-dev/api_smoke.spec.ts。

4. 报告每个端点的状态码和结构断言；按照仓库惯例保留或删除脚本。

在工作流中的位置

Harness 的 Validate 阶段会运行确定性基础检查（单元测试 + openspec --strict）；它不会自动驱动浏览器或 API。完成改动后，或批准 PR 前，请自行调用这项技能（或让 Agent 调用它），以确认运行中的表面确实有效。这项能力保留为技能（而不是自动化门禁），以便 Harness 不受技术栈限制。

规则

• 驱动真实表面；单元测试套件通过，并不等于“页面能够渲染”或“端点返回承诺的结构”。
• 切勿扩大凭据/IAM 权限来让检查通过——请使用当前会话自身的环境。
• 临时 API 脚本应放在 scripts-dev/ 下；切勿将密钥提交到这些脚本中。