/marionette sweep — 화면 전수 점검 (한 번에 쭉 훑기)

Widgetbook 카탈로그나 화면 목록을 순회하며 각 항목을 캡처·조작하고, 반응 없는 항목을 표시합니다.

/marionette sweep — 화면 전수 점검 (한 번에 쭉 훑기)#

항목	내용
실행 명령	`/cc-marionette:sweep`
분류	Flutter
난이도	●●○ 보통
MCP 서버	`marionette`

한마디로#

앱의 화면(또는 부품)들을 하나하나 자동으로 눌러보고 사진을 찍어, "눌렀는데 아무 반응 없는" 것들을 골라내는 일괄 점검 도구입니다. 마치 매장 직원이 진열된 모든 제품의 버튼을 직접 눌러보며 "이건 고장났네" 하고 표시해 두는 것과 같아요.

누가·언제 쓰나요#

화면이나 UI 부품을 한꺼번에 점검해 반응 없는(고장난) 곳을 찾아내고 싶을 때
새 버전을 내보내기 전, 회귀 점검(이전에 멀쩡하던 게 망가지지 않았는지 확인)이 필요할 때
점검 대상은 두 가지 중 하나입니다: 디자인 부품 모음(coui) 또는 앱의 화면 목록(routes).

무엇을 해주나요#

점검이 끝나면 결과물이 한 폴더(.claude/docs/marionette/<run_id>/)에 정리되어 남습니다:

화면 사진 (screens/) — 각 항목을 누르기 전(_idle.png)과 누른 후(_after.png) 사진
눌러본 요소 목록 (interactive/<항목>.json) — 각 화면에서 어떤 버튼·입력칸을 건드렸는지
로그 (logs.txt) — 도중에 오류가 난 경우 그 흔적
요약 보고서 (summary.md) — 항목별로 "반응함 / 반응 없음 / 오류"를 한눈에 보는 표

이 도구는 문제를 찾아 증거를 남기기만 할 뿐, 직접 고치지는 않습니다. 발견된 문제는 다음 단계에서 이슈로 등록해 처리합니다.

어떻게 쓰나요#

# 디자인 부품 모음(coui)을 점검하되, 처음엔 20개만 (시험 삼아)
/marionette sweep --catalogue=coui --limit=20 --output=.claude/docs/marionette/coui-v2.3/

--catalogue (필수): 무엇을 점검할지. coui(디자인 부품) / routes(앱 화면 목록) / 직접 만든 목록 파일(YAML) 중 하나
--limit (선택): 한 번에 점검할 개수 제한. 처음 시험 삼아 돌릴 때 유용
--output (선택): 결과를 저장할 폴더 위치
--actions (선택): 부품 종류별 기본 동작을 바꾸고 싶을 때

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

목록에 있는 각 항목마다 아래 과정을 반복합니다:

해당 항목(화면·부품)으로 이동합니다.
건드리기 전 모습을 사진으로 찍어 둡니다 (_idle.png).
그 화면에서 누를 수 있는 요소들을 모두 찾아냅니다.
버튼은 누르고, 입력칸엔 글자를 넣고, 스위치는 켜는 식으로 종류에 맞는 동작을 한 번씩 해봅니다.
건드린 뒤 모습을 다시 사진으로 찍습니다 (_after.png).
두 사진을 비교합니다 — 똑같으면 "반응 없음"으로 표시, 달라지면 "정상", 오류가 났으면 로그를 함께 기록합니다.

이 점검은 한 번에 쭉 훑고 끝입니다(반복하며 고치지 않음). 결과 표를 보고 어디가 문제인지 파악하는 용도예요.

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

Parameters#

Parameter	Required	Description	Default
`--catalogue`	✅	`coui` (Widgetbook), `routes` (app router table), or a path to a YAML manifest	—
`--filter`	❌	컴포넌트/UseCase 이름으로 카탈로그를 한정 (예: `--filter=PrimaryButton` — 단일 컴포넌트 검증, 구 `verify-component` 흡수)	전체
`--limit`	❌	Cap on items processed (useful for first dry-run)	`unlimited`
`--output`	❌	Output dir	`.claude/docs/marionette/<ts>/`
`--actions`	❌	Override default smoke actions per type (YAML inline)	sensible defaults

Default Smoke Actions per Type#

Type	Action
`PrimaryButton` / `SecondaryButton` / others	`tap`
`Input` / `Textarea`	`enter_text("marionette-test")`
`Toggle` / `Switch` / `Checkbox`	`tap` (flip)
`Slider`	`tap` mid-track
`TabItem`	`tap`
`AccordionItem`	`tap` (expand)

⚠️ `--catalogue=coui` vs `--catalogue=routes` — 같은 액션, 다른 파괴력#

catalogue	무엇을 누르나	상태 변이
`coui` (Widgetbook)	스텁 컴포넌트	없음 — 자유롭게 쓸어도 된다
`routes` (앱 라우터)	실제 화면의 실제 저장/제출/삭제 버튼, 실제 토글	앱이 가리키는 백엔드에 그대로 기록된다

routes 로 스윕할 때는 백엔드가 무엇인지 먼저 확인한다:

로컬 격리(E0) → 그대로 진행
공유 스테이징(E1) → cc-quality:qa-environment-hygiene 필수. 저장/삭제 성격의 액션은 CBM(원본 선캡처) 없이는 실행하지 않고, 스윕 후 /cc-quality:cleanup 으로 정리한다. --limit 으로 범위를 좁히고 --actions 로 파괴적 액션을 제외하는 것을 우선 검토한다
실서비스(E2) → 스윕 금지

"The sweep is one-shot — no iteration. It produces evidence, not fixes." 는 소스 코드를 고치지 않는다는 뜻이지, 데이터를 바꾸지 않는다는 뜻이 아니다. routes 스윕은 데이터를 바꾼다.

Loop#

For each catalogue item:

Navigate to the item (tap on Widgetbook sidebar entry OR GoRouter.go(route)).
take_screenshots → screens/<item>_idle.png.
get_interactive_elements → interactive/<item>.json.
For each element, run the type's smoke action.
take_screenshots → screens/<item>_after.png.
Diff the two screenshots:
- identical → flag as "non-responsive" in summary.md.
- changed → record as "interactive".
- threw → collect get_logs excerpt around the timestamp.

Output#

.claude/docs/marionette/ < run_id > /
├── interactive/
│   └──  < item > .json
├── screens/
│   ├──  < item > _idle.png
│   └──  < item > _after.png
├── logs.txt
└── summary.md            # table of items × actions × result

Convergence#

The sweep is one-shot — no iteration. It produces evidence, not fixes. Use this output to open ZenHub issues; see cc-quality:bug-report for the next step.

Example#

/marionette sweep --catalogue=coui --limit=20 --output=.claude/docs/marionette/coui-v2.3/

[1/20] PrimaryButton → idle.png + after.png + 4 interactive elements
[2/20] SecondaryButton → idle.png + after.png + 4 interactive elements
...
[20/20] Toggle → idle.png + after.png + 2 interactive elements

Non-responsive: 1 (LinkButton.disabled — expected, see ADR-12)
Threw: 0
Report: .claude/docs/marionette/coui-v2.3/summary.md