# 시각 보조 도구 가이드

브레인스토밍 중 목업, 다이어그램, 비교안을 보여주기 위한 브라우저 기반 시각 보조 가이드입니다.

## 언제 사용할지

세션 단위가 아니라 질문 단위로 판단합니다. 기준은 하나입니다. **읽는 것보다 보는 것이 더 이해하기 쉬운가?**

**브라우저를 사용할 때**

- UI 목업, 와이어프레임, 레이아웃, 내비게이션 구조
- 시스템 구성도, 데이터 흐름도, 관계도
- 레이아웃이나 스타일의 시각적 비교
- 간격, 시각적 위계, 분위기 같은 디자인 완성도 논의
- 상태 전이, 흐름도, 엔터티 관계처럼 공간적 관계가 중요한 설명

**터미널을 사용할 때**

- 요구사항과 범위 질문
- 개념적 A/B/C 선택
- 장단점 비교와 트레이드오프 정리
- API 설계, 데이터 모델링, 구조 선택 같은 기술 의사결정
- 시각 취향이 아니라 언어 설명이 필요한 명확화 질문

UI 주제에 대한 질문이라고 해서 자동으로 시각 질문이 되는 것은 아닙니다. "어떤 종류의 위저드를 원하나요?"는 개념 질문이고, "이 위저드 레이아웃 중 무엇이 더 맞나요?"는 시각 질문입니다.

## 진행 방식

서버는 HTML 파일이 저장되는 디렉터리를 감시하고 가장 최근 파일을 브라우저에 제공합니다. 화면 내용은 `screen_dir`에 기록하고, 사용자의 클릭/선택 결과는 `state_dir/events`에 저장됩니다.

**콘텐츠 조각과 전체 문서**

- HTML이 `<!DOCTYPE` 또는 `<html`로 시작하면 전체 문서로 그대로 제공합니다.
- 그렇지 않으면 서버가 기본 프레임 템플릿으로 감싸서 보여줍니다.
- 기본적으로는 전체 HTML 문서보다 **콘텐츠 조각** 작성 방식을 사용합니다.

## 세션 시작

- 서버를 시작하고 응답에서 `url`, `screen_dir`, `state_dir`를 저장합니다.
- 사용자에게 URL을 열어 달라고 안내합니다.
- 가능하면 프로젝트 루트를 기준으로 실행해 결과물이 프로젝트 안에 유지되게 합니다.
- 환경상 URL 접근이 어렵다면 호스트 설정을 조정합니다.

## 반복 루프

1. 서버가 살아 있는지 확인하고 `screen_dir`에 새 HTML 파일을 씁니다.
2. 사용자에게 URL과 현재 화면에 무엇이 보이는지 짧게 설명합니다.
3. 사용자가 터미널에서 응답하면 `state_dir/events`를 읽어 브라우저 상호작용을 확인합니다.
4. 피드백에 따라 현재 화면을 수정하거나 다음 질문으로 넘어갑니다.
5. 다음 단계가 시각 자료가 아니라면 대기 화면을 밀어 넣어 오래된 화면이 남지 않게 합니다.

## 작성 원칙

- 파일명은 의미 있게 짓습니다. 예: `layout.html`, `visual-style.html`
- 같은 파일명을 재사용하지 않습니다.
- 한 화면에는 2~4개 선택지만 둡니다.
- 질문 자체를 화면에 명확히 적습니다.
- 레이아웃 검토에는 와이어프레임, 완성도 검토에는 더 실제적인 시안을 사용합니다.
- 필요한 경우 실제 콘텐츠를 사용하고, 불필요한 정교함은 피합니다.

## 이벤트 해석

브라우저 클릭 이벤트는 `state_dir/events`에 JSON Lines 형식으로 기록됩니다. 마지막 선택이 최종 선택인 경우가 많지만, 선택 흐름 전체가 사용자의 망설임이나 선호를 보여줄 수 있습니다.

## 정리

- 세션 종료 시 서버를 중지합니다.
- 프로젝트 기반 세션이라면 결과물은 이후 참고를 위해 남겨둘 수 있습니다.