Widget Previewer를 Human/AI 친화적으로 만든 CLI 도구, shutter

$ shutter shot lib/preview/button_preview.dart
# shutter ai-report v1
run: /path/to/example/.dart_tool/shutter/runs/20260920T105416Z
...

$ shutter diff latest~1 latest --images
# shutter ai-report v1
diff: /path/to/example/.dart_tool/shutter/diffs/20260920T105442Z
...

shutter shot --widget 'PrimaryButton(label:

AI 에이전트에게 맡긴다는 관점에서도, 기준 이미지가 없는 설계에는 의미가 있습니다. golden test를 AI가 처리하게 하면, 차이가 발생했을 때 '기준 이미지를 업데이트했습니다'로 끝내버리는 경우가 있습니다. `shutter`는 업데이트할 기준 자체가 없기 때문에, 이러한 속임수의 경로가 없습니다. 대신 차이 이미지(diff image)가 남게 되므로, 판단의 근거 자료는 사람에게 돌아오게 됩니다.

## AI 에이전트에게 전달하기

`shutter`는 AI 에이전트가 사용한다는 전제하에 설계되었습니다.

### 플레이북을 바이너리에 포함

`shutter agent`를 실행하면, 절차서(playbook)가 출력됩니다. 피사체를 정하고, 편집 전에 촬영하고, 편집한 후에 다시 촬영하며, `diff`를 읽는 흐름입니다. `shutter manual`은 개념적인 참고 자료입니다.

문서를 바이너리에 포함하는 이유는 설치된 버전과 절차서의 내용이 어긋나지 않도록 하기 위함입니다. 그리고 또 하나, AI가 사용법을 모른다고 떼쓰는 상황을 피하기 위해서이기도 합니다. AI 입장에서 `shutter`는 미지의 패키지이기 때문에, 틀림없이 '저는 사용법을 모릅니다'라며 헤매게 됩니다. 이를 방어하는 장치입니다.

패키지에는 agent skill인 `shutter-visual-check`도 포함되어 있습니다.

만드는 과정에서 Flutter SDK 측에 느낀 점을 적어두겠습니다.

현재 v1은 Widget Previewer가 이미지를 출력할 수 없다는 전제하에, `flutter test`를 경유하여 렌더링하고 있습니다. 이는 임시방편의 축적일 뿐, 이상적인 설계는 아닙니다. Font 문제, `flutter/material.dart`가 `material_ui/material_ui.dart`로 마이그레이션되는 문제 등 여러 문제를 거치고 있습니다. 또한, Widget Previewer가 `lib/` 디렉토리 아래만 볼 수 있다는 제약 등의 영향도 받고 있습니다.

이러한 문제들의 대부분은 `flutter widget-preview`가 `ui.Image`를 출력해 준다면 해결될 것입니다. `shutter`의 내부 구조는 엔진 계층을 교체할 수 있도록 분리되어 있기 때문에, SDK 측 개선이 이루어지면 run이나 diff의 설계를 변경하지 않고도 대체할 수 있습니다.[3]

세상이 AI에 의한 구현을 지원하는 방향으로 가고 있기 때문에, 지식을 쌓아간다면 좋은 방향으로 나아갈 것 같은 느낌입니다. Widget Previewer는 흥미로운 메커니즘이므로, 관심 있는 분들은 꼭 사용해 보세요.

## 맺음말

`shutter`는 Flutter 개발 루프에서 사람의 손에 남기 쉬웠던 '시각적 확인'을 이미지라는 형태로 기계에게 전달하려는 시도입니다. 사람이 직접 테스트해도 편리하고, AI 에이전트에게 전달해도 동일하게 작동합니다. 외관과 관련된 변경 사항을 AI에게 맡기고 계신 분들은 꼭 사용해 보세요.

agent skill의 사용 편의성이나 PR에 붙여넣는 기능에 대해서는 필자도 아직 감을 잡지 못했습니다. 사용해보시고 느낀 점이나 요청사항이 있다면 꼭 보내주세요. 기다리겠습니다!

### 토론
![](https://static.zenn.studio/images/drawing/discussion.png)