skillhub-dev-workflow

Category: Tools & Productivity | Uploader: iflytek | Downloads: 0 | Version: v1.0（Latest）
Use when starting any development task in the SkillHub repository and you need to route work through the correct project-level agents based on what changed.
Changelog: Source: GitHub https://github.com/iflytek/skillhub
Directory Structure

Current level: tree/main/.claude/skills/skillhub-dev-workflow/
📄 SKILL.md 16.0 KB
SKILL.md

---
name: skillhub-dev-workflow
description: Use when starting any development task in the SkillHub repository and you need to route work through the correct project-level agents based on what changed.
---

# SkillHub 开发工作流

## 概述

编排 SkillHub 项目级 agents。分析任务涉及的范围，按顺序激活对应 agent，在完成前强制通过质量门禁。

## Agent 概览

| Agent | 定义文件 | 负责内容 | 触发时机 | 关键产出 |
|---|---|---|---|---|
| `migration-guard` | `.claude/agents/migration-guard.md` | Flyway migration 校验 | 新增/修改 `server/skillhub-app/src/main/resources/db/migration/V*.sql` | 版本号连续性结论、是否误改历史 migration |
| `backend` | `.claude/agents/backend.md` | 后端 Java 实现（Spring Boot / 分层架构 / Flyway） | 修改 `server/**/*.java` 或新增后端能力 | 代码实现、分层合规、API 规范符合性 |
| `api-drift` | `.claude/agents/api-drift.md` | OpenAPI 与前端类型漂移检查 | 修改 Controller（`server/**/controller/**/*.java`）后 | `make generate-api` 执行提示、`schema.d.ts` 是否需提交 |
| `frontend` | `.claude/agents/frontend.md` | 前端 TypeScript/React 实现 | 修改 `web/src/**/*.ts(x)` 或新增前端功能 | 代码实现、i18n 合规、API 层调用合规 |
| `tester` | `.claude/agents/tester.md` | 测试编写与质量门禁执行（重点：Playwright MCP E2E） | 功能实现完成后、准备宣称完成前 | Vitest/SpringBoot/Playwright MCP 验证结果与失败定位 |
| `reviewer` | `.claude/agents/reviewer.md` | 结构化代码审查与合并前验收 | 质量门禁全部通过后 | 带文件路径和行号的审查清单（✅/⚠️/❌） |

## 调度原则

- 按依赖顺序调度：`migration-guard → backend/api-drift → frontend → tester → reviewer`
- `api-drift` 不是独立开发阶段，而是 **Controller 变更后的契约同步检查**
- `tester` 失败后必须回流到对应开发 agent 修复，再次进入质量门禁
- **任何前端修改（`web/src/**/*.ts(x)`）都必须执行 Playwright MCP E2E，不得只用单测替代**
- **E2E 测试必须包含关键步骤截图，保存到 `web/test/screenshots/` 并在报告中引用**
- `reviewer` 只在质量门禁通过后执行，不可前置

## 工作流

```dot
digraph dev_workflow {
    rankdir=TB;

    "分析任务范围" [shape=box];
    "创建开发分支" [shape=box];
    "涉及 DB 表结构变更？" [shape=diamond];
    "migration-guard agent" [shape=box];
    "涉及后端 Java 变更？" [shape=diamond];
    "backend agent 规则" [shape=box];
    "修改了 Controller？" [shape=diamond];
    "api-drift agent" [shape=box];
    "涉及前端 TS 变更？" [shape=diamond];
    "frontend agent 规则" [shape=box];
    "实现功能" [shape=box];
    "tester agent" [shape=box];
    "质量门禁全部通过？" [shape=diamond];
    "定位失败原因" [shape=box];
    "后端问题？" [shape=diamond];
    "前端问题？" [shape=diamond];
    "reviewer agent" [shape=box];
    "完成" [shape=doublecircle];

    "分析任务范围" -> "创建开发分支";
    "创建开发分支" -> "涉及 DB 表结构变更？";
    "涉及 DB 表结构变更？" -> "migration-guard agent" [label="是"];
    "涉及 DB 表结构变更？" -> "涉及后端 Java 变更？" [label="否"];
    "migration-guard agent" -> "涉及后端 Java 变更？";
    "涉及后端 Java 变更？" -> "backend agent 规则" [label="是"];
    "涉及后端 Java 变更？" -> "涉及前端 TS 变更？" [label="否"];
    "backend agent 规则" -> "修改了 Controller？";
    "修改了 Controller？" -> "api-drift agent" [label="是"];
    "修改了 Controller？" -> "涉及前端 TS 变更？" [label="否"];
    "api-drift agent" -> "涉及前端 TS 变更？";
    "涉及前端 TS 变更？" -> "frontend agent 规则" [label="是"];
    "涉及前端 TS 变更？" -> "实现功能" [label="否"];
    "frontend agent 规则" -> "实现功能";
    "实现功能" -> "tester agent";
    "tester agent" -> "Validation 验证";
    "Validation 验证" [shape=box];
    "Validation 验证" -> "验证全部通过？";
    "验证全部通过？" [shape=diamond];
    "验证全部通过？" -> "质量门禁";
    "质量门禁" [shape=box];
    "质量门禁" -> "质量门禁全部通过？";
    "质量门禁全部通过？" -> "定位失败原因" [label="否"];
    "验证全部通过？" -> "定位失败原因" [label="否"];
    "定位失败原因" -> "后端问题？";
    "后端问题？" -> "backend agent 规则" [label="是，重新开发"];
    "后端问题？" -> "前端问题？" [label="否"];
    "前端问题？" -> "frontend agent 规则" [label="是，重新开发"];
    "前端问题？" -> "tester agent" [label="否，其他问题"];
    "质量门禁全部通过？" -> "reviewer agent" [label="是"];
    "reviewer agent" -> "提交 Pull Request";
    "提交 Pull Request" [shape=box];
    "提交 Pull Request" -> "完成";
}
```

## 阶段零 — 创建开发分支

开始任何实现之前,必须从 `main`(或 `develop`)切出一条独立分支:

```bash
git checkout main && git pull
git checkout -b <type>/<short-description>
```

**分支类型映射**:

| 任务类型 | 分支前缀 | 示例 |
|---|---|---|
| 新功能 | `feature/` | `feature/user-skill-export` |
| 缺陷修复 | `fix/` | `fix/login-token-expire` |
| 文档更新 | `docs/` | `docs/api-readme` |
| 重构(无行为变更)| `refactor/` | `refactor/skill-service-layer` |
| 性能优化 | `perf/` | `perf/skill-list-query` |
| 测试补充 | `test/` | `test/skill-controller-cases` |
| CI/构建/配置 | `chore/` | `chore/update-makefile` |

**规则**:
- `short-description` 使用 kebab-case,简洁描述目标(≤ 5 词)
- 禁止直接在 `main` / `develop` 上提交功能代码
- 一个分支对应一个功能/修复,不混用

## 阶段一 — 分析范围

写代码之前,先运行 `git status`,结合任务描述判断变更类型:

| 信号 | 激活的 Agent |
|---|---|
| 新增或修改 `db/migration/V*.sql` | migration-guard |
| 修改 `server/**/*.java` | backend |
| 修改 `server/**/controller/**/*.java` | api-drift(实现后触发) |
| 修改 `web/src/**/*.ts(x)` | frontend |

## 阶段二 — 实现前检查

### DB Migration(migration-guard)
- 新文件版本号必须 = 当前最高版本 + 1,以当前工作树中最高的 `V*.sql` 为准(当前这份工作树已看到 `V39`,下一个应为 `V40+`)
- 确认未修改任何已有 `V*.sql` 文件
- 通过后才能开始实现 schema 变更

### 后端规则(backend agent)
实现过程中遵守:
- 依赖方向:`domain` ← `infra` ← `app`,禁止反向
- Controller 只做传输层,不写业务逻辑
- API 响应统一 `{ code, msg, data, timestamp, requestId }`,`msg` 通过 `LocaleContextHolder` 解析
- 用户 ID 全为 `string`;二进制流接口(`/download`)豁免统一包装

### 前端规则(frontend agent)
实现过程中遵守:
- 禁止手动编辑 `web/src/api/generated/schema.d.ts`
- 禁止硬编码用户可见文案,必须使用 i18n key
- 优先复用 `web/src/shared/ui/` 中已有组件
- 文件名 kebab-case,2 空格缩进,不加分号

## 阶段三 — 实现后检查

### API Drift(api-drift)— 修改了 Controller 时必做
```bash
make generate-api
git diff --name-only HEAD -- web/src/api/generated/schema.d.ts
```
有 diff → 将 `web/src/api/generated/schema.d.ts` 加入本次提交。

## 阶段四 — 测试(tester agent,E2E 优先)

标记任务完成之前必须编写测试:

| 变更类型 | 需要的测试 |
|---|---|
| 前端逻辑 | Vitest 单测,与源文件同目录,kebab-case 命名 |
| 后端 Controller | `@SpringBootTest + @AutoConfigureMockMvc + @MockBean` |
| **任何前端修改** | **Playwright MCP E2E(强制)**,必须包含关键步骤截图 |

### Playwright MCP E2E(重点)

- **触发条件:任何前端修改(`web/src/**/*.ts(x)`)都必须执行 E2E 测试**
- 最低要求:覆盖至少 1 条成功路径 + 1 条失败/边界路径
- 推荐执行流:`browser_navigate` → `browser_snapshot`(定位元素)→ `browser_click`/`browser_fill_form` → `browser_wait_for` → `browser_take_screenshot`
- **截图要求(强制)**:
  - 每个关键步骤必须截图(页面加载、表单填写前、提交后、错误状态等)
  - 截图保存到 `web/test/screenshots/<feature-name>/step-<N>-<description>.png`
  - 文件名必须包含步骤序号和描述,例如:`step-1-login-page.png`、`step-2-form-filled.png`
  - 在测试报告中引用所有截图路径
- 证据沉淀:关键步骤截图保存到 `web/test/screenshots/`,并在结论中附失败定位信息

## 阶段五 — Validation（功能验证）

测试通过后，进入质量门禁前，必须完成以下验证：

### 5.1 功能完整性验证

对照原始需求或 Issue，逐项检查：
- [ ] 所有需求点已实现
- [ ] 边界条件已处理（空值、极限值、异常输入）
- [ ] 错误提示清晰且已国际化
- [ ] 成功/失败路径都已验证

### 5.2 UI/UX 验证（前端变更时必做）

- [ ] 页面布局符合设计稿或现有风格
- [ ] 响应式设计在不同屏幕尺寸下正常
- [ ] 交互反馈及时（loading 状态、禁用状态、hover 效果）
- [ ] 无明显的视觉错位、文字截断、颜色不一致
- [ ] 可访问性基本要求（键盘导航、焦点管理、ARIA 标签）

### 5.3 性能验证

- [ ] 关键操作响应时间 < 2 秒（列表加载、表单提交、页面跳转）
- [ ] 无明显的内存泄漏（长时间操作后检查）
- [ ] 前端包体积无异常增长（`make build` 后检查 bundle size）
- [ ] 后端 API 无 N+1 查询（检查日志中的 SQL 语句数量）

### 5.4 安全验证

- [ ] 无硬编码敏感信息（密钥、token、内部 URL）
- [ ] 用户输入已验证和转义（防 XSS、SQL 注入）
- [ ] 权限检查已到位（前端隐藏 + 后端强制校验）
- [ ] 敏感操作有二次确认（删除、发布等）

### 5.5 验证失败处理

如果任何验证项未通过：
1. **记录问题** — 明确描述问题、复现步骤、预期行为
2. **路由到对应 Agent** — 根据问题类型回到 backend/frontend agent 修复
3. **重新验证** — 修复后重新执行完整的 Validation 流程

**禁止**：
- 跳过验证项直接进入质量门禁
- 在验证未全部通过时标记任务完成
- 降低验证标准以"快速通过"

## 阶段六 — 质量门禁

全部通过后才能进入代码审查:

| 检查项 | 命令 | 通过条件 |
|---|---|---|
| TypeScript 类型检查 | `make typecheck-web` | 0 errors |
| ESLint | `make lint-web` | 0 errors,0 warnings |
| 前端单测 | `make test-frontend` | 全部通过 |
| 后端单测 | `make test-backend-app` | 全部通过(有后端变更时执行) |
| E2E 关键路径回归 | Playwright MCP(`browser_*` 工具链) | 关键路径通过,且截图/日志可追溯 |

### 质量门禁失败处理流程

如果任何检查项未通过,必须:

1. **定位失败原因** — 分析错误日志,确定是后端、前端还是其他问题
2. **路由到对应 Agent 重新开发**:
   - 后端单测失败 / 后端类型错误 → 回到 **backend agent 规则**,重新实现
   - 前端单测失败 / TypeScript 错误 / ESLint 错误 → 回到 **frontend agent 规则**,重新实现
   - Playwright MCP E2E 失败(UI 交互/路由问题)→ 回到 **frontend agent 规则**,必要时联动 **backend agent**
   - 测试本身有问题 → 回到 **tester agent**,修复测试代码
3. **修复后重新执行 Validation + 质量门禁** — 循环直到全部通过

**禁止**:
- 跳过 Validation 或质量门禁检查项直接进入代码审查
- 在 Validation 或质量门禁未全部通过时标记任务完成
- 修改测试代码以绕过真实的代码问题

## 阶段七 — 代码审查(reviewer agent)

按 7 个维度执行 reviewer agent 检查清单:
1. 分层合规(无 `domain → infra` 反向依赖)
2. API 契约(响应结构、LocaleContextHolder、二进制流豁免)
3. API Drift(schema.d.ts 已同步)
4. 前端类型安全(无 `any`,无绕过 api 层直接请求)
5. i18n 合规(无硬编码文案)
6. 测试覆盖(新功能有对应测试)
7. 提交规范(Conventional Commits,作者不含 AI 工具名)

## 阶段八 — 提交 Pull Request

代码审查通过后,使用 gh 创建 PR,PR 描述必须包含以下结构化内容:

### PR 模板结构

```markdown
## 概述
[一句话描述本次变更的目标和动机]

## 变更内容

### 后端实现
- [列出关键的后端变更,包括新增/修改的类、接口、服务层逻辑]
- [DB migration 变更(如有)]
- [API 契约变更(如有)]

### 前端实现
- [列出关键的前端变更,包括新增/修改的组件、页面、路由]
- [状态管理变更(如有)]
- [UI/UX 改进(如有)]

### 测试覆盖
- 后端单测:[列出新增/修改的测试类和覆盖的场景]
- 前端单测:[列出新增/修改的测试文件和覆盖的场景]
- E2E 测试:[列出 Playwright MCP 验证的关键路径,附截图路径]

## 质量门禁

- [ ] `make typecheck-web` 通过(0 errors)
- [ ] `make lint-web` 通过(0 errors, 0 warnings)
- [ ] `make test-frontend` 通过
- [ ] `make test-backend-app` 通过(如有后端变更)
- [ ] Playwright MCP E2E 关键路径通过(如有 UI 交互变更)
- [ ] `make generate-api` 已执行且 `schema.d.ts` 已提交(如有 Controller 变更)

## 安全考虑

- [列出本次变更涉及的安全相关内容,例如:]
  - 鉴权/授权变更
  - 敏感数据处理
  - 输入验证
  - SQL 注入/XSS 防护
  - 依赖项安全更新
- [如无安全相关变更,填写"本次变更不涉及安全敏感内容"]

## 相关 Issue

Closes #[issue_number]
或
Related to #[issue_number]

## 测试说明

### 本地验证步骤
1. [列出 reviewer 需要执行的本地验证步骤]
2. [包括如何启动服务、访问哪些页面、执行哪些操作]
3. [预期结果是什么]

### 回归测试范围
- [列出可能受影响的功能模块]
- [建议的回归测试路径]

### 截图/录屏(如有 UI 变更)
[附上关键页面的截图或操作流程的录屏]
```

### PR 提交检查清单

提交 PR 前必须确认:

| 检查项 | 说明 |
|---|---|
| 分支命名规范 | 符合 `<type>/<short-description>` 格式 |
| Commit 规范 | 所有 commit 符合 Conventional Commits 格式 |
| Commit 作者 | 不包含 AI 工具名称(Claude Code、Codex、Gemini 等)|
| PR 标题 | 简洁明确,格式:`type(scope): description` |
| PR 描述完整 | 包含上述模板的所有必填章节 |
| 质量门禁全通过 | 所有检查项已勾选 ✅ |
| 代码审查已完成 | reviewer agent 检查清单无 ❌ 项 |
| 相关 Issue 已关联 | 使用 `Closes #` 或 `Related to #` |
| 敏感信息已移除 | 无硬编码密钥、token、内部 URL |

### PR 提交命令

```bash
# 方式一:使用 Makefile(推荐)
make pr

# 方式二:手动提交
git push -u origin <branch-name>
gh pr create --title "feat(scope): description" --body "$(cat PR_TEMPLATE.md)"
```

### PR 审查要点

提交后,PR reviewer 将重点关注:

1. **架构合规性** — 分层依赖、模块边界
2. **API 契约一致性** — 响应格式、错误码、i18n
3. **测试充分性** — 覆盖率、边界场景、E2E 关键路径
4. **安全风险** — 注入漏洞、权限绕过、敏感数据泄露
5. **性能影响** — N+1 查询、大对象序列化、前端包体积
6. **可维护性** — 代码可读性、注释必要性、重复代码

## 快速参考 — Agent 调用方式

```
"使用 migration-guard agent"   → DB migration 校验
"使用 backend agent"           → 后端 Java 规则
"使用 frontend agent"          → 前端 TS 规则
"使用 api-drift agent"         → 修改 Controller 后触发
"使用 tester agent"            → 编写测试 + 质量门禁
"使用 reviewer agent"          → 合并前代码审查
```

## 禁止跳过

- **直接在 `main` / `develop` 上提交功能代码,未创建对应类型分支**
- 有 DB 变更时跳过 migration-guard 直接开始实现
- 修改 Controller 后忘记运行 `make generate-api`
- **质量门禁未全部通过就标记任务完成或进入代码审查**
- **质量门禁失败时不定位原因、不回到对应 Agent 重新开发**
- 结尾跳过 reviewer agent
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
skillhub-dev-workflow

Directory Structure

SKILL.md

Report

Notice
