# 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
        wire.excalidraw            # 선택: 1차 visual source 후보
```

## Source of Truth

- `agent-ui/definition/**`은 현재 UI 정의의 source of truth다.
- `agent-ui/frame/**`은 와이어프레임과 visual source를 연결하는 보조 자료다.
- `.excalidraw` 파일만으로 현재 UI 기준을 확정하지 않는다. 반드시 대응되는 `frame/views/<view-id>/index.md`가 있어야 한다.
- `frame/views/<view-id>/index.md`는 대응되는 `definition/views/<view-id>/index.md`를 가리켜야 한다.
- 화면 의도, 상태, 액션, 정보 우선순위는 definition에 둔다.
- 배치, 밀도, 시각적 영역 관계는 frame에 둔다.

## 명명 규칙

- 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`.
- view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다.
- view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다.

## 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의 필수 조건이 아니다.

## 스킬

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