180 lines
11 KiB
Markdown
180 lines
11 KiB
Markdown
---
|
|
name: create-agent-ui
|
|
version: 1.1.0
|
|
description: 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 최초 코드 동기화 기준선을 생성하는 스킬
|
|
---
|
|
|
|
# create-agent-ui
|
|
|
|
## 목적
|
|
|
|
프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 `agent-ui/` 기본 구조와 UI 정의 초안을 생성한다.
|
|
ops/dev UI를 1차 대상으로 하며, 생성 결과를 최초 agent-ui 기준선으로 보고 `.sync-state.json`을 만든다.
|
|
|
|
## 언제 호출할지
|
|
|
|
- 사용자가 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 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다.
|
|
- [ ] baseline commit/push를 위해 현재 git status와 HEAD를 확인한다.
|
|
- [ ] unrelated dirty worktree가 있으면 baseline commit 전에 범위를 보고하고, agent-ui 생성 파일만 stage한다.
|
|
|
|
## 실행 절차
|
|
|
|
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/<view-id>/index.md`
|
|
- view 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다.
|
|
- 코드 근거가 있으면 `status: 구현됨`
|
|
- 문서 근거만 있으면 `status: 계획`
|
|
- 명시 입력만 있고 근거가 부족하면 `status: 가정`
|
|
- 판단 불가하면 `status: 불명확`과 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/<view-id>/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/<component-id>/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. **정합성 검증과 baseline 기록**
|
|
- 생성 직후 `validate-agent-ui`를 실행해 scaffold와 문서 간 정합성을 확인하고 자동 보정한다.
|
|
- `agent-ui/.sync-state.json`에 기록할 baseline 내용을 준비한다.
|
|
- `baseline_mode`는 선택된 `source-mode`로 둔다.
|
|
- `code-first`, `concept-first`, `blank` 모두 생성된 agent-ui를 최초 기준선으로 본다.
|
|
- baseline commit은 두 단계로 남긴다.
|
|
- 먼저 `.sync-state.json`을 제외한 agent-ui 생성/보정 파일을 commit한다.
|
|
- 그 commit hash를 새 `agent-ui/.sync-state.json`의 `last_synced_head`에 기록한 뒤 별도 commit한다.
|
|
- commit message는 예를 들어 `docs(agent-ui): create baseline`과 `sync: record agent-ui baseline`처럼 목적이 분리되게 쓴다.
|
|
- 두 commit을 push한다.
|
|
- USER_REVIEW가 생성되어도 생성 baseline은 남길 수 있다. 단, 이후 `sync-agent-ui`는 관련 USER_REVIEW가 해결될 때까지 실행하지 않는다.
|
|
|
|
9. **결과 보고**
|
|
- 선택된 `source-mode`
|
|
- 읽은 근거 파일과 생성에 사용한 evidence
|
|
- 생성한 파일
|
|
- 적용한 frontmatter schema
|
|
- 생성한 view/component의 status
|
|
- USER_REVIEW 생성 여부
|
|
- `.sync-state.json` 생성 여부와 baseline commit hash
|
|
- baseline commit/push 결과
|
|
- 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`가 있는가
|
|
- [ ] 구현 근거 없는 항목을 `구현됨`으로 표시하지 않았는가
|
|
- [ ] visual source가 없는 view에 빈 `frame/views/<view-id>/index.md`를 만들지 않았는가
|
|
- [ ] 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
|
|
- [ ] 같은 레벨에 `<name>.md`와 `<name>/`가 함께 생기지 않았는가
|
|
- [ ] archive 본문 파일을 불필요하게 생성하지 않았는가
|
|
- [ ] `validate-agent-ui` 결과가 PASS 또는 자동 보정 완료 WARN으로 보고되었는가
|
|
- [ ] `.sync-state.json`이 생성되었고 `last_synced_head`가 baseline commit을 가리키는가
|
|
- [ ] baseline commit/push가 완료되었는가
|
|
- [ ] unrelated dirty file이 baseline commit에 포함되지 않았는가
|
|
- 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.
|
|
|
|
## 출력 형식
|
|
|
|
```md
|
|
## 생성 완료
|
|
|
|
- 루트: agent-ui/
|
|
- source-mode: <code-first|concept-first|blank>
|
|
- evidence: <주요 근거 파일 목록>
|
|
- 생성 파일: <목록>
|
|
- frontmatter schema: <적용/부분 적용/없음>
|
|
- views: <view-id=status 목록 또는 없음>
|
|
- components: <component-id=status 목록 또는 없음>
|
|
- USER_REVIEW: <생성/없음>
|
|
- sync state: <생성/없음, last_synced_head>
|
|
- baseline commit/push: <완료/실패/생략 사유>
|
|
- 확인 필요: <항목 또는 없음>
|
|
- 후속 권장: <필요 시 sync-agent-ui 또는 없음>
|
|
```
|
|
|
|
## 금지 사항
|
|
|
|
- 기존 `agent-ui/` 문서를 덮어쓰지 않는다.
|
|
- `.excalidraw` 파일을 현재 UI source of truth로 만들지 않는다.
|
|
- 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
|
|
- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
|
|
- product UI 전용 레이어를 요청 없이 추가하지 않는다.
|
|
- `definition/archive/**`나 `archive/user-review/**`에 현재 기준 문서를 만들지 않는다.
|
|
- baseline commit 없이 `.sync-state.json`의 `last_synced_head`를 추정하지 않는다.
|