# agent-ui 규칙

`agent-ui/`가 있는 프로젝트 또는 agent-ui 생성, 갱신, 검증 요청에서 적용한다.

## 목적

`agent-ui/`는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.
초기 기준은 ops/dev UI이며, product UI는 같은 구조 위에 brand, content, assets, tokens, motion 같은 레이어를 추가할 수 있다.

## 기본 구조

```text
agent-ui/
  README.md
  USER_REVIEW.md                  # 선택: 사용자 판단이 필요한 활성 리뷰
  archive/
    user-review/
      user_review_001.log

  definition/
    index.md
    views/
      index.md
      <view-id>/
        index.md
    components/
      index.md
      <component-id>/
        index.md
    archive/
      views/
        <view-id>/
          index.log
      components/
        <component-id>/
          index.log

  frame/
    index.md
    views/
      <view-id>/
        index.md                   # visual source가 있을 때만 생성
        wire.excalidraw            # 선택: 1차 visual source 후보
```

## Source of Truth

- `agent-ui/definition/**`은 현재 UI 정의의 source of truth다.
- `agent-ui/frame/**`은 와이어프레임과 visual source를 연결하는 보조 자료다.
- visual source가 없는 view는 `frame/views/<view-id>/`를 만들지 않는다. view 문서의 `frame`은 `null`로 둔다.
- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. visual source가 있으면 반드시 대응되는 `frame/views/<view-id>/index.md`가 있어야 한다.
- `frame/views/<view-id>/index.md`는 대응되는 `definition/views/<view-id>/index.md`를 가리켜야 한다.
- 화면 의도, 상태, 액션, 정보 우선순위는 definition에 둔다.
- 배치, 밀도, 시각적 영역 관계는 frame에 둔다.
- 생성된 view/component는 코드, 문서, 사용자 입력 중 어떤 근거에서 왔는지 `Source Evidence`에 남긴다.
- 구현 코드에서 확인된 항목은 `implemented`, 문서 계획에서 온 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 표시한다.
- `planned`, `assumed`, `unknown` 항목을 구현 완료처럼 설명하지 않는다.

## Frontmatter Schema

- 활성 Markdown 문서는 YAML frontmatter를 둔다.
- `ui_doc_type`은 `readme`, `definition-index`, `views-index`, `view`, `components-index`, `component`, `frame-index`, `frame-view`, `user-review`, `archive-log` 중 하나다.
- definition-index 문서는 `surface_type`, `source_evidence`를 둘 수 있다.
- view 문서는 `view_id`, `status`, `frame`, `source_evidence`를 둔다.
- component 문서는 `component_id`, `status`, `source_evidence`를 둔다.
- view 문서의 `frame`은 frame-view 문서가 있으면 경로, 없으면 `null`로 둔다.
- frame-view 문서는 visual source가 있을 때만 만들며 `view_id`, `definition`, `visual_source`, `regions`를 둔다.
- `status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나다.
- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다.
- `source_evidence.type`은 `code`, `docs`, `user` 중 하나다.
- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다.
- view에 visual source가 없으면 view 문서의 `frame`을 `null`로 두고 frame-view 문서를 만들지 않는다.
- frame-view를 만들 때 `visual_source`는 실제 존재하는 visual source 경로여야 한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다.
- `implemented`는 존재하는 `code` evidence path가 있을 때만 사용한다.
- `planned`는 문서 근거만 있을 때, `assumed`는 사용자 명시 입력만 있을 때, `unknown`은 근거나 판단이 부족할 때 사용한다.
- frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다.
- frontmatter는 기계적 검증을 위한 최소 schema이고, 본문 Markdown은 사람과 agent가 읽는 설명을 유지한다.

## 명명 규칙

- view id, component id, 파일명, 디렉터리명은 kebab-case를 사용한다.
- view 기준 문서는 `definition/views/<view-id>/index.md`에 둔다.
- component 기준 문서는 `definition/components/<component-id>/index.md`에 둔다.
- 같은 레벨에서 `<name>.md`와 `<name>/`를 함께 두지 않는다.
- 하위 정의가 필요하면 `<name>/index.md`와 `<name>/<child>.md`를 사용한다.

## ID 규칙

- region id는 `<view-id>.<region>` 형식을 사용한다.
- 하위 region은 `<view-id>.<region>.<subregion>` 형식을 사용할 수 있다.
- component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`.
- frame-view가 있으면 view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다.
- view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다.
- frame-view가 있으면 frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다.

## Archive 접근

- `agent-ui/definition/archive/**`는 일반 작업에서 읽지 않는다.
- `agent-ui/archive/user-review/**`는 일반 작업에서 읽지 않는다.
- 예외: 사용자가 과거 결정 확인, 복원, 비교, 특정 archive 경로 확인, 해결된 user review 확인을 요청한 경우에만 필요한 파일을 좁게 읽는다.
- validate 작업은 archive 경로 존재 여부와 tree 대응 여부를 확인할 수 있지만, 위 예외가 없으면 archive 본문을 읽지 않는다.

## USER_REVIEW

- agent가 확정할 수 없는 UI 의도, 화면 구조, region 추가/삭제, component 신규 생성 여부, page/drawer/split 같은 UX 결정은 `agent-ui/USER_REVIEW.md`에 남긴다.
- 해결된 user review는 `agent-ui/archive/user-review/user_review_N.log`로 이동할 수 있다.
- `USER_REVIEW.md`가 있으면 관련 agent-ui 갱신이나 검증 결과에 남은 review id를 보고한다.

## Excalidraw

- 1차 visual source 후보는 `wire.excalidraw`다.
- VS Code Excalidraw extension은 초기 편집 워크플로우로 사용할 수 있다.
- excalidraw.com import/export 워크플로우는 기본 표준으로 삼지 않는다.
- Excalidraw self-host는 R&D 후보이며, 기본 agent-ui scaffold의 필수 조건이 아니다.
- `.excalidraw`는 JSON으로 다룬다. 검증 시 가능하면 JSON parser로 `elements`의 text label 또는 `customData.region_id`를 확인한다.
- visual source에 region label이 있으면 `frame-view.regions`와 `definition` region id의 집합과 비교한다.
- visual source가 있는데 region label이 없으면 frame과 definition의 연결 근거가 부족한 상태로 본다.
- visual source에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동으로 UI 의도를 확정하지 않고 USER_REVIEW로 남긴다.

## 스킬

- agent-ui 초기 scaffold 생성은 `create-agent-ui`를 사용한다.
- view, component, frame 갱신은 `update-agent-ui`를 사용한다.
- 구조와 정합성 검사, 자동 보정, USER_REVIEW 생성은 `validate-agent-ui`를 사용한다.