cups-web: Skill for Claude Code

cups-web Dev Flow

按阶段推进 cups-web 的开发任务。维护当前阶段和待确认事项；用户确认后才进入下一阶段。用户提出修正时，留在当前阶段重新整理，不要自行跳过确认点。

触发与范围

• 用户明确说"使用 dev-flow"、$dev-flow，或请求按项目开发流程处理需求、Bug、优化时使用本 skill。
• 输入包含 Issue 引用（如 #123 或完整 URL）时，从 Issue 开始；否则按自由描述收集信息。
• 遵守项目根目录的 AGENTS.md（@AGENTS.md）和 CLAUDE.md。本项目为 cups-web 单仓库，无子模块。

不可跳过的安全规则

• 开始修改前运行 git status --short，识别并保留用户已有改动；禁止 reset、checkout 或覆盖无关改动。
• 只在已确认的 scope 内读写文件。发现需要扩大 scope 时，先说明原因并重新确认。
• 读操作可以自动执行；提交、推送等不可逆操作必须分别获得明确确认。
• 不能验证时如实报告原因和剩余风险，不要用"应该可以"代替验证。

项目速查

项	值
后端	Go 1.26，gorilla/mux，modernc.org/sqlite（纯 Go，无 CGO），goipp
前端	Vue 3.5 + Vite 7，@nuxt/ui v4 + Tailwind CSS v4，hash 路由
数据库	SQLite，WAL + foreign_keys，迁移在 internal/store/store.go::migrate()
构建	make all（前端 dist → Go 二进制），Docker 五阶段构建
入口	cmd/server/main.go，路由注册在同一文件
部署	AIO 容器（cupsd + cups-web 同容器），docker-compose.yml，host 网络
版本	VERSION 环境变量 → ldflags -X main.Version，回退 git describe

阶段一：收集信息

有 Issue 引用

1. 从引用提取 owner、repo 和 number（本项目为单仓库，owner/repo 按实际 remote 判定）。

2. 获取 Issue 正文、评论、标签和状态：

   gh issue view <number> --repo <owner>/<repo> \
     --json title,body,comments,labels,state,url
   

3. 判断类型：Bug、功能需求或优化。

自由描述

先查 AGENTS.md、docs/ 目录和相关代码建立上下文，再只询问缺失且会影响实现的关键信息。

• Bug：复现步骤、平台/版本、期望与实际行为、日志或截图、首次出现版本。
• 需求：使用场景、期望行为、涉及端（前端/后端/容器/Docker）、边界条件、兼容性或性能约束。
• 描述含糊时，先指出已知事实和未知项；不要在需求尚未清楚时开始改代码。

输出一份简短的结构化摘要：

类型：Bug / 功能 / 优化
问题或目标：
复现步骤或典型用例：
影响范围（前端/后端/数据库/容器/Dockerfile/entrypoint）：
已知约束：
待确认事项：

然后暂停并询问：信息是否准确、完整，是否进入方案设计。

阶段二：分析与方案设计

Bug

• 根据描述、日志和代码调用链定位根因；区分已证实事实、推断和待验证假设。
• 检查 AGENTS.md 中的踩坑记录（各类 🚫/⚠️ 标记）和 docs/ 下的深度文档。
• 说明为何现有行为会发生、修复点、回归风险和验证方法。

功能或优化

输出可执行方案，至少包含：

• 期望行为和不在 scope 内的内容
• 涉及的文件：后端（cmd/server/*.go、internal/*）、前端（frontend/src/）、数据库（internal/store/）、容器（Dockerfile、entrypoint.sh、scripts/）
• API 路由和 handler 设计（如新增接口）
• 数据库迁移（幂等 SQL + addColumnIfMissing，见 AGENTS.md 表结构）
• 前端状态、路由、组件和 UI 交互
• 测试策略、兼容性、性能和安全（CSRF、会话、跨源防护、登录限流）
• 需要用户决定的选项