maestro-workflow - SKILL.md Agent Skill

name: maestro-workflow description: Maestro 기반 모바일 테스트 자동화 워크플로우를 시작합니다. planner -> grouper -> generator -> executor -> healer 순서로 Agent 기반 테스트를 자동 실행합니다. "/maestro-workflow", "마에스트로 워크플로우", "Maestro 테스트" 등의 명령으로 활성화됩니다. allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Task, TodoWrite, AskUserQuestion

Maestro 테스트 워크플로우

Claude + Maestro로 Agent 기반 모바일 테스트 자동화를 수행하는 워크플로우입니다.

활성화 방법

/maestro-workflow
마에스트로 워크플로우
Maestro 테스트
마에스트로로 [기능] 테스트

예시

사용자: /maestro-workflow 로그인 기능 테스트
사용자: 마에스트로로 거래 추가 기능 테스트해줘
사용자: Maestro 테스트 전체 앱

워크플로우 개요

[요청 접수]
    |
    v
[Phase 1: 시나리오 계획] ── maestro-planner-agent
    |  - 앱 기능 분석
    |  - 테스트 시나리오 YAML 출력
    |
    v
[Phase 2: 그룹화] ── maestro-grouper-agent
    |  - 병렬/순차 실행 그룹 분류
    |  - 실행 순서 결정
    |
    v
[Phase 3: Flow 생성] ── maestro-generator-agent
    |  - Maestro YAML 파일 생성
    |  - flows/ 디렉토리에 저장
    |
    v
[Phase 4: 실행] ── scripts/run-maestro.sh
    |  - 그룹별 병렬/순차 실행
    |  - 결과 수집
    |
    v
[Phase 5: 복구 Loop] ── maestro-healer-agent
    |  +──[테스트 실패]──> healer 호출
    |  |                    - 실패 분석
    |  |                    - flow 수정
    |  +<─────────────────[재실행]
    |
    v (모든 테스트 통과)
[Phase 6: 완료 보고]
    - 결과 요약
    - 보고서 생성

Phase 1: 시나리오 계획

1.1 maestro-planner-agent 호출

Task(
  subagent_type: "maestro-planner-agent",
  prompt: """
  다음 기능에 대한 Maestro 테스트 시나리오를 계획해주세요:

  기능: [테스트 대상 기능]
  앱 정보:
  - 패키지: com.household.shared.shared_household_account
  - 아키텍처: Clean Architecture + Feature-first

  lib/features/ 디렉토리를 분석하여 시나리오를 도출하세요.
  반드시 YAML 형식으로만 출력하세요.
  """
)

1.2 출력 예시

scenarios:
  - id: login_success
    description: 정상 로그인
    entry_state: logged_out
    screen: Login
    mutation: true
    shared_state: true
    priority: critical
    steps:
      - 로그인 화면 진입
      - 이메일 입력
      - 비밀번호 입력
      - 로그인 버튼 탭
      - 홈 화면 확인

Phase 2: 그룹화

2.1 maestro-grouper-agent 호출

Task(
  subagent_type: "maestro-grouper-agent",
  prompt: """
  다음 테스트 시나리오를 병렬 실행 그룹으로 분류해주세요:

  [Phase 1 출력 YAML]

  반드시 YAML 형식으로만 출력하세요.
  """
)

2.2 출력 예시

groups:
  - group_id: auth
    execution: sequential
    test_ids: [login_success, logout]
    reason: 인증 상태 공유로 순차 실행
    order: 1

  - group_id: read_only
    execution: parallel
    test_ids: [category_list, statistics_view]
    reason: 읽기 전용으로 병렬 실행 가능
    order: 2

Phase 3: Flow 생성

3.1 maestro-generator-agent 호출

Task(
  subagent_type: "maestro-generator-agent",
  prompt: """
  다음 시나리오를 Maestro YAML flow 파일로 생성해주세요:

  시나리오:
  [Phase 1 출력 YAML]

  그룹 정보:
  [Phase 2 출력 YAML]

  앱 패키지: com.household.shared.shared_household_account

  flows/ 디렉토리에 파일을 생성하세요.
  """
)

3.2 생성되는 파일 구조

flows/
├── auth/
│   ├── login_success.yaml
│   └── logout.yaml
├── transaction/
│   └── add_expense.yaml
└── common/
    └── setup.yaml

Phase 4: 실행

4.1 Maestro CLI 실행

Claude가 직접 실행합니다:

# 순차 그룹 실행
maestro test flows/auth/login_success.yaml
maestro test flows/auth/logout.yaml

# 병렬 그룹 실행
maestro test flows/transaction/ &
maestro test flows/category/ &
wait

4.2 실행 스크립트

# scripts/run-maestro.sh 실행
./scripts/run-maestro.sh

Phase 5: 복구 Loop

5.1 실패 감지

실행 결과에서 실패한 테스트 확인:

# 로그에서 실패 추출
grep -l "FAILED" .maestro/logs/*.log

5.2 maestro-healer-agent 호출

Task(
  subagent_type: "maestro-healer-agent",
  prompt: """
  다음 실패한 Maestro 테스트를 수정해주세요:

  실패한 flow: flows/auth/login_success.yaml

  실패 로그:

[실패 로그 내용]


테스트 목적은 변경하지 마세요.
selector 변경이나 대기 시간 추가로 해결하세요.
"""
)

5.3 재시도 제한

동일 테스트 최대 3회 재시도
초과 시 수동 검토 요청

Phase 6: 완료 보고

6.1 결과 요약

# .maestro/reports/summary.yaml
execution:
  date: 2026-01-05
  total_tests: 10
  passed: 8
  failed: 1
  healed: 1

groups:
  - group_id: auth
    tests: 2
    passed: 2

  - group_id: transaction
    tests: 3
    passed: 2
    healed: 1

failures:
  - test_id: share_invite
    attempts: 3
    status: manual_review

6.2 보고서 저장

.maestro/
├── flows/          # 생성된 flow 파일
├── logs/           # 실행 로그
├── screenshots/    # 스크린샷
└── reports/        # 결과 보고서
    └── summary.yaml

Agent 역할 정리

Agent	역할	출력
maestro-planner-agent	테스트 시나리오 계획	scenarios YAML
maestro-grouper-agent	병렬/순차 그룹화	groups YAML
maestro-generator-agent	Maestro flow 생성	.yaml 파일들
maestro-healer-agent	실패 테스트 복구	수정된 flow

디렉토리 구조

project/
├── .claude/
│   ├── agents/
│   │   ├── maestro-planner-agent.md
│   │   ├── maestro-grouper-agent.md
│   │   ├── maestro-generator-agent.md
│   │   └── maestro-healer-agent.md
│   └── skills/
│       └── maestro-workflow/
│           └── SKILL.md
├── flows/                    # Maestro flow 파일
│   ├── auth/
│   ├── transaction/
│   └── common/
├── scripts/
│   ├── run-maestro.sh       # 실행 스크립트
│   └── heal-maestro.sh      # 복구 스크립트
└── .maestro/
    ├── logs/
    ├── screenshots/
    └── reports/

환경 설정

Maestro 설치

# macOS
brew install maestro

# 또는 curl
curl -Ls "https://get.maestro.mobile.dev" | bash

환경변수 (.env)

TEST_EMAIL=test@example.com
TEST_PASSWORD=TestPassword123!
MAESTRO_DRIVER_STARTUP_TIMEOUT=120000

자동 승인 설정

워크플로우 원활한 실행을 위한 settings.local.json 권한:

{
  "permissions": {
    "allow": [
      "Bash(maestro:*)",
      "Bash(./scripts/run-maestro.sh:*)",
      "Bash(./scripts/heal-maestro.sh:*)"
    ]
  }
}

사용 예시

전체 앱 테스트

사용자: /maestro-workflow 전체 앱 테스트

특정 기능 테스트

사용자: /maestro-workflow 로그인 기능만 테스트

특정 그룹만 재실행

사용자: auth 그룹 테스트만 다시 실행해줘

주의사항

Maestro 설치 필수: maestro CLI가 PATH에 있어야 함
에뮬레이터 실행 필요: Android/iOS 에뮬레이터가 실행 중이어야 함
YOLO 모드 권장: --dangerously-skip-permissions로 실행 시 끊김 없이 진행
테스트 격리: 각 테스트는 clearState로 시작하여 격리
병렬 실행 주의: shared_state 테스트는 반드시 순차 실행