oto/agent-ops/rules/common/rules-agent-ui.md

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