bdd-scenario-agent

BDD 시나리오 생성 전문가입니다. Gherkin 문법과 Step Definition 작성에 사용합니다.

/cc-flutter:bdd:generate — 화면 시나리오 자동 작성기#

항목	내용
실행 명령	`/cc-flutter:bdd:generate`
별칭	`/bdd:scenario`, `/test:bdd`
모델	`sonnet`
사용 도구	`Read`, `Edit`, `Write`, `Glob`, `Grep`
연계 스킬	`bdd`

한마디로#

새 화면을 만들 때 "이 화면이 이렇게 동작해야 한다"는 테스트 시나리오를 자동으로 써주는 도우미입니다. 신입 직원에게 "이 버튼 누르면 이렇게 되고, 빈칸이면 이런 경고가 떠야 한다"는 업무 매뉴얼을 대신 정리해주는 것과 같아요.

누가·언제 쓰나요#

목록·상세·입력 폼 같은 새 화면을 개발하기 직전, 어떻게 동작해야 하는지 합의된 시나리오가 필요할 때
/cc-flutter:bdd:generate 명령을 직접 실행했을 때
피그마 분석(/cc-flutter:figma:analyze) 흐름에서 자동으로 호출될 때

무엇을 해주나요#

화면 종류(목록 / 상세 / 입력 폼)에 맞는 시나리오 문서와 그 시나리오를 실제로 검증하는 코드 묶음을 만들어 줍니다. 실제로 생기는 파일은 app/{app}/integration_test/ 아래에 만들어집니다 — feature 패키지 안에는 BDD 관련 파일을 두지 않습니다.

features/{feature}_list.feature, features/{feature}_detail.feature, features/{feature}_form.feature — 사람이 읽을 수 있는 "동작 시나리오" 문서 (Gherkin 형식, 빌드 대상 아님)
step/*_steps.dart — 각 시나리오 문장을 실제로 검증하는 코드 (TestDriver 기반, 손으로 작성)
scenarios/{feature}_{scenario}_test.dart — .feature의 Scenario 이름·step 순서를 그대로 옮긴 Patrol 테스트 (코드 생성기 없이 손으로 작성)

각 시나리오 문장은 영어 원문 + # 한글 번역 주석을 나란히 적어, 개발자와 비개발자가 함께 읽을 수 있게 작성됩니다.

어떻게 쓰나요#

# 기본: 기능 이름과 엔티티 이름을 넘깁니다
/cc-flutter:bdd:generate

# 다른 이름으로도 호출할 수 있어요 (별칭)
/bdd:scenario
/test:bdd

넘기는 정보:

feature_name (필수) — 기능 모듈 이름 (예: community_post)
entity_name (필수) — 데이터 이름 (예: CommunityPost)
screen_type (선택) — list(목록) / detail(상세) / form(입력 폼)

안에서 무슨 일이 벌어지나요#

화면 종류를 판단한 뒤, 종류별로 흔히 필요한 동작들을 시나리오로 풀어냅니다.

목록 화면 — 목록 불러오기, 당겨서 새로고침, 무한 스크롤, 카드 탭 시 상세 이동, 카테고리 필터, 비어 있음·오류 상태
상세 화면 — 상세 정보 표시, 좋아요 토글, (작성자만) 수정·삭제, 공유
입력 폼 화면 — 정상 제출, 필수 항목 누락 경고, 글자 수 제한, 이미지 첨부·삭제, 작성 취소, 네트워크 오류
품질 점검 — 모든 문장에 한글 번역 주석이 붙었는지, 공용 스텝을 재사용했는지, @smoke·@validation 같은 분류 태그를 달았는지 체크리스트로 확인합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role#

Analyzes screen types (list/detail/form) and generates Gherkin scenarios and Step definitions.

Activation Conditions#

/cc-flutter:bdd:generate Activated when command is invoked
/cc-flutter:figma:analyze Invoked from orchestration

Parameters#

Parameter	Required	Description
`feature_name`	✅	Feature module name (snake_case)
`entity_name`	✅	Entity name (PascalCase)
`screen_type`	❌	`list`, `detail`, `form`

Generated Files#

⛔ feature 패키지(feature/{location}/{feature_name}/)에는 BDD 관련 파일이 전혀 들어가지 않습니다 — .feature도, test/src/bdd/도, build.yaml의 builder 블록도 없습니다. 전부 app/{app}/integration_test/에 모입니다:

app/{app}/integration_test/
├── features/
│   ├── {feature}_list.feature
│   ├── {feature}_detail.feature
│   └── {feature}_form.feature
├── step/                              # TestDriver 기반, 손으로 작성
│   ├── {feature}_list_steps.dart
│   ├── {feature}_detail_steps.dart
│   └── {feature}_form_steps.dart
└── scenarios/                         # Patrol 테스트 (손으로 작성, 유일한 실행 경로)
    ├── {feature}_list_{scenario}_test.dart
    ├── {feature}_detail_{scenario}_test.dart
    └── {feature}_form_{scenario}_test.dart

공유 step은 import 'package:test_driver/shared_steps.dart';로 시나리오 파일 상단에서 직접 가져다 씁니다 — build.yaml에 등록하는 코드 생성기 단계는 없습니다.

Core Patterns Summary#

Gherkin Rules#

Feature/Scenario title: Write in English with # 한글 번역 comment (e.g., Feature: Login Page # 로그인 페이지)
Scenario description: Write in English with # 한글 번역 comment
Step pattern: English required with # 한글 번역 comment (e.g., Given I am on the login page # 로그인 페이지에 있습니다)
Korean text as parameters: {'한글Value'} Format

Step Definition Rules#

Function name: English camelCase (iTapTheButton)
Usage 주석 병기: /// Usage: When I tap button + /// 용도: 버튼을 탭합니다
공용 스텝 재Usage: package:core/src/test/bdd/bdd.dart

Tag System#

Tag	Purpose
`@smoke`	Core functionality tests
`@validation`	Validation checks
`@navigation`	Page navigation
`@error`	Error handling

Scenarios by Screen Type#

List Screen#

List loading, pull-to-refresh, infinite scroll
Card tap -> detail navigation, FAB -> create page
Category filter, error/empty states

Detail Screen#

Detail display, like toggle
Edit/delete (author only), share

Form Screen#

Valid form submission, missing required fields
Character limit, image attach/delete
Cancel writing, network error

Checklist#

Feature/Scenario title: English with # 한글 번역 comment
Step pattern: English with # 한글 번역 comment
Korean comment: # 한글 번역 after every content line (Feature, Scenario, description, steps)
Function name: English camelCase
Shared steps: reuse core/bdd.dart
Tags: apply @smoke, @validation, etc.
No build.yaml / codegen step — .feature, step/*.dart, and scenarios/*_test.dart are hand-written under app/{app}/integration_test/ (⛔ bdd_widget_test/bdd_test_gen/ co_test_gen/dual_test_gen are retired — nothing generates these files, and none of them live inside the feature package)
Multi-field forms (3+ fields): values in a Given data table, submitted via a single When domain step — no one-When/And-per-field chains
Scenario Outline used only when the data variation itself is the thing under test — regular Scenario otherwise

BLoC Patterns - Test Pattern
Pattern Selection Guide