agent-ui 규칙

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

목적

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

기본 구조

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를 사용한다.

4 KiB Raw Blame History