Back to Details

sdd-verify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Surface-aware verification

面向界面的验证

Unit tests prove the code does what its tests say; this skill proves the change works in the running app. It picks the validation that matches what the change actually touches.
单元测试只能证明代码符合测试用例的预期；而本技能可证明变更在运行中的应用实际生效。它会根据变更实际涉及的界面类型选择对应的验证方式。

1. Detect the surface (from the diff)

1. 检测变更涉及的界面（通过代码差异）

Inspect 
git diff
for the change:
  • Frontend if it touches rendered UI: 
    .tsx/.jsx/.vue/.svelte/.html/.css/.scss
    , component or page/route dirs, design tokens, a Storybook, etc.
  • API / backend if it touches request handlers, routes, controllers, resolvers, an OpenAPI/Swagger spec, serializers, or lambda handlers.
  • A change can be both — validate both surfaces.
If neither surface is present (pure lib/tooling/docs), say so and stop — there is nothing to drive; the unit-test floor is the whole gate.
检查
git diff
中的变更内容：
  • 前端界面：若变更涉及渲染后的UI相关文件，如
    .tsx/.jsx/.vue/.svelte/.html/.css/.scss
    、组件或页面/路由目录、设计令牌、Storybook等。
  • API / 后端界面：若变更涉及请求处理器、路由、控制器、解析器、OpenAPI/Swagger规范、序列化器或Lambda处理器等。
  • 变更可能同时涉及两者——此时需对两种界面分别验证。
若变更未涉及上述任何界面（仅为纯库/工具/文档变更），则无需进行后续操作——单元测试即可作为验证依据。

2. Frontend → chrome-devtools MCP

2. 前端场景 → 使用chrome-devtools MCP

Requires the 
chrome-devtools-mcp
plugin (load its tools via ToolSearch: 
+chrome navigate
).
  1. Start (or confirm) the dev server — read the project's run/dev script; do NOT assume a port.
  2. navigate_page
    to the affected route(s).
  3. take_screenshot
    — confirm the design renders (layout, the changed component, no obvious breakage). If the change has a reference design, compare against it.
  4. list_console_messages
    — no new errors. 
    list_network_requests
    — no failed calls for the view. Optionally run an accessibility/Lighthouse check on the affected page.
  5. Report: rendered ✓/✗, console clean ✓/✗, network clean ✓/✗, with the screenshot as evidence.
需安装
chrome-devtools-mcp
插件（可通过ToolSearch加载工具：
+chrome navigate
）。
  1. 启动（或确认已启动）开发服务器——需查看项目的run/dev脚本，不要默认假设端口号。
  2. 使用
    navigate_page
    导航至受影响的路由。
  3. 执行
    take_screenshot
    ——确认页面设计渲染正常（布局、变更后的组件无明显损坏）。若变更有参考设计，需与参考设计进行对比。
  4. 执行
    list_console_messages
    ——确保无新增错误；执行
    list_network_requests
    ——确保当前视图无失败的网络请求。可选择对受影响页面进行可访问性/Lighthouse检查。
  5. 生成报告：页面渲染状态✓/✗、控制台状态✓/✗、网络状态✓/✗，并附上截图作为证据。

3. API → Playwright request script

3. API场景 → Playwright请求脚本

Requires Playwright (the kit installer confirms it; else 
pnpm add -D @playwright/test
).
  1. Identify the affected endpoints (method + path) from the diff and any OpenAPI delta.
  2. Write a throwaway script under 
    scripts-dev/
    (e.g. 
    api_smoke.spec.ts
    ) using Playwright's 
    request
    context — NOT a browser:
    ts
    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. Run it with THIS shell's own credentials/env (do not assume-role, do not widen IAM): 
    npx playwright test scripts-dev/api_smoke.spec.ts
    .
  4. Report status codes + shape assertions per endpoint; keep or delete the script per the repo's convention.
需安装Playwright（工具包安装程序会确认是否已安装；若未安装，执行
pnpm add -D @playwright/test
）。
  1. 通过代码差异和OpenAPI变更内容，确定受影响的端点（方法+路径）。
  2. 在
    scripts-dev/
    目录下编写一个临时脚本（如
    api_smoke.spec.ts
    ），使用Playwright的
    request
    上下文——不要使用浏览器：
    ts
    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')      // 或使用.post(...)并传入请求体
  expect(res.status()).toBe(200)
  expect(await res.json()).toMatchObject({ /* 变更规范承诺的响应结构 */ })
})
  3. 使用当前Shell的凭证/环境变量运行脚本（不要切换角色或扩大IAM权限）： 
    npx playwright test scripts-dev/api_smoke.spec.ts
    。
  4. 生成报告：记录每个端点的状态码和结构验证结果；根据仓库约定决定保留或删除该临时脚本。

When in the flow

使用时机

The harness's Validate phase runs the deterministic floor (unit tests + 
openspec --strict
); it does NOT auto-drive a browser or an API. Invoke THIS skill yourself — or have the agent invoke it — after implementing a change, or before approving a PR, to confirm the running surface actually works. It stays a skill (not an automated gate) so the harness remains stack-agnostic.
验证流程的Validate阶段会执行确定性基础验证（单元测试 + 
openspec --strict
）；但不会自动驱动浏览器或API验证。需自行调用本技能——或让Agent调用——在完成变更实现后，或在批准PR之前，确认运行中的界面实际正常工作。本技能作为独立技能（而非自动化验证关卡）存在，以确保验证流程保持堆栈无关性。

Rules

规则

  • Drive the REAL surface; a passing unit suite is not the same as "the page renders" or "the endpoint returns the promised shape".
  • Never widen credentials/IAM to make a check pass — use the session's own environment.
  • Throwaway API scripts live under 
    scripts-dev/
    ; never commit secrets into them.
  • 针对真实界面进行验证；单元测试通过并不等同于“页面渲染正常”或“端点返回承诺的响应结构”。
  • 切勿为了让验证通过而扩大凭证/IAM权限——使用当前会话的环境变量即可。
  • 临时API脚本需存放在
    scripts-dev/
    目录下；切勿在脚本中提交敏感信息。