--- name: validate-agent-ui version: 1.1.0 description: agent-ui scaffold, definition/frame/component/wireframe/source evidence/status 정합성을 맞추고 필요한 USER_REVIEW와 code sync intent를 분리하는 스킬 --- # validate-agent-ui ## 목적 `agent-ui/` 구조와 문서 그래프 정합성을 검사하고 자동 보정한다. definition, component, frame, visual source, USER_REVIEW, archive가 서로 뒤처진 상태를 같은 수준으로 맞추며, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다. ## 언제 호출할지 - agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때 - view/component/frame 문서가 서로 어긋났는지 확인할 때 - view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때 - Excalidraw visual source와 frame index 연결을 검사할 때 - agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때 - 수동 호출에서 정합성 통과 후 code sync가 필요한지 판단할 때 - 사용자가 "화면정의서와 코드가 안 맞아"처럼 UI 정의와 코드 결과물의 불일치를 보고할 때 ## 입력 - `scope`: `all`, `internal`, `implementation`, `view:`, `component:`, `frame:` 중 하나. 기본값은 `all` (선택) - `repair`: `true` 또는 `false`. 기본값은 `true` (선택) - `sync-intent`: `auto`, `required`, `skip`, `inherited` 중 하나. 기본값은 수동 호출에서 `auto`, `update-agent-ui` 후속 호출에서 `inherited` (선택) - `sync-mode`: `incremental` 또는 `full`. 기본값은 `incremental` (선택) ## 먼저 확인할 것 - [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다. - [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다. - [ ] `agent-ui/definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md` 존재 여부를 확인한다. - [ ] scope에 해당하는 활성 definition/frame 문서만 읽는다. - [ ] `scope=view:` 또는 `scope=component:`이면 해당 문서의 Source Evidence code path를 확인한다. - [ ] `scope=all`, `scope=implementation` 또는 sync intent가 있으면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다. - [ ] `agent-ui/.sync-state.json`이 있으면 읽고, 없으면 sync 기준 없음으로 보고한다. - [ ] archive는 경로와 tree 대응만 확인하고, 사용자가 과거 내용 확인을 요청하지 않았으면 본문을 읽지 않는다. - [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다. ## 실행 절차 1. **인벤토리 작성** - `definition/views/**/index.md`에서 view 목록을 만든다. - `definition/components/**/index.md`에서 component 목록을 만든다. - `frame/views/**/index.md`에서 frame 목록을 만든다. frame이 없는 view는 visual source가 없는 정상 상태로 본다. - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`, id, status, source_evidence, regions를 수집한다. - 같은 레벨의 `.md`와 `/` 혼재 여부를 확인한다. 2. **구조 검증과 자동 보정** - 필수 루트 문서가 없고 `repair=true`이면 템플릿으로 생성한다. - view/component 디렉터리에 `index.md`가 없고 의도가 명확하면 템플릿으로 생성한다. - frame 디렉터리는 visual source가 있을 때만 `index.md` 생성 대상으로 삼는다. - `.excalidraw` 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다. - archive/user-review 디렉터리가 없고 필요하면 생성한다. - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다. 3. **definition 정합성 검사** - 활성 Markdown 문서에 `ui_doc_type` frontmatter가 있는지 확인한다. - `ui_doc_type`이 경로와 맞는지 확인한다. 예: `definition/views//index.md`는 `view`다. - view/component/frame id가 경로 id와 일치하는지 확인한다. - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다. - frontmatter `source_evidence`는 list이고 각 항목은 `type`, `path`, `notes`를 가져야 한다. - `source_evidence.type`은 `code`, `docs`, `user` 중 하나여야 한다. - 근거 파일이 없으면 `path: null`이어야 하며, placeholder 문자열을 근거로 보지 않는다. - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하는지 확인한다. - `Status`는 `구현됨`, `계획`, `가정`, `불명확` 중 하나여야 한다. - `구현됨` 항목은 코드 반영 완료 상태여야 한다. 코드 근거가 있으면 실제 존재하는 code evidence path를 가져야 한다. - `구현됨`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `계획`으로 낮추고 USER_REVIEW를 남길 수 있다. - `가정`, `불명확` 항목이 코드 동기화 가능한 정의처럼 설명되면 자동 의미 변경하지 않고 USER_REVIEW로 남긴다. - region id가 `.` 또는 `..` 형식인지 확인한다. - view 문서에서 참조한 component id가 component 목록에 있는지 확인한다. - 없는 component가 단순 누락이고 생성 의도가 명확하면 `repair=true`일 때 component skeleton을 만들고 `Status`와 `Source Evidence`를 채운다. - 새 component로 만들지 기존 component로 바꿀지 판단이 필요하면 USER_REVIEW로 남긴다. 4. **frame 정합성 검사** - view가 있는데 대응 frame index가 없어도 visual source가 없으면 정상으로 본다. - visual source 파일이 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다. - frame index가 있는데 `visual_source: null`이고 해당 view 아래 visual source 파일도 없으면 `repair=true`일 때 빈 frame index 삭제 후보로 본다. - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다. - `visual_source`가 `null`이면 legacy/empty frame 후보로 보고 visual source 파일 존재 여부를 함께 확인한다. - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다. - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다. - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다. - Excalidraw region id 후보가 없고 frame required region이 있으면 USER_REVIEW로 남긴다. - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다. - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다. - frame required region과 view definition region을 비교한다. - visual source가 있는 frame index에서 definition region이 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다. - 기존 frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다. - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다. 5. **구현 정합성 검사** - `scope=view:` 또는 `scope=component:`이면 해당 문서의 `source_evidence` 중 `type: code` 경로만 확인하고 전체 코드 후보 스캔은 하지 않는다. - `scope=all` 또는 `scope=implementation`이면 전체 view/component의 `source_evidence` 중 `type: code` 경로가 실제 존재하는지 확인한다. - 실제 UI 구현 후보를 찾는다. - 이 후보 스캔은 `scope=all` 또는 `scope=implementation`일 때만 수행한다. - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일 - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다. - 코드가 많으면 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다. - 운영 단계에서는 코드 후보만 보고 agent-ui view/component를 새로 만들지 않는다. - 코드 후보가 명확한 route/page/view/shell인데 agent-ui에 대응 view가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다. - 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action인데 agent-ui에 대응 component가 없으면 USER_REVIEW로 남기거나, 사용자가 코드 기준 반영을 명시한 경우 `update-agent-ui`로 돌린다. - 코드 결과물이 `구현됨` 상태의 agent-ui 정의와 어긋난다는 사용자 보고가 있으면 해당 항목을 `계획`으로 낮추고 sync intent를 만든다. - 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다. - 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `구현됨`을 `계획`으로 낮출 수 있다. 6. **USER_REVIEW 생성 또는 갱신** - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다. - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다. - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다. - 항목에는 `Source Skill: validate-agent-ui`, `Stage: document-consistency`, `Blocking Step`, Context, Options, Needed For를 포함한다. 7. **code sync intent 판정** - `sync-intent=inherited`이면 `update-agent-ui`가 전달한 판단을 그대로 사용하고 재판단하지 않는다. - 수동 호출이거나 `sync-intent=auto`이면 agent-ui 변경분과 `계획` 상태 항목을 보고 `sync-agent-ui` 필요 여부를 판단한다. - `sync-intent=required`이면 validate 결과가 PASS 또는 자동 보정 완료 WARN이고 현재 범위에 미해결 USER_REVIEW가 없을 때 `sync-agent-ui`를 실행한다. - `sync-intent=skip`이면 code sync 필요 여부를 보고만 하고 실행하지 않는다. - 현재 범위에 `가정` 또는 `불명확` 항목이 있거나 미해결 USER_REVIEW가 있으면 `sync-agent-ui`를 실행하지 않는다. - `sync-agent-ui`를 실행할 때는 이 스킬의 보정 결과를 입력으로 넘기고, 순서를 바꾸지 않는다. 8. **결과 판정** - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태 - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태 - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태 ## 자동 수정 허용 범위 - 누락된 필수 디렉터리와 index 문서 생성 - 명확한 단일 후보 visual source 등록 - 명확한 단일 후보 상대 링크 보정 - visual source가 있는 frame index의 region 누락 보완 - 빈 archive/user-review 디렉터리 생성 - 템플릿 필수 섹션과 frontmatter 누락 보완. `ui_doc_type`, `Source Evidence`, `Status` 누락 포함 - 명시된 code evidence 경로가 실제 존재하지 않는 `구현됨`을 `계획`으로 낮추고 USER_REVIEW를 남기는 보정 ## USER_REVIEW 대상 - 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우 - frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우 - component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우 - 운영 단계에서 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우 - 운영 단계에서 코드에만 있는 view/component를 agent-ui에 반영할지 판단이 필요한 경우 - 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우 - `계획` 항목을 코드로 반영하려 했지만 구현 방향, 환경, 권한, 검증 실패를 에이전트가 해결하지 못한 경우 - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우 - drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우 ## 실행 결과 검증 - [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가 - [ ] 활성 Markdown 문서가 유효한 `ui_doc_type` frontmatter를 갖는가 - [ ] folder-first + `index.md` 구조가 유지되는가 - [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가 - [ ] 명시된 code evidence 경로가 깨진 `구현됨`이 남아 있지 않은가 - [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보와 agent-ui 불일치가 sync intent 또는 USER_REVIEW로 분리되었는가 - [ ] view/component/frame 참조가 끊기지 않는가 - [ ] visual source가 없는 view는 frame 참조가 `null`이거나 비어 있는 frame-view가 없는가 - [ ] 자동 수정한 파일 목록이 보고되는가 - [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가 - [ ] archive 본문을 일반 검증에서 읽지 않았는가 - 검증 실패 시: 판정을 `FAIL`로 보고하고 자동 수정하지 못한 이유를 남긴다. ## 출력 형식 ```md ## agent-ui 검증 결과: - Scope: - Auto Fixed: <파일/항목 목록 또는 없음> - User Review: - Remaining Issues: <목록 또는 없음> - Checked Files: <활성 파일 목록> - Sync Intent: - sync-agent-ui: <실행/보류/생략 사유> ``` ## 금지 사항 - UI 의도 판단이 필요한 문제를 자동 수정하지 않는다. - archive 본문을 일반 검증 컨텍스트로 읽지 않는다. - `.excalidraw` 내용을 현재 UI 기준으로 단독 확정하지 않는다. - 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다. - agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다. - 전달받은 sync intent가 있으면 같은 내용을 재판단하지 않는다. - `sync-agent-ui`보다 뒤에 실행되어서는 안 된다. - 운영 단계에서 코드 후보만 근거로 agent-ui view/component skeleton을 자동 생성하지 않는다.