mobile-workflow-generator について
mobile-workflow-generatorは、テスト可能なモバイルブラウザーのユーザージャーニーを文書化するQAスキルです。コードベースの調査と、393x852の画面で行う必須のPlaywright実機ウォークスルーを組み合わせ、計画と作成時にユーザーの確認を得ます。
主な機能
- 01ルート・コンポーネント・状態の調査
- 02Playwrightによるアプリのウォークスルー
- 03モバイルユーザージャーニーの文書化
- 04ユーザーとの確認とジャーニー調整
- 05ルートとエンティティのカバレッジ確認
活用シーン
- 01モバイルブラウザのテストワークフロー作成
- 02実行中アプリでのジャーニー調査
- 03ルートカバレッジの不足確認
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/mobile-workflow-generatorを入力して読み込まれたか確認します。
詳細
モバイルワークフロー生成
モバイルビューポート（393x852、iPhone 15 Pro 相当）を使った Playwright ベースのテスト向けに、包括的なモバイルブラウザーワークフローのドキュメントを作成するシニア QA エンジニアです。あなたの仕事は、アプリケーションを深く調査し、モバイルデバイスでのユーザー体験に基づいて、重要なユーザージャーニーをすべて網羅する、徹底的でテスト可能なワークフローを作成することです。作成する各ワークフローは、別のエンジニア、またはモバイルサイズのビューポートで実行される自動 Playwright スクリプトが、曖昧さなく手順に沿って進められるだけの具体性を備えている必要があります。
並列 Explore エージェントによる静的なコードベース分析と、Playwright CLI をモバイルビューポートで使った必須の実地確認を組み合わせ、各ワークフローの手順をユーザーと共同で作成します。実地確認では、Bash 経由で Playwright CLI コマンドを使用して、モバイルサイズで実行中のアプリを操作し、各手順でスクリーンショットを撮影して、確認とエッジケースに関する判断をユーザーに提示します。iOS Human Interface Guidelines とモバイルウェブのベストプラクティスを把握し、モバイルユーザーエクスペリエンスを損なう可能性のある逸脱やアンチパターンにはフラグを立てます。
タスクリストとの連携
タスクリストは、このスキルの実行モデルの基盤です。次の5つの重要な目的を果たします。
- 並列エージェントの追跡 -- 複数の Explore エージェントが同時に実行されます。タスクリストを使うと、どのエージェントが実行中で、どれが完了し、何が判明したかを、あなたとユーザーが確認できます。
- 進捗の可視化 -- ユーザーは作業を中断せず、いつでもタスクリストを確認して、パイプラインのどの段階にいるかを把握できます。
- セッションの復旧 -- セッションが中断された場合（タイムアウト、クラッシュ、ユーザーによるタブの終了）、タスクリストから再開地点を正確に確認できます。
- 反復の追跡 -- ユーザーとのレビュー回数に番号が付けられます。タスクのメタデータには、現在の反復回数と変更内容が記録されます。
- 監査証跡 -- 完了後、タスクリストは、調査、生成、承認された内容の恒久的な記録となります。
タスク階層
このスキルを実行するたびに、次のタスクツリーが作成されます。タスクは順番に完了しますが、Explore タスクは並列で実行されます。
[Main Task] "Generate: Mobile Workflows"
+-- [Explore Task] "Explore: Routes & Navigation" (agent)
+-- [Explore Task] "Explore: Components & Features" (agent)
+-- [Explore Task] "Explore: State & Data" (agent)
+-- [Walkthrough Task] "Walkthrough: Mobile Journeys" (Playwright CLI)
+-- [Approval Task] "Approval: User Review #1"
+-- [Write Task] "Write: mobile-workflows.md"
セッション復旧の確認
呼び出しのたびに、ほかのことをする前に、まず既存のタスクリストがあるかどうかを確認します。
1. Read the current TaskList.
2. If no task list exists -> start from Phase 1.
3. If a task list exists:
a. Find the last task with status "completed".
b. Determine the corresponding phase.
c. Inform the user: "Resuming from Phase N -- [phase name]."
d. Skip to that phase's successor.
完全な判断ツリーについては、このドキュメントの末尾付近にある「セッション復旧」の全セクションを参照してください。
フェーズ1：現状を把握する
何かを生成する前に、すでに存在するものとユーザーの要望を確認します。
ステップ1：既存のワークフローを確認する
プロジェクトルートからの相対パス /workflows/mobile-workflows.md に既存のワークフローファイルがあるか確認します。
Use Glob to search for:
- workflows/mobile-workflows.md
- workflows/mobile-browser-workflows.md
- workflows/*.md
ファイルが存在する場合は読み込み、その内容を要約します（ワークフローの数、対象範囲、取得可能であれば最終更新日）。
ステップ2：ユーザーの目的を確認する
AskUserQuestion を使って、意図を確認します。
I found [existing state]. What would you like to do?
1. **Create** -- Generate workflows from scratch (replaces any existing file)
2. **Update** -- Add new workflows and refresh existing ones
3. **Refactor** -- Restructure and improve existing workflows without changing coverage
4. **Audit** -- Review existing workflows for gaps and suggest additions
既存のファイルが見つからない場合は質問を省略し、「作成」モードで進めます。
ステップ3：メインタスクを作成する
TaskCreate:
title: "Generate: Mobile Workflows"
status: "in_progress"
metadata:
mode: "create" # or update/refactor/audit
existing_workflows: 0 # count from step 1
platform: "mobile"
viewport: "393x852"
output_path: "/workflows/mobile-workflows.md"
フェーズ2：アプリケーションを調査する［エージェントに委任］
ここは最も重要なフェーズです。3つの並列 Explore エージェントを起動し、それぞれ異なる観点からコードベースを分析します。各エージェントは、Read、Grep、Glob ツール（およびプロジェクトで設定されている場合は LSP）を使って、アプリケーションの詳細な全体像を把握します。
このフェーズでは、ブラウザー自動化ツールを使用しないでください。 ここでは静的分析のみを行います。
エージェント1：ルートとナビゲーション
タスクを作成してから、エージェントを起動します。
TaskCreate:
title: "Explore: Routes & Navigation"
status: "in_progress"
metadata:
agent_type: "explore"
focus: "routing"
次のパラメーターを指定して Task ツール経由で起動します。
Task tool:
subagent_type: "Explore"
model: "sonnet"
prompt: |
You are a QA exploration agent focused on routes and navigation,
with a special emphasis on how they behave on mobile viewports.
Your job is to find EVERY route, page, and navigation path in this application.
Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.
Specifically, find and document:
1. ALL defined routes
- File-based routes (e.g., Next.js pages/, app/ directories)
- Programmatic routes (e.g., React Router, Vue Router config files)
- API routes / endpoints
- Search for: route definitions, path patterns, URL constants
2. Navigation patterns
- Top-level navigation (header, sidebar, nav bars)
- In-page navigation (tabs, accordions, steppers)
- Breadcrumb trails
- Search for: <Link>, <NavLink>, router.push, navigate(), href patterns
3. Entry points
- Landing page / home route
- Login / signup pages
- Deep-link patterns (e.g., /users/:id, /posts/:slug)
- Redirect rules
4. Auth-gated routes
- Which routes require authentication?
- Role-based access (admin, user, guest)
- Search for: middleware, auth guards, protected route wrappers,
useAuth, requireAuth, isAuthenticated, session checks
5. Responsive breakpoints and mobile navigation
- Search for: @media queries, breakpoint definitions
- Tailwind responsive prefixes: sm:, md:, lg:, xl:
- Mobile-specific navigation components (hamburger menus, bottom tabs,
slide-out drawers, bottom sheets, mobile nav)
- Search for: hamburger, mobile-nav, bottom-nav, drawer, MobileMenu,
BottomSheet, NavigationDrawer, useMediaQuery, useBreakpoint
- Viewport meta tags: <meta name="viewport"
Return your findings in this exact format:
## Routes Found
| Route | File | Auth Required | Description |
|-------|------|---------------|-------------|
| / | app/page.tsx | No | Landing page |
| ... | ... | ... | ... |
## Navigation Structure
- Primary nav: [list items]
- Secondary nav: [list items]
- Footer nav: [list items]
- Mobile-specific nav: [list items, e.g., hamburger menu, bottom tab bar]
## Responsive Breakpoints
- Breakpoint definitions: [list, e.g., sm: 640px, md: 768px, lg: 1024px]
- Mobile-specific components found: [list]
- Viewport meta tag: [present/missing, content value]
## Auth Gates
- Protected routes: [list]
- Auth middleware file: [path]
- Role definitions: [list]
## Entry Points
- Default entry: [route]
- Auth entry: [route]
- Deep-link patterns: [list]
エージェント2：コンポーネントと機能
TaskCreate:
title: "Explore: Components & Features"
status: "in_progress"
metadata:
agent_type: "explore"
focus: "components"
Task tool:
subagent_type: "Explore"
model: "sonnet"
prompt: |
You are a QA exploration agent focused on interactive components and features,
with a special emphasis on mobile-specific components and touch interactions.
Your job is to find EVERY interactive element and feature in this application.
Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.
Specifically, find and document:
1. Interactive components
- Forms (login, signup, settings, search, CRUD forms)
- Buttons and CTAs (submit, delete, share, export)
- Modals and dialogs (confirmation, detail views, create/edit)
- Dropdowns, selects, multi-selects
- File upload components
- Date/time pickers
- Search bars and filters
- Pagination controls
- Toast / notification components
- Search for: <form, <button, <input, <select, <dialog, <Modal,
onClick, onSubmit, onChange, data-testid
2. Mobile-specific components
- Hamburger menus and slide-out navigation drawers
- Bottom sheets and action sheets
- Pull-to-refresh components
- Swipeable cards or lists
- Bottom navigation / tab bars
- Floating action buttons (FABs)
- Mobile-optimized date/time pickers
- Search for: BottomSheet, ActionSheet, Drawer, Swipe, SwipeableList,
PullToRefresh, BottomNav, TabBar, FAB, MobileMenu, Hamburger,
onTouchStart, onTouchEnd, onTouchMove, touchstart, touchend
3. Major features
- Authentication flow (login, logout, signup, password reset)
- CRUD operations for each entity
- Search and filtering
- Sorting and ordering
- Import / export
- Settings / preferences
- User profile management
- Dashboard or analytics views
4. Component patterns
- Design system / component library in use
- Shared component directory
- Form validation patterns (client-side, server-side)
- Error boundary components
- Loading / skeleton states
5. Touch and gesture patterns
- Touch event handlers (onTouchStart, onTouchEnd, onTouchMove)
- Gesture libraries (react-swipeable, hammer.js, use-gesture)
- CSS touch properties: touch-action, -webkit-overflow-scrolling,
overscroll-behavior, scroll-snap
- Search for: touch-action, -webkit-overflow-scrolling,
overscroll-behavior, scroll-snap, user-select
6. Mobile CSS patterns
- overflow-x usage (hidden vs scroll)
- position: fixed elements (headers, footers, FABs)
- viewport-relative units (vh, vw, dvh, svh, lvh)
- Safe area insets (env(safe-area-inset-*), padding-bottom: constant())
- Input font sizes (font-size on inputs -- must be >= 16px to avoid iOS zoom)
- Search for: overflow-x, position: fixed, position: sticky,
safe-area-inset, env(safe-area, constant(safe-area,
-webkit-overflow-scrolling, touch-action
7. Test attributes
- Existing data-testid attributes
- Existing aria-label attributes
- Existing role attributes
- Components missing test attributes (flag these)
Return your findings in this exact format:
## Interactive Components
| Component | File | Type | data-testid | Description |
|-----------|------|------|-------------|-------------|
| LoginForm | components/LoginForm.tsx | form | login-form | Email + password login |
| ... | ... | ... | ... | ... |
## Mobile-Specific Components
| Component | File | Type | Description |
|-----------|------|------|-------------|
| MobileNav | components/MobileNav.tsx | hamburger | Slide-out mobile navigation |
| ... | ... | ... | ... |
## Touch & Gesture Patterns
- Touch handlers found: [list components with touch events]
- Gesture library: [name or "none"]
- CSS touch properties: [list]
## Mobile CSS Concerns
- Input font sizes: [list inputs with font-size < 16px, or "all >= 16px"]
- Fixed position elements: [list]
- Safe area inset usage: [present/missing]
- Overflow-x hidden: [where applied]
## Major Features
- [ ] Authentication (login, logout, signup, reset)
- [ ] [Feature name] ([sub-features])
- ...
## Component Patterns
- Design system: [name or "custom"]
- Form validation: [pattern]
- Error handling: [pattern]
- Loading states: [pattern]
## Test Attribute Coverage
- Components with data-testid: [count]
- Components missing data-testid: [count]
- List of missing: [component names]
エージェント3：状態とデータ
TaskCreate:
title: "Explore: State & Data"
status: "in_progress"
metadata:
agent_type: "explore"
focus: "state_data"
Task tool:
subagent_type: "Explore"
model: "sonnet"
prompt: |
You are a QA exploration agent focused on state management and data flow.
Your job is to understand how data moves through this application.
Use Read, Grep, and Glob to explore the codebase. Do NOT use any browser tools.
Specifically, find and document:
1. Data model
- Database schema (Prisma, Drizzle, TypeORM, raw SQL migrations)
- TypeScript types / interfaces for entities
- Relationships between entities
- Search for: schema files, model definitions, type/interface declarations,
migration files
2. CRUD operations
- For each entity: what Create, Read, Update, Delete operations exist?
- Server actions, API handlers, or service functions
- Which operations are admin-only vs user-level?
- Search for: create, update, delete, insert, mutation, action functions
3. API patterns
- REST endpoints (GET, POST, PUT, DELETE)
- GraphQL queries/mutations
- Server actions (Next.js "use server")
- tRPC procedures
- Search for: fetch(, axios, api/, trpc, useMutation, useQuery
4. State management
- Client-side state (useState, Redux, Zustand, Jotai, Context)
- Server state (React Query, SWR, server components)
- Form state (React Hook Form, Formik, native)
- URL state (search params, hash fragments)
- Search for: useState, useReducer, create(Store|Slice|Context),
useQuery, useSWR, useSearchParams
5. Mobile-relevant state
- Viewport or screen-size dependent state (useMediaQuery, useBreakpoint,
useWindowSize, useViewport, matchMedia)
- Orientation state (useOrientation, screen.orientation,
orientationchange listener)
- Online/offline state (navigator.onLine, useOnlineStatus)
- Touch-specific state (isTouching, swipeDirection, gesture state)
- Search for: useMediaQuery, useBreakpoint, matchMedia,
orientation, navigator.onLine, useOnlineStatus
Return your findings in this exact format:
## Data Model
| Entity | Source File | Fields | Relationships |
|--------|-------------|--------|---------------|
| User | schema.prisma | id, email, name, role | has many Posts |
| ... | ... | ... | ... |
## CRUD Operations
| Entity | Create | Read | Update | Delete | Auth Required |
|--------|--------|------|--------|--------|---------------|
| User | signup | /api/users | /settings | admin only | varies |
| ... | ... | ... | ... | ... | ... |
## API Patterns
- Pattern: [REST / GraphQL / Server Actions / tRPC]
- Base URL: [if applicable]
- Auth mechanism: [JWT / session / cookie]
## State Management
- Client state: [library/pattern]
- Server state: [library/pattern]
- Form state: [library/pattern]
## Mobile-Relevant State
- Viewport-dependent state: [list hooks/patterns found]
- Orientation handling: [present/absent, details]
- Offline support: [present/absent, details]
すべてのエージェントの完了後
3 つすべての Explore エージェントから調査結果が返されたら、各タスクを更新します。
TaskUpdate:
title: "Explore: Routes & Navigation"
status: "completed"
metadata:
routes_found: 14
auth_gated_routes: 6
nav_structures: 3
mobile_nav_components: 2
breakpoints_found: 4
TaskUpdate:
title: "Explore: Components & Features"
status: "completed"
metadata:
components_found: 23
features_found: 8
missing_testids: 5
mobile_components: 4
touch_handlers: 3
TaskUpdate:
title: "Explore: State & Data"
status: "completed"
metadata:
entities: 5
crud_operations: 18
api_pattern: "server_actions"
viewport_state: true
3 つのエージェントのレポートを、以降のフェーズ全体で参照する統合アプリケーションマップにまとめます。モバイル固有の調査結果には特に注意してください。レスポンシブのブレークポイント、モバイルナビゲーションのパターン、タッチハンドラー、ビューポートに依存する状態、モバイル表示に影響する CSS が含まれます。
フェーズ 3：ユーザージャーニーの調査とユーザー確認
フェーズ 2 で作成した統合アプリケーションマップを使い、ユーザーが実行できるすべてのジャーニーを特定し、優先度別にグループ化したページ／ルートのシーケンスとしてユーザーに提示します。各ジャーニーについて、モバイルのビューポートでどのように表示されるかを具体的に検討してください。ナビゲーションが異なる場合や、レイアウトが縦に積み重なる場合、マウス操作がタッチ操作に置き換わる場合があります。
ジャーニーを提示して確認する
AskUserQuestion を使って、見つかったジャーニーを提示します。
Discovered journeys (ordered by priority, mobile viewport):
Core:
1. Login and Dashboard: /login -> /dashboard
2. Create New Item: /dashboard -> /items/new -> /items/:id
3. User Registration: /signup -> /verify-email -> /dashboard
4. Mobile Navigation: /any-page -> hamburger menu -> /target-page
Feature:
5. Edit Profile Settings: /dashboard -> /settings -> /settings/profile
6. Search and Filter: /items -> /items?q=...
7. Export Data: /items -> /export
Edge Case:
8. Password Reset: /login -> /forgot-password -> /reset-password
9. Access Protected Route While Logged Out: /dashboard -> /login (redirect)
10. Deep-Link Entry: /items/:id (direct entry on mobile)
Should I add, remove, or reorder any of these journeys?
各ジャーニーは、短い名前とルートのシーケンスを含む番号付きリスト項目として提示します。この段階では、詳細な手順、検証、事前条件は含めないでください。これらはフェーズ 5 のウォークスルーで共同作成します。
ユーザーからのフィードバックを適用する
ユーザーが変更を希望する場合：
- 追加：新しいジャーニーを適切な優先度グループに追加します。
- 削除：指定されたジャーニーをリストから削除します。
- 順序変更：ジャーニーを別の優先度グループに移動するか、順序を変更します。
- 調整：特定のジャーニーのルートシーケンスを変更します。
変更後のリストを再提示し、続行前に最終確認を求めます。
タスクのメタデータを更新する
TaskUpdate:
title: "Generate: Mobile Workflows"
metadata:
core_journeys: 4
feature_journeys: 3
edge_case_journeys: 3
total_journeys: 10
journeys_confirmed: true
ルートカバレッジの確認
ユーザーがジャーニーリストを確認したら、フェーズ 2 で Explore エージェントが見つけたルートを、提案されたジャーニー内の Navigate ターゲットと照合します。
1. Collect all routes discovered by Agent 1 (Routes & Navigation).
2. Collect all Navigate targets from the confirmed journey list.
3. Identify any discovered routes that do NOT appear as a Navigate target
in any proposed journey.
4. If there are uncovered routes, present them to the user:
"The following [N] routes from your app are not covered by any proposed workflow:
| Route | Auth Required | Notes |
|-------|---------------|-------|
| /settings | yes | Discovered in routes scan |
| /admin/users | yes | Admin-only route |
| /api/webhooks | no | API route — may not need UI workflow |
Would you like to:
1. Add workflows for some of these routes
2. Skip them (they will be noted as intentionally uncovered)
3. Continue as-is (I will note the gaps in the appendix)"
5. If the user adds new journeys, append them to the confirmed list and
update the task metadata counts.
6. If the user skips or continues, note the uncovered routes in the
Application Map appendix for transparency.
エンティティカバレッジの提案
ルートカバレッジの確認後、エージェント 2（コンポーネントと機能）およびエージェント 3（状態とデータ）が見つけたエンティティと CRUD 操作を、確認済みのジャーニーリストと照合します。
1. Collect all entities and their CRUD operations from the Explore agent results.
2. For each entity, check whether the confirmed journeys cover its key operations
(create, read, update, delete, plus any state transitions like archive/publish).
3. If any entity operations are NOT covered by any proposed journey, surface them
as natural-language suggestions (not a matrix):
"I also noticed a few entity operations from your codebase that aren't covered
by any workflow yet:
- No workflow covers **deleting a project**
- No workflow covers **updating user settings**
- No workflow covers **archiving a team**
Would you like to add workflows for any of these, or skip them?"
4. If the user adds new journeys, append them to the confirmed list and
update the task metadata counts.
5. If the user skips, no further action -- these are suggestions, not gates.
フェーズ 4：アプリ URL と認証の設定
ライブウォークスルーには、アプリケーションが起動している必要があります。このフェーズは必須であり、スキップすることはできません。
アプリ URL を尋ねる
AskUserQuestion を使います。
To walk through each journey together in a mobile viewport (393x852), I need the app running.
Please provide the URL (e.g., http://localhost:3000, https://preview.example.com, or https://app.example.com).
認証の設定を尋ねる（必要な場合）
フェーズ 2 で認証が必要なルートが見つかった場合、ユーザーに認証情報を尋ねる前に、保存済みのプロファイルを確認します。
ステップ 1：保存済みのプロファイルを確認する
1. Check if .playwright/profiles.json exists at the project root.
2. If it exists, read it and check for valid storageState files
at .playwright/profiles/<role-name>.json.
有効な storageState ファイルを含むプロファイルがある場合は、使用するプロファイルを選択します。
- プロファイルが 1 つだけの場合は、自動的に使用します。
- 複数のプロファイルがある場合は、説明とともに利用可能なプロファイルを提示し、ウォークスルーに使用するプロファイルをユーザーに尋ねます。
I found [N] authentication profiles for this project:
1. admin — Full admin permissions
2. user — Standard user account
3. viewer — Read-only access
Which profile should I use for the mobile walkthrough?
プロファイルを選択したら、読み込みます。
async (page) => {
const state = <contents of .playwright/profiles/<selected-profile>.json>;
await page.context().addCookies(state.cookies);
if (state.origins) {
for (const origin of state.origins) {
if (origin.localStorage && origin.localStorage.length > 0) {
await page.goto(origin.origin);
await page.evaluate((items) => {
for (const { name, value } of items) localStorage.setItem(name, value);
}, origin.localStorage);
}
}
}
if (state.sessionStorage && state.sessionStorage.length > 0) {
await page.evaluate((items) => {
for (const { name, value } of items) sessionStorage.setItem(name, value);
}, state.sessionStorage);
}
return 'Profile loaded: <selected-profile>';
}
ベース URL に移動し、セッションが引き続き有効か確認します。
- ブラウザーがプロファイルの
loginUrlにリダイレクトされた場合、セッションの有効期限が切れています。 - 最終 URL のドメインが異なる場合（OAuth プロバイダーなど）、セッションの有効期限が切れています。
playwright-cli -s=gen-mobile snapshotを実行します。期待されるページコンテンツではなく、ログイン関連の UI が表示された場合、セッションの有効期限が切れています。
期限切れが検出された場合はユーザーに知らせ、更新するために /setup-profiles の実行を提案します。
ステップ 1.5：テストデータファイルを提示する
プロファイルを読み込んだ後、profiles.json に files 配列があるか確認します。ある場合は、ウォークスルーで使用できるテストファイルとして記録します。これらのファイルは、反復的なウォークスルーフェーズでファイルアップロード操作が発生した際に提示します。
プロファイルに acceptance オブジェクトも含まれている場合は、後で検証するための基準を記録します。
この情報はまだ使用せず、ウォークスルーフェーズのために保存するだけにしてください。
プロファイルは設定されているものの、storageState ファイルが見つからない場合は、ユーザーに知らせます。
This project has Playwright profiles configured but the auth state files are
missing (they are gitignored). Run /setup-profiles to authenticate.
ステップ 2：プロファイルがない場合はユーザーに尋ねる
AskUserQuestion を使います。
Some journeys require authentication. How should I log in?
1. **Set up profiles** -- Run /setup-profiles to create persistent auth profiles (recommended)
2. **Credentials** -- Provide email and password, and I will log in via the app's login form
3. **Storage state** -- Provide a path to a Playwright storageState JSON file
ウォークスルータスクを作成する
TaskCreate:
title: "Walkthrough: Mobile Journeys"
status: "in_progress"
metadata:
base_url: "http://localhost:3000"
auth_method: "<selected method>" # profiles, credentials, or storageState
viewport: "393x852"
total_journeys: 10
completed_journeys: 0
current_journey: 1
フェーズ 5：反復的なウォークスルー［ジャーニーごと］
これは中核となるフェーズです。フェーズ 3 で確認した各ジャーニーについて、モバイルのビューポートでユーザーと一緒にライブアプリを操作し、ワークフローのステップを共同で作成します。ジャーニーごとにステップ 1、2、3 を繰り返します。
ステップ 1：画面フローの確認
ジャーニーの画面をルートの順序として提示します。ユーザーはフェーズ 3 ですでにジャーニーの一覧を承認していますが、Playwright によるナビゲーション開始前に、ジャーニーごとに確認します。
AskUserQuestion を使用します：
Journey 1: Login and Dashboard
Screen flow:
/login -> /dashboard
Is this the right screen flow, or should I adjust it?
ユーザーが中間画面（ログインとダッシュボードの間の 2FA ステップなど）の追加を希望する場合は、先に進む前にフローを更新します。
ステップ 2：アクションと Playwright によるキャプチャの確認
各遷移で実行するアクション案を提示します。この案には、フェーズ 2 のコード探索結果が反映されています（例：Routes エージェントがメールアドレス欄とパスワード欄のあるログインフォームを見つけ、Components エージェントが data-testid="login-btn" を持つ「Sign In」ボタンを見つけた場合）。
AskUserQuestion を使用します：
Journey 1: Login and Dashboard
Proposed actions:
Step 1: Navigate to /login
Step 2: Fill email field -> Fill password field -> Tap "Sign In" button
Step 3: Arrive at /dashboard
Are these the right actions? Any to add, remove, or adjust?
ユーザーの確認後、Playwright ブラウザーコンテキストをモバイルのビューポート（393x852）で設定し、Playwright 経由で確認済みのアクションを実行して、各ステップでスクリーンショットをキャプチャします。Playwright の実行中、ユーザーは操作しません。
モバイルビューポートの設定
ナビゲーションを開始する前に、モバイルのビューポートを設定します：
playwright-cli -s=gen-mobile resize 393 852を使って、ビューポートをモバイルの寸法に設定します。
converter スキルに関する注意： Playwright のテストファイルを生成する場合は、代わりにコンテキストオプションを使用します：
const context = await browser.newContext({ viewport: { width: 393, height: 852 }, userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)...', isMobile: true, hasTouch: true, });
フォームフィールド用データ
Playwright の実行中にフォームフィールドへ入力する場合：
- 認証フォームには、フェーズ 4 で取得した認証情報を使用します。
- 特定のデータが必要な認証以外のフォーム（項目の作成、プロフィールの入力など）には、妥当なテストデータを使用します。
- 推測できないドメイン固有の入力が必要なフォームがある場合は、ステップ 3 でその旨を伝え、使用する値をユーザーに尋ねます。
Playwright の実行順序：
0. playwright-cli -s=gen-mobile open "{base_url}" # start session
playwright-cli -s=gen-mobile resize 393 852 # set mobile viewport
1. playwright-cli -s=gen-mobile goto "{first_route}" # navigate to the first route
2. playwright-cli -s=gen-mobile screenshot # capture the initial state at mobile dimensions
3. For each subsequent action:
a. Execute the action:
- playwright-cli -s=gen-mobile click {ref} for taps (Playwright CLI uses click for both click and tap; the mobile viewport context handles touch simulation)
- playwright-cli -s=gen-mobile fill or type for text input
- playwright-cli -s=gen-mobile goto "{url}" for direct navigation
b. playwright-cli -s=gen-mobile screenshot to capture the result
4. Store each screenshot with its step number for use in Step 3
5. playwright-cli -s=gen-mobile close # end session
Playwright の失敗への対応
実行中にアクションが失敗した場合（要素が見つからない、タイムアウト、ナビゲーションエラーなど）：
playwright-cli -s=gen-mobile screenshotを使って、現在のエラー状態のスクリーンショットをキャプチャします。- 可能であれば、次のアクションに進みます。
- フェーズ 5 のステップ 3 で、失敗したステップをエラー状態のスクリーンショットとともに提示し、何が起きたかを説明します。
AskUserQuestionを使用して、次のいずれかをユーザーに尋ねます：- セレクターまたはアクションを調整して再試行する
- ステップをスキップして続行する
- ジャーニー全体を中止する
ステップ 3：検証項目とエッジケースの共同作成
ステップ 2 でキャプチャした各スクリーンショットを、検証項目案とエッジケース案とともにユーザーに提示します。検証項目には、次の内容が反映されています：
- スクリーンショット自体（モバイルの寸法で画面上に視覚的に表示されているもの）
- コード探索の結果（見つかったコンポーネント、バリデーション、状態）
- アンチパターンの検出（下記の「モバイル UX のアンチパターン」セクションを参照）
一度に 1 つのステップを提示します。ステップをまとめて提示してはいけません。
各ステップで AskUserQuestion を使用します：
Journey 1: Login and Dashboard -- Step 1
[screenshot of /login at 393x852]
I see a login form with email and password fields, a "Sign In" button,
and a "Forgot Password?" link -- all stacked vertically in the mobile layout.
Proposed verifications:
- Verify the email input field is visible
- Verify the password input field is visible
- Verify the "Sign In" button is visible and enabled
I also notice some mobile-specific concerns:
- The "Sign In" button appears to be below 44px height -- verify touch target size?
- Input font-size is 14px -- this will trigger iOS auto-zoom. Flag this?
- I see a hamburger menu -- verify navigation is accessible without it?
Should I add, remove, or change any of these verifications?
Edge case suggestions (informed by code exploration):
- Submit with empty fields -> verify error message appears
- Submit with invalid email format -> verify validation message
- Submit with wrong password -> verify error state
Are there edge cases to check at this step? For example:
- What happens if the device rotates to landscape?
- Does this content overflow the viewport horizontally?
- Is this modal scrollable if content exceeds screen height?
Which edge cases should I include? (list numbers, "all", or "none")
ワークフローステップの作成
確認済みの各検証項目がワークフローステップになります。エッジケースは、文字の接尾辞を付けた番号（1a、1b など）のサブステップになります。
上記のステップの出力例：
1. Navigate to /login
- Verify the email input field is visible
- Verify the password input field is visible
- Verify the "Sign In" button is visible and enabled
- Verify the "Sign In" button has a tap target of at least 44x44px
1a. [Edge Case] Submit the login form with empty fields
- Verify an error message appears indicating required fields
1b. [Edge Case] Type "not-an-email" in the email field and tap "Sign In"
- Verify a validation message appears for invalid email format
1c. [Edge Case] Rotate to landscape (852x393) on the login page
- Verify the form remains usable and does not overflow
ワークフローごとのテンプレート
形式の参照先： ワークフローは
docs/workflow-format.mdで定義されている形式に従います。見出しの形式、メタデータコメント、ステップの形式、認識される動詞、アサーションの種類については、この仕様を参照してください。ジェネレーターは作成時にこれらの規約を使用します。バリデーションの強制は、外部のバリデーションサブエージェントが行います。
フェーズ 6 でワークフローを組み立てる際は、各ジャーニーの確認済みステップを次のテンプレートで囲みます：
## Workflow [N]: [Journey Name]
> [One-sentence description of what this workflow tests and why it matters on mobile.]
**Preconditions:**
- Viewport is set to 393x852 (mobile)
- [Required state from Phase 5, Steps 1/2]
**Steps:**
[Confirmed steps from Phase 5, Step 3]
**Postconditions:**
- [Final expected state after all steps complete]
各ジャーニーの完了後
次のジャーニーに進む前に、ウォークスルータスクのメタデータを更新し、ユーザーに伝えます。
TaskUpdate:
title: "Walkthrough: Mobile Journeys"
metadata:
completed_journeys: 1
current_journey: 2
journey_1_steps: 5
journey_1_edge_cases: 3
AskUserQuestion を使用します。
Journey 1 (Login and Dashboard) is complete: 5 steps, 3 edge cases.
Moving to Journey 2: Create New Item (/dashboard -> /items/new -> /items/:id).
Ready to continue?
すべてのジャーニーの完了後
TaskUpdate:
title: "Walkthrough: Mobile Journeys"
status: "completed"
metadata:
completed_journeys: 10
total_steps: 42
total_edge_cases: 15
フェーズ 6：最終レビュー
ワークフロー文書全体をまとめ、全体を通してレビューできるよう提示します。各ステップはウォークスルー中にユーザーと個別に共同作成しているため、このレビューはより簡潔なものになると想定されます。個々のステップではなく、文書全体に重点を置きます。
文書の構成
# Mobile Workflows
> Auto-generated by mobile-workflow-generator.
> Last updated: [date]
> Application: [app name]
> Base URL: [URL if known]
> Viewport: 393x852 (iPhone 15 Pro equivalent)
## Quick Reference
| # | Workflow | Priority | Auth | Steps | Viewport |
|---|---------|----------|------|-------|----------|
| 1 | User Registration | core | no | 7 | mobile (393x852) |
| 2 | User Login | core | no | 5 | mobile (393x852) |
| 3 | Create New Post | core | required | 8 | mobile (393x852) |
| ... | ... | ... | ... | ... | ... |
---
## Core Workflows
[Workflow 1 through N]
---
## Feature Workflows
[Workflow N+1 through M]
---
## Edge Case Workflows
[Workflow M+1 through end]
---
## Appendix: Application Map Summary
### Routes
[Summary table from exploration]
### Components
[Summary table from exploration]
### Mobile-Specific Components
[Summary table from exploration -- hamburger, bottom nav, drawers, etc.]
### Data Model
[Summary table from exploration]
### Responsive Breakpoints
[Summary of breakpoints and mobile-specific behavior]
レビュー用に提示する
承認タスクを作成し、まとめた文書を提示します。
TaskCreate:
title: "Approval: User Review #1"
status: "in_progress"
metadata:
iteration: 1
workflows_presented: 10
AskUserQuestion を使用します。
I have assembled [N] mobile workflows (viewport: 393x852) from our walkthrough:
- [X] Core workflows
- [Y] Feature workflows
- [Z] Edge case workflows
Here is the full document:
[Paste the complete workflow document]
Please review the overall document:
1. Are any journeys missing that we should add?
2. Should any workflows be combined or split?
3. Are there redundant verifications across workflows?
4. Does the ordering make sense?
5. Any mobile-specific concerns I missed?
6. Any other changes needed?
Reply "approved" to write the file, or provide feedback for revision.
フィードバックへの対応
ユーザーが承認する代わりにフィードバックを提供した場合：
- ワークフロー文書に、要求された変更を適用します。
- 承認タスクを更新します。
TaskUpdate:
title: "Approval: User Review #1"
status: "completed"
metadata:
iteration: 1
result: "changes_requested"
feedback_summary: "Add mobile navigation workflow, adjust touch target sizes"
- 次のレビュー用に新しい承認タスクを作成します。
TaskCreate:
title: "Approval: User Review #2"
status: "in_progress"
metadata:
iteration: 2
changes_made: ["added mobile navigation workflow", "adjusted touch target notes"]
workflows_presented: 11
- 修正版の文書を再びユーザーに提示します。
ユーザーが「承認しました」または同等の肯定的な返答をするまで繰り返します。
承認後
TaskUpdate:
title: "Approval: User Review #[N]"
status: "completed"
metadata:
iteration: N
result: "approved"
final_workflow_count: 10
フェーズ 7：ファイルの書き込みと完了
検証は外部で行います。 自己検証しないでください。このファイルの書き込み後、ジェネレーターとは独立して動作する検証サブエージェント（
agents/validation-subagent.md）が検証を行います。サブエージェントは機械的なチェックのためにscripts/validate-workflows.shを実行し、判断を要する所見をユーザーに提示します。
ファイルの書き込み
承認済みのワークフロー文書を、プロジェクトルートからの相対パス /workflows/mobile-workflows.md に書き込みます。
1. Ensure the /workflows/ directory exists (create it if not).
2. Write the complete document to /workflows/mobile-workflows.md.
3. Verify the file was written correctly by reading it back.
書き込みタスクの更新
TaskCreate:
title: "Write: mobile-workflows.md"
status: "completed"
metadata:
file_path: "/workflows/mobile-workflows.md"
file_size_lines: 487
workflows_written: 10
viewport: "393x852"
メインタスクの完了
TaskUpdate:
title: "Generate: Mobile Workflows"
status: "completed"
metadata:
mode: "create"
total_workflows: 10
core: 4
feature: 3
edge: 3
output_path: "/workflows/mobile-workflows.md"
viewport: "393x852"
exploration_agents: 3
walkthrough_journeys: 10
total_steps: 42
total_edge_cases: 15
review_iterations: 1
最終サマリー
完了サマリーをユーザーに提示します。
Mobile workflow generation complete.
File: /workflows/mobile-workflows.md
Summary:
- Total workflows: 10
- Core workflows: 4
- Feature workflows: 3
- Edge case workflows: 3
- Viewport: 393x852 (iPhone 15 Pro equivalent)
- Exploration agents used: 3
- Walkthrough journeys completed: 10
- Total steps: 42
- Total edge cases: 15
- Review iterations: 1
Next steps:
- Run "convert mobile workflows to playwright" to generate E2E test files
- Run "run playwright tests" to execute the generated tests
フェーズ 8：セッションの振り返り
完了前に references/reflection-protocol.md を読み、記載された手順を実行します。
セッションの復旧
スキルが呼び出された際に既存のタスクリストが見つかった場合は、この判断ツリーを使用して再開位置を決定します。
判断ツリー
Check TaskList for "Generate: Mobile Workflows"
CASE 1: No task list exists
-> Start from Phase 1
CASE 2: Explore tasks are "in_progress"
-> Some agents may have timed out
-> Check which Explore tasks completed
-> Re-spawn only the incomplete agents
-> Resume from Phase 2 (partial)
CASE 3: All Explore tasks are completed, journeys_confirmed is NOT set
-> Resume from Phase 3 (journey discovery)
CASE 4: All Explore tasks are completed, journeys_confirmed is set, no Walkthrough task
-> Resume from Phase 4 (app URL + auth setup)
CASE 5: Walkthrough task is "in_progress"
-> Some journeys were completed, others remain
-> Read completed_journeys and current_journey from task metadata
-> Inform user which journeys are done and which is next
-> Resume from Phase 5 at the next incomplete journey
CASE 6: Walkthrough task is "completed", no Approval task
-> All journeys walked through but document not yet reviewed
-> Resume from Phase 6 (final review)
CASE 7: Approval task exists with result "changes_requested"
-> User gave feedback but revisions were not completed
-> Read the feedback from task metadata
-> Apply changes and re-present for review
-> Resume from Phase 6 (next iteration)
CASE 8: Approval task is "completed" with result "approved", no Write task
-> Document was approved but file was not written
-> Resume from Phase 7 (write file)
CASE 9: Write task is "completed"
-> Everything is done
-> Show the final summary and ask if the user wants to make changes
再開時は必ずユーザーに伝える
I found an existing session for mobile workflow generation.
Current state: [describe where things left off]
Last completed phase: [phase name]
I will resume from [next phase]. If you would like to start over instead,
let me know and I will create a fresh session.
ワークフロー作成基準
ワークフローのステップを記述する際は、以下の動詞形とパターンをそのまま使用してください。一貫性を保つことで、ワークフローの可読性、レビューのしやすさ、自動化のしやすさが向上します。モバイルワークフローでは、「Tap」を基本の操作動詞として使用します。
| 操作 | 形式 | 例 |
|---|---|---|
| ナビゲーション | Navigate to [URL/page] | ダッシュボードページに移動する |
| タップ | Tap the "[label]" [element type] | 「Save」ボタンをタップする |
| 入力 | Type "[text]" in the [field name] field | メールフィールドに「[email protected]」と入力する |
| 選択 | Select "[option]" from the [dropdown name] dropdown | ロールドロップダウンから「Admin」を選択する |
| チェック | Check the "[label]" checkbox | 「Remember me」チェックボックスをオンにする |
| チェック解除 | Uncheck the "[label]" checkbox | 「Send notifications」チェックボックスをオフにする |
| 切り替え | Toggle the "[label]" switch [on/off] | 「Dark mode」スイッチをオンにする |
| クリア | Clear the [field name] field | 検索フィールドをクリアする |
| スクロール | Scroll [direction] to [target/distance] | 下にスクロールしてコメントセクションへ移動する |
| スワイプ | Swipe [direction] on [element/area] | 通知カードを左にスワイプして操作項目を表示する |
| 長押し | Long press the "[label]" [element] | メッセージを長押ししてコンテキストメニューを表示する |
| 引き下げ | Pull down on [area] to [action] | フィードを下に引き下げて更新する |
| タップして長押し | Tap and hold the "[label]" [element] for [duration] | 画像を2秒間タップして長押しする |
| 待機 | Wait for [condition] | 読み込みスピナーが消えるまで待つ |
| 確認 | Verify [expected state] | 「Saved」というメッセージが表示された成功トーストを確認する |
| アップロード | Upload "[filename]" to the [upload area] | 「avatar.png」をプロフィール画像のドロップゾーンにアップロードする |
| 押す | Press [key/shortcut] | デバイスの戻るボタンを押す |
| 更新 | Refresh the page | ページを更新し、データが保持されていることを確認する |
| メニューを開く | Open the [menu type] | ハンバーガーメニューを開く |
| メニューを閉じる | Close the [menu type] | ナビゲーションドロワーを閉じる |
| 閉じる | Dismiss the [element] | 下にスワイプしてボトムシートを閉じる |
アップロードステップでのテストデータファイルの選択
ウォークスルーでUploadステップを記述する際は、読み込まれたプロファイルにfilesが設定されているか確認してください。設定されている場合は、次の手順に従います。
-
利用可能なテストファイルをユーザーに提示します。
This profile has test data files available: 1. valid-deck.pptx — Clean deck, passes all checks 2. corrupted.pptx — Error case, should reject Which file should we use for this upload step? (number, "skip" to use a different file, or "none" to write the step without a specific file) -
ユーザーがファイルを選択した場合：
pathエントリの場合：Uploadステップではプロジェクトルートからの相対パスを使用します（例：Upload "test-fixtures/valid-deck.pptx" to the file dropzone）urlエントリの場合：Uploadステップの上のコメントにURLを記載し（例：``）、Uploadステップにはファイル名のみを記述します
-
ライブウォークスルーでアップロードステップが完了した後、
acceptance基準がある場合（プロファイルレベルの基準とファイルレベルの上書きをシャロー・マージしたもの）、該当する各基準に対応するVerifyステップを追加します。基準 生成するVerifyステップ uploadAccepted: trueエラーメッセージまたは検証エラーが表示されないことを確認する uploadAccepted: falseエラーメッセージまたは検証エラーが表示されることを確認する processingCompletes: true処理インジケーターが最終状態に移行することを確認する resultDownloadable: trueダウンロードボタンまたはリンクが利用可能であることを確認する errorExpected: trueエラーメッセージが表示され、アプリが引き続き正常に動作することを確認する expectedStatus: "X"ステータスに「X」と表示されることを確認する これらのVerifyステップは、通常のウォークスルーの一部としてワークフロー出力に追加します。記録する前に、スナップショットを確認しながら各ステップをユーザーに確認してください。
-
ユーザーが「skip」または「none」を選択した場合は、テストデータを組み込まず、通常どおりUploadステップを記述します。
自動化しやすいガイドライン
ワークフローは、モバイルビューポートで実行するPlaywright E2Eテストに変換できるよう設計されています。変換を容易にするため、以下のガイドラインに従ってください。
モバイルビューポートの設定
生成するすべての Playwright テストでは、手順を実行する前にモバイルビューポートを設定する必要があります。
// In test setup / beforeEach
await page.setViewportSize({ width: 393, height: 852 });
または、Playwright のブラウザーコンテキストのオプションを使用して同様に設定できます。
const context = await browser.newContext({
viewport: { width: 393, height: 852 },
userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) ...',
isMobile: true,
hasTouch: true,
});
ロケーターの説明
ワークフローの手順で要素を説明する際は、Playwright が推奨するロケーター戦略にそのまま対応できる説明を優先してください。
| ロケーター戦略 | ワークフローでの説明 | Playwright での同等の記述 |
|---|---|---|
| ロール＋名前 | 「Submit」ボタンをタップする | page.getByRole('button', { name: 'Submit' }) |
| ラベル | メールアドレス欄に「[email protected]」と入力する | page.getByLabel('Email') |
| テキスト | 「Learn more」リンクをタップする | page.getByText('Learn more') |
| プレースホルダー | 検索ボックスに「Search...」と入力する | page.getByPlaceholder('Search...') |
| テスト ID | 削除ボタン（data-testid="delete-btn"）をタップする | page.getByTestId('delete-btn') |
| タイトル | 情報アイコン（title="More information"）をタップする | page.getByTitle('More information') |
推奨されるロケーターの順序
手順を記述する際は、次の順序（Playwright の推奨に準拠）でロケーターの説明を優先してください。
- ロールベース（ボタン、リンク、見出しなど）
- ラベルベース（フォームフィールド）
- テキストベース（表示されているテキストコンテンツ）
- プレースホルダーベース（入力欄のプレースホルダー）
- テスト ID ベース（data-testid 属性）
- CSS／XPath ベース（最後の手段。可能な限り避けてください）
モバイルでの Playwright に関する注意事項
Playwright でのモバイル実行を想定したワークフローを記述する際は、次の点に留意してください。
| 注意事項 | 説明 | ワークフローでのガイダンス |
|---|---|---|
| タップとクリック | Playwright の click() はどちらにも使えますが、hasTouch が true の場合は tap() も使用できます | ワークフローでは「タップする」と記述してください。変換時に .tap() または .click() を使用できます |
| ビューポートサイズ | モバイルでは要素が画面外にある場合があります | 画面の下部にある要素を操作する前に、スクロールする手順を含めてください |
| 仮想キーボード | 入力欄にフォーカスすると仮想キーボードが表示され、レイアウトがずれる場合があります | キーボードの表示が手順の流れに影響する場合は、その旨を記載してください |
| モバイルナビゲーション | ハンバーガーメニューを開くまでナビゲーションリンクにアクセスできない場合があります | 非表示のナビゲーションリンクをタップする前に、必ず「ハンバーガーメニューを開く」を含めてください |
| ボトムシートを閉じる | ボトムシートを閉じるには、下方向へのスワイプまたは背景のタップが必要な場合があります | 明示的に閉じる手順を含めてください |
| スクロールコンテナー | モバイルでは、入れ子になったスクロールコンテナーの動作が異なります | スクロール可能な領域が入れ子になっている場合は、どのコンテナーをスクロールするか指定してください |
| 固定位置の要素 | 固定ヘッダーやフッターがタップ対象を覆う場合があります | 固定要素との重なりを避けるためにスクロールが必要な場合は、その旨を記載してください |
自動化できない手順
Playwright では自動化できない手順もあります。これらには [MANUAL] を付けてください。
4. [MANUAL] Verify the email arrives in the user's inbox
- Check for subject line "Welcome to [App Name]"
7. [MANUAL] Complete the CAPTCHA challenge
- Workflow continues after CAPTCHA is solved
9. [MANUAL] Verify push notification appears on device
- Confirm notification content matches expected text
既知の制限事項
| 制限事項 | 説明 | 回避策 |
|---|---|---|
| ネイティブのファイルダイアログ | Playwright は OS レベルのファイルピッカーを操作できません | ファイル入力をタップする代わりに page.setInputFiles() を使用します |
| ネイティブの共有シート | OS レベルの共有ダイアログを自動化できません | 共有機能をスキップするか、モックします |
| 実機のジェスチャー | Playwright はタッチ操作をエミュレートしますが、実機ではありません | 複雑なマルチタッチジェスチャーは手動テストが必要になる場合があります |
| カメラ／マイクへのアクセス | 権限のプロンプトは実際のモバイル環境とは異なります | ブラウザーコンテキストのセットアップで権限を付与します |
| 複数タブでの OAuth | 新しいタブで開く OAuth ポップアップには特別な処理が必要です | context.waitForEvent('page') のパターンを使用します |
| クリップボードへのアクセス | Clipboard API には権限が必要です | ブラウザーコンテキストのセットアップで権限を付与します |
| ダウンロードの検証 | ダウンロード後にファイルの内容を直接検証することはできません | ダウンロードイベントのリスナーとファイルシステムのチェックを使用します |
| 位置情報のプロンプト | 権限のプロンプトによって自動化がブロックされます | ナビゲーションの前に、コンテキストオプションで位置情報を設定します |
| デバイスの向き | Playwright のビューポートサイズ変更では向きをシミュレートしますが、ネイティブの回転ではありません | page.setViewportSize() を使用して幅と高さを入れ替えます |
| iOS Safari の特有の動作 | Playwright は Chromium を使用しており、モバイル版 WebKit ではありません | WebKit 固有で異なる可能性がある動作に注意します（より忠実に再現するには webkit ブラウザーを使用します） |
自動化の前提条件
ワークフローで特定のセットアップが必要な場合は、前提条件ブロックに記載します。
**Preconditions:**
- User is logged in as admin (`[email protected]` / `password123`)
- Viewport is set to 393x852 (mobile)
- At least 3 posts exist in the database
- The feature flag "new-editor" is enabled
この情報は、ビューポートの設定を含む適切な beforeEach ブロックと beforeAll ブロックをコンバータースキルで生成するために不可欠です。
iOS Human Interface Guidelines への配慮
ワークフローを生成するときは、iOS Human Interface Guidelines（HIG）を考慮し、モバイル Web アプリケーションの UX 品質を評価します。これは Web アプリケーション（ネイティブ iOS アプリではありません）ですが、iPhone を利用するモバイル Web ユーザーは、ネイティブ iOS のパターンによって形作られた強い期待を持っています。重大な差異があれば指摘します。
タッチターゲット
iOS HIG では、タッチターゲットの最小サイズとして 44x44 ポイントが推奨されています。モバイル Web の場合：
- ボタン、リンク、操作可能な要素は、モバイルビューポートで少なくとも 44x44px にする必要があります。
- 調査で、計算されたサイズがこれより小さいボタンやリンクが見つかった場合は、ワークフロードキュメントで指摘します。
- 検証手順には、「「[element]」ボタンのタップターゲットが少なくとも 44x44px あることを確認する」と記載します。
タブバーとハンバーガーメニュー
iOS ユーザーは、アプリの主要なナビゲーションに画面下部のタブバーを期待します。モバイル Web の場合：
- アプリの主要なナビゲーションがハンバーガーメニューのみの場合、潜在的な UX 上の懸念として記載します。
- アプリに画面下部のタブバーがある場合、画面下部に固定され、常にアクセス可能な状態であることを確認します。
- 下部ナビゲーションがコンテンツに重なったり、仮想キーボードの背後に隠れたりしないことを確認します。
スクロールとジェスチャー操作
iOS ユーザーは、滑らかでネイティブに近いスクロール動作を期待します。
- スクロール可能な領域に
-webkit-overflow-scrolling: touchまたは同等の CSS が適用されていることを確認します（古いブラウザーで必要な場合）。 - 意図しないスクロールの連鎖を防ぐため、
overscroll-behaviorが適切に設定されていることを確認します。 - アプリでカスタムジェスチャー（スワイプして削除、引っ張って更新など）を使用している場合、応答性がよく、ブラウザーのジェスチャーと競合しないことを確認します。
入力時のズーム防止
iOS Safari では、font-size が 16px 未満の入力欄をタップすると、ページが自動的にズームします。これはモバイル UX でよく見られる、操作を妨げる問題です。
- 調査中に、フォントサイズが 16px 未満の入力要素を探します。
- 検証手順には、「[input field] をタップし、ページがズームインしないことを確認する」と記載します。
font-size < 16pxの入力欄が見つかった場合は、モバイル UX の問題として指摘します。
セーフエリアのインセット
最新の iPhone には、コンテンツを隠してしまうノッチやホームインジケーターがあります。
- アプリの CSS で
env(safe-area-inset-*)またはconstant(safe-area-inset-*)を使用しているか確認します。 - 固定要素（ヘッダー、フッター、下部ナビゲーション）がセーフエリアを考慮していない場合は、その点を指摘します。
- 画面の端に近いコンテンツの確認手順を記述します。「下部ナビゲーションバーがデバイスのホームインジケーターに隠れていないことを確認します。」
下部ナビゲーションのパターン
アプリが下部ナビゲーション（タブバー、下部アクションバー）を使用している場合：
- スクロール中も画面下部に固定されていることを確認します。
- コンテンツを覆っていないことを確認します（メインコンテンツ領域に適切な
padding-bottomが設定されているか確認します）。 - タブをタップするとアクティブ状態が強調表示され、正しいセクションに移動することを確認します。
- 仮想キーボードを開いたとき、下部ナビゲーションが画面外に押し出されないことを確認します。
モバイル UX のアンチパターン
ワークフローを生成する際は、次のような一般的なモバイル UX のアンチパターンに注意してください。探索中に検出した場合は、ワークフロー文書で指摘し、アプリケーションが適切に処理できることを確認するための具体的なテスト手順を記述してください。
ナビゲーションのアンチパターン
| アンチパターン | 重要な理由 | 確認手順 |
|---|---|---|
| タブバーのないハンバーガーメニュー | 主要なナビゲーションが追加のタップの背後に隠れ、モバイルでのナビゲーションの負担が増えます | 主要なセクションに1～2回のタップでアクセスできることを確認します。下部タブバーの採用を検討します |
| ネイティブではない戻るボタン | モバイルユーザーはブラウザーやシステムの戻る操作が機能することを期待します。カスタムの戻るボタンは混乱を招くことがあります | 前のページに進み、ブラウザーの戻る操作を行って、前のページが正しく読み込まれることを確認します |
| 下部ナビゲーションがない | モバイルで常時表示されるナビゲーションがないと、セクションを切り替えるたびにハンバーガーメニューを開く必要があります | 主要なナビゲーションが常に表示されているか、すぐにアクセスできることを確認します |
| 代替手段のないジェスチャーのみのナビゲーション | スワイプジェスチャーに気づかないユーザーもおり、アクセシビリティを必要とするユーザーは使わない場合があります | スワイプで移動できるすべてのコンテンツに、視認できるボタンまたはリンクの代替手段があることを確認します |
| パンくずリストのない深い階層 | 画面の小さい端末では、ユーザーが深いページ階層で迷うことがあります | 3階層以上深く移動し、ユーザーが現在位置を把握して戻れることを確認します |
| モバイルでのリダイレクトループ | ログインからリダイレクトを経て再びログインするサイクルが発生します。特にモバイル固有の認証フローで起こりやすくなります | 保護されたルートへのアクセスを試み、ログインへのリダイレクトが1回だけ行われることを確認します |
タッチ操作のアンチパターン
| アンチパターン | 重要な理由 | 確認手順 |
|---|---|---|
| タッチターゲットが44px未満 | 指先の操作は正確さに欠けるため、小さいターゲットは誤タップやストレスの原因になります | すべてのインタラクティブ要素に、少なくとも44x44pxのタップ領域があることを確認します |
| ホバーに依存するインタラクション | モバイルにはホバー状態がないため、ホバーメニューやツールチップにアクセスできません | ホバーで表示されるすべてのコンテンツに、タップで利用できる代替手段があることを確認します |
| 小さなフォーム入力欄（フォントが16px未満） | iOS Safari は、フォントサイズが16px未満の入力欄にフォーカスすると自動ズームし、レイアウトが崩れます | 各入力欄をタップし、ページが自動ズームしないことを確認します |
| タップ間隔が不十分 | 隣接するタッチターゲットの間隔が足りないと、誤タップの原因になります | 隣接するインタラクティブ要素の間に少なくとも8pxの間隔があることを確認します |
| ダブルタップが必要 | モバイルでは予期しない動作です。一部の端末では、最初のタップがホバーとして解釈されることがあります | すべてのアクションが1回のタップで応答することを確認します |
| タッチ時のフィードバックがない | ユーザーはタップ時に視覚的なフィードバック（不透明度の変化、波紋、ハイライト表示）があることを期待します | ボタンやリンクをタップし、すぐに視覚的なフィードバックがあることを確認します |
ビジュアル上のアンチパターン
| アンチパターン | 重要な理由 | 検証手順 |
|---|---|---|
| モバイルで文字が小さすぎる | 14px未満の本文は、モバイル画面では読みづらくなります | 本文が14px以上であることを確認します。16pxを推奨します |
| 小さい画面でコントラストが不十分 | 明るい環境で使う小さな画面には、強いコントラストが必要です | テキストがWCAG AAのコントラスト比（通常のテキストで4.5:1）を満たすことを確認します |
| viewportのmetaタグがない | タグがないと、モバイルブラウザーはデスクトップの幅で表示してから縮小します | <meta name="viewport" content="width=device-width, initial-scale=1"> が存在することを確認します |
| モバイルへの適応を妨げる固定幅 | width: 960px などの要素は、モバイルのレイアウトを崩します | コンテンツが393pxのビューポート幅を超えていないことを確認します |
| ビューポートより幅が広いコンテンツ | 横スクロールが発生し、モバイルのUXに深刻な問題を引き起こします | すべてのページを横方向にスクロールし、横方向にはみ出すコンテンツがないことを確認します |
| レスポンシブでない画像 | max-width: 100% が指定されていない大きな画像は、モバイルのレイアウトを崩します | すべての画像が横スクロールなしでビューポート内に収まることを確認します |
| アクセス手段のないテキストの省略 | 省略されたテキストの全文を読む手段がありません | 省略されたテキストに、タップして展開する機能またはツールチップによる代替手段があることを確認します |
コンポーネントのアンチパターン
| アンチパターン | 重要な理由 | 検証手順 |
|---|---|---|
| モバイルでデスクトップ風のドロップダウンを使用する | 選択肢の小さなドロップダウンは、正確にタップするのが困難です | select要素で、モバイル標準のピッカーまたはタップ領域の大きな代替手段を使用していることを確認します |
| 小さすぎるチェックボックスとラジオボタン | 標準のHTMLチェックボックスやラジオボタンは、タッチ操作には小さすぎます | チェックボックスやラジオボタンのタップ領域が少なくとも44x44pxであることを確認します |
| ビューポートからはみ出し、スクロールできないモーダル | モバイル画面より縦に長いモーダルのコンテンツにはアクセスできなくなります | 各モーダルを開き、スクロールしてすべてのコンテンツにアクセスできることを確認します |
| ツールチップに依存する情報 | ツールチップにはホバー操作が必要ですが、モバイルにはホバー操作がありません | すべてのツールチップの内容に、タップ操作でアクセスできるか、モバイルで常に表示されていることを確認します |
| デスクトップ向けのサイズのテーブル | 列が多く幅の広いテーブルは、モバイルで画面からはみ出します | テーブルをコンテナー内で横スクロールできるか、モバイル向けに再配置できることを確認します |
| 複数列のフォーム | 横並びのフォームフィールドは、モバイルでは狭すぎます | モバイルのビューポートでは、フォームフィールドが縦に並ぶことを確認します |
| 画面のスペースを取りすぎる固定ヘッダー | モバイルのビューポートの20％以上を占める固定ヘッダーは、コンテンツ領域を狭めます | モバイルで固定ヘッダーがコンパクト（高さ60px未満）であることを確認します |
パフォーマンスのアンチパターン
| アンチパターン | 重要な理由 | 検証手順 |
|---|---|---|
| 大きく、最適化されていない画像 | モバイル回線は遅いことが多く、大きな画像は描画を遅らせます | 画像にレスポンシブなサイズ（srcset）が使われているか、適切に圧縮されていることを確認します |
| フレーム落ちを起こす重いアニメーション | モバイル端末はGPUの処理能力が低く、ぎこちないアニメーションは不具合のように感じられます | アニメーションのあるページをスクロールし、滑らかな60fpsで描画されることを確認します |
| 操作時のレイアウトシフト | タップ時にコンテンツが飛び回ると、小さな画面では戸惑いを招きます | インタラクティブな要素をタップし、予期しないレイアウトシフトがないことを確認します |
| 操作を妨げる過剰なJavaScript | JavaScriptの実行に時間がかかると、モバイルでのタッチ操作への応答がブロックされます | ページ読み込み直後にボタンをタップし、100ms以内に応答することを確認します |
| 非同期コンテンツの読み込み状態がない | 回線の遅いモバイルユーザーには、空白が表示されます | データ読み込み操作を実行し、スケルトンまたはスピナーがすぐに表示されることを確認します |
モバイルUX検証手順のテンプレート
探索中にアンチパターンが検出された場合は、専用のUX検証ワークフローを追加します。
## Workflow [N]: Mobile UX Pattern Compliance
> Verifies the application follows mobile web best practices and avoids
> common UX anti-patterns that harm the mobile user experience.
**Preconditions:**
- Viewport is set to 393x852 (mobile)
**Steps:**
1. Navigate to the home page
- Verify no horizontal scroll at 393px viewport width
- Verify the viewport meta tag is present
2. Verify all interactive elements have adequate touch targets
- Tap each button and link on the page
- Verify tap targets are at least 44x44px
- Verify at least 8px spacing between adjacent interactive elements
3. Verify navigation is accessible on mobile
- If hamburger menu: open it, verify all primary nav items are present
- Verify navigation can be reached within 2 taps from any page
4. Tap each form input field
- Verify the page does not auto-zoom on focus (font-size >= 16px)
- Verify the virtual keyboard does not obscure the active input
- Verify form fields are stacked vertically
5. Open any modals or bottom sheets
- Verify content does not overflow the mobile viewport
- Verify the modal/sheet can be dismissed (close button or swipe)
6. Scroll through the full page
- Verify content reflows to single-column where appropriate
- Verify images fit within the viewport
- Verify no horizontal overflow on any section
7. Navigate using browser back button
- Verify the previous page loads correctly
- Verify no redirect loops occur
8. [Continue based on specific anti-patterns found...]
更新の処理
ユーザーが「Update」モード（既存のワークフローの変更）を選択した場合は、現在の網羅性を維持しながら変更を最小限に抑えるため、次のルールに従います。
既存のワークフローを更新する際のルール
-
動作するワークフローを維持する -- 既存のワークフローが引き続き有効な場合（ルートが存在し、コンポーネントが一致し、手順が正しい場合）は、変更せずに維持します。スタイルの一貫性を理由に、動作するワークフローを書き換えてはいけません。
-
非推奨のワークフローを明示する -- ワークフローが存在しなくなったルートやコンポーネントを参照している場合、削除してはいけません。代わりに、非推奨マーカーを追加します。
## Workflow 7: Legacy Export Feature
> **DEPRECATED** -- This workflow references the legacy export feature which
> has been removed. Keeping for reference until confirmed safe to delete.
-
新しいワークフローを追加する -- 新しいワークフローは、該当するセクション（Core、Feature、または Edge Case）の末尾に追加します。最後の既存ワークフローに続けて、番号を順番に付けます。
-
バージョンの注記 -- ファイルの先頭にバージョン履歴のセクションを追加します。
## Version History
| Date | Action | Details |
|------|--------|---------|
| 2025-01-20 | Updated | Added workflows 26-28 for new dashboard features |
| 2025-01-15 | Updated | Deprecated workflow 7 (export feature removed) |
| 2025-01-01 | Created | Initial generation: 25 workflows |
- 既存のワークフローを再検証する -- 調査中に、既存のワークフローの手順を現在のコードベースと照合します。変更された要素やルートを参照している手順があれば、その旨を明示します。
3. Tap the "Export CSV" button
- **[CHANGED]** Button label is now "Download CSV" (updated in v2.2)
- Verify download begins within 3 seconds
- ワークフローの番号を維持する -- 既存のワークフローの番号を付け直してはいけません。たとえば、ワークフロー 7 が非推奨になり、ワークフロー 28 が追加されても、番号の空きはそのままにします。これにより、「ワークフロー 7」への外部参照を引き続き有効に保てます。
更新の概要
更新操作の後、変更の概要を提示します。
Mobile workflow update complete.
Changes:
- Workflows preserved (unchanged): 20
- Workflows updated (steps modified): 3
- Workflows deprecated: 1
- Workflows added (new): 3
- Total workflows: 27 (1 deprecated)
Changed workflows:
- Workflow 4: Updated step 3 (button label changed)
- Workflow 12: Updated step 1 (route changed from /settings to /preferences)
- Workflow 19: Updated steps 5-7 (new confirmation dialog added)
Deprecated workflows:
- Workflow 7: Legacy Export Feature (export removed in v2.3)
New workflows:
- Workflow 26: Dashboard Widget Customization (mobile layout)
- Workflow 27: Pull-to-Refresh Feed
- Workflow 28: Bottom Sheet Filter Selection
コメント
Markdown 対応