---
ui_doc_type: readme
surface_type: ops-dev
---

# agent-ui

이 디렉터리는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.

## 대상

- 1차 대상: ops/dev UI
- 확장 후보: product UI

## 구조

- `definition/`: 현재 UI 정의 source of truth
- `frame/`: visual source가 있는 view의 wireframe 연결
- `.sync-state.json`: agent-ui -> code 동기화 기준점, plan/Milestone pending 매핑, 완료 정합화 기록
- `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문
- `archive/user-review/`: 해결된 사용자 리뷰 로그

## 기본 규칙

- 현재 기준은 `definition/**`에 둔다.
- visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다.
- `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다.
- 초기 생성 이후 기본 흐름은 `agent-ui -> code` 방향이다.
- plan-required 코드 작업은 `.sync-state.json.pending_code_work`로 연결하고 일반 code-review 완료 뒤 `sync-agent-ui`가 정합화한다.
- milestone-required 코드 작업은 `.sync-state.json.pending_milestone_work`로 연결하고 Milestone 종료 직전에 `sync-agent-ui`가 정합화한다.
- `sync-agent-ui`의 state transition은 bundled helper가 담당하며 frame-view는 status 전환 대상이 아니다.
- `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다.
