95 lines
4 KiB
Markdown
95 lines
4 KiB
Markdown
# 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`를 사용한다.
|