marionette:sweep

Walk a Widgetbook catalogue or route table; screenshot + interact with each item; flag non-responsive ones.

항목	내용
Invoke	/marionette:sweep
Category	cocode-flutter
Complexity	moderate
MCP Servers	marionette

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

한마디로#

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

누가·언제 쓰나요#

화면이나 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	—
`--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)

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-code-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