--- name: create-agent-ui version: 1.1.0 description: 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 동기화된 UI 정의 초안을 생성하는 스킬 --- # create-agent-ui ## 목적 프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 `agent-ui/` 기본 구조와 UI 정의 초안을 생성한다. ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분해 AI와 사람이 UI 의도를 동기화할 수 있게 만든다. ## 언제 호출할지 - 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때 - 프로젝트에 `agent-ui/`가 없고 기존 코드 또는 문서에서 UI 정의 문맥을 추출할 때 - UI 코드가 있으면 구현 상태와 동기화된 view/component/frame 초안이 필요할 때 - UI 코드가 아직 부족하면 README, roadmap, SDD, docs 같은 컨셉 문서 기반 최소 view tree가 필요할 때 ## 입력 - `surface-type`: `ops-dev` 또는 `product`. 기본값은 `ops-dev` (선택) - `source-mode`: `auto`, `code-first`, `concept-first`, `blank` 중 하나. 기본값은 `auto` (선택) - `views`: 초기 생성할 view id 목록, kebab-case (선택) - `components`: 초기 생성할 component id 목록, kebab-case 또는 path id (선택) ## 먼저 확인할 것 - [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다. - [ ] 생성 대상 `agent-ui/` 존재 여부를 확인한다. - [ ] 기존 `agent-ui/`가 있으면 덮어쓰지 않고 `update-agent-ui` 또는 `validate-agent-ui` 대상인지 보고한다. - [ ] 템플릿 경로 `agent-ops/skills/common/_templates/agent-ui/` 하위 파일을 확인한다. - [ ] `source-mode=auto`이면 UI 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다. ## 실행 절차 1. **생성 대상 확정** - 생성 루트는 `agent-ui/`로 고정한다. - `surface-type`이 없으면 `ops-dev`로 둔다. - `source-mode`가 없으면 `auto`로 둔다. - product UI가 명시되어도 기본 구조는 유지하고 product 전용 레이어는 요청된 경우에만 추가 후보로 보고한다. 2. **근거 수집** - `code-first` 또는 `auto`에서는 UI 구현 후보를 찾는다. - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일 - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다. - 코드가 많으면 전체 정독하지 말고 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다. - `concept-first` 또는 `auto`에서는 컨셉 문서 후보를 찾는다. - 예: `README.md`, `docs/**`, `agent-roadmap/current.md`, 활성 Phase/Milestone, 승인된 SDD, `agent-ops/rules/project/rules.md` - roadmap 문서는 `agent-ops/rules/common/rules-roadmap.md`의 loading/archive 접근 규칙을 따른다. - archive 문서는 사용자가 과거 근거를 명시하지 않는 한 읽지 않는다. - 근거가 없거나 사용자가 빈 구조를 요청하면 `blank`로 처리한다. 3. **source-mode 결정** - `auto`에서 route, shell, page/view, widget/component 후보 중 하나 이상이 실제 파일 경로로 확인되면 `code-first`로 생성한다. - UI 구현 후보가 부족하고 컨셉 문서 후보가 있으면 `concept-first`로 생성한다. - 코드와 문서 근거가 모두 부족하면 `blank`로 생성하고 부족한 근거를 결과에 보고한다. - 명시된 `views` 또는 `components`는 선택된 mode와 함께 생성 후보로 반영한다. 4. **기본 구조 생성** - 다음 활성 문서를 템플릿 기준으로 만든다. - `agent-ui/README.md` - `agent-ui/definition/index.md` - `agent-ui/definition/views/index.md` - `agent-ui/definition/components/index.md` - `agent-ui/frame/index.md` - 생성하는 활성 Markdown 문서에는 `rules-agent-ui.md`의 Frontmatter Schema를 적용한다. - 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 `.gitkeep`을 둘 수 있다. - `agent-ui/definition/archive/views/` - `agent-ui/definition/archive/components/` - `agent-ui/archive/user-review/` - `USER_REVIEW.md`는 사용자 판단 항목이 있을 때만 만든다. 5. **초기 view 생성** - `code-first`에서는 구현 코드에서 확인된 route/page/view/shell 단위를 view 후보로 만든다. - `concept-first`에서는 문서에서 확인된 운영 업무, 화면, 콘솔 영역을 view 후보로 만든다. - `blank`에서는 명시 `views`가 있을 때만 view 후보를 만든다. - 각 view 후보마다 다음 문서를 만든다. - `agent-ui/definition/views//index.md` - view 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다. - 코드 근거가 있으면 `status: implemented` - 문서 근거만 있으면 `status: planned` - 명시 입력만 있고 근거가 부족하면 `status: assumed` - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다. - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다. - visual source가 없는 초기 view 문서의 frontmatter `frame`은 `null`로 둔다. - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 같은 기준을 말하게 작성한다. - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다. - `.excalidraw` 또는 다른 visual source를 만들거나 연결할 때만 `agent-ui/frame/views//index.md`를 만든다. - `.excalidraw`를 만들거나 연결하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다. - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다. 6. **초기 component 생성** - `code-first`에서는 반복 widget/component/table/filter/log/status/action 단위를 component 후보로 만든다. - `concept-first`에서는 문서상 반복 패턴이 분명한 data table, status badge, filter bar, log viewer 같은 구성요소만 component 후보로 만든다. - `blank`에서는 명시 `components`가 있을 때만 component 후보를 만든다. - 각 component 후보마다 `agent-ui/definition/components//index.md`를 만든다. - component 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다. - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다. - component id가 path id이면 하위 디렉터리 구조로 만든다. - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다. 7. **불확실성 분리** - 코드와 문서가 충돌하면 임의로 통합하지 않고 `agent-ui/USER_REVIEW.md`에 남긴다. - view 경계, component 신규 생성 여부, page/drawer/split 같은 UX 판단은 USER_REVIEW로 남긴다. - 문서 근거만 있는 계획 항목을 구현 완료처럼 쓰지 않는다. 8. **결과 보고** - 선택된 `source-mode` - 읽은 근거 파일과 생성에 사용한 evidence - 생성한 파일 - 적용한 frontmatter schema - 생성한 view/component의 status - USER_REVIEW 생성 여부 - product UI 확장 후보 - 후속 권장 작업 ## 실행 결과 검증 - [ ] `agent-ui/README.md`가 생성되었는가 - [ ] `definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md`가 생성되었는가 - [ ] 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가 - [ ] view/component는 folder-first + `index.md` 구조를 사용하는가 - [ ] 생성한 view/component에 `Source Evidence`와 `Status`가 있는가 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가 - [ ] visual source가 없는 view에 빈 `frame/views//index.md`를 만들지 않았는가 - [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가 - [ ] 같은 레벨에 `.md`와 `/`가 함께 생기지 않았는가 - [ ] archive 본문 파일을 불필요하게 생성하지 않았는가 - 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다. ## 출력 형식 ```md ## 생성 완료 - 루트: agent-ui/ - source-mode: - evidence: <주요 근거 파일 목록> - 생성 파일: <목록> - frontmatter schema: <적용/부분 적용/없음> - views: - components: - USER_REVIEW: <생성/없음> - 확인 필요: <항목 또는 없음> - 후속 권장: validate-agent-ui 실행 ``` ## 금지 사항 - 기존 `agent-ui/` 문서를 덮어쓰지 않는다. - `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다. - 코드나 문서 근거 없이 화면 의도를 확정하지 않는다. - 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다. - product UI 전용 레이어를 요청 없이 추가하지 않는다. - `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다.