Polish 指南
入口：
spec-polish·spec-polish· 契约见spec-polish
spec-polish 是浏览器可见 UI 的交互式打磨入口。它会启动或连接 dev server，把页面交给用户实际查看，再根据反馈小步修改。它是 UI 打磨 workflow，适合 polish，不适合替代 code review、QA 或发布验证。
什么时候使用
| 场景 | 推荐 |
|---|---|
| 页面已经能运行，但布局、文案、状态或交互需要打磨 | 使用 polish |
| 用户希望边看页面边反馈“这里再改一下” | 使用 polish |
| 后端、CLI、数据迁移或非 UI 改动 | 不使用，走 work / review |
当前分支是 main / master | 不直接运行，先切到 feature branch |
输入
text
spec-polish
spec-polish 123
spec-polish feature/ui-onboarding可以传当前分支、PR 号或 branch 名称。空参数时使用当前分支。
执行逻辑图
text
用户运行 spec-polish
|
v
确认目标 branch / PR，并拒绝 main 或 master
|
v
读取 .claude/launch.json；没有时自动识别 Rails / Next / Vite / Nuxt / Astro / Remix / SvelteKit / Procfile
|
v
解析 package manager、启动命令和端口
|
+-- dev server 启动失败
| |
| v
| 输出日志尾部和需要用户提供的启动方式
|
+-- 页面可访问
|
v
打开或打印浏览器 URL
|
v
用户浏览页面并提出 polish 反馈
|
v
小步改动、热更新、必要时截图复查
|
v
用户确认完成后再整理验证与提交边界Dev server 识别
source skill 会优先读取 .claude/launch.json，因为这是项目明确给出的启动契约。没有配置时，它按项目类型选择 recipe：
| 类型 | 处理 |
|---|---|
| Rails / Next / Vite / Nuxt / Astro / Remix / SvelteKit | 使用对应 recipe 推导启动命令和默认端口 |
| Procfile | 按 Procfile recipe 启动 |
| unknown | 询问用户如何启动项目 |
Codex 或终端上下文无法自动打开 IDE 浏览器时，会输出 URL 让用户自行打开。
Browser helper 边界
如果需要截图或页面检查，workflow 可使用 agent-browser。如果 helper 不可用，polish loop 不应因此中断；它会说明 helper 缺失，并继续让用户通过浏览器反馈。
要修复浏览器自动化能力，先重新运行当前宿主的 setup：
text
spec-runtime-setup不适合用它做什么
- 不做无头代码审查。
- 不处理生产部署。
- 不替代移动端真机、自动化测试或 QA。
- 不在用户未确认的情况下扩大 UI 范围。
- 不把“看起来更好”当作唯一验收；关键行为仍需测试或截图证据。