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

7.3 KiB Raw Blame History