nomadcode/agent-ops/skills/common/validate-agent-ui/SKILL.md

name	version	description
validate-agent-ui	1.1.0	agent-ui scaffold, definition/frame/component/source evidence/status와 구현 코드 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬

validate-agent-ui

목적

agent-ui/ 구조, 문서 간 정합성, 구현 코드와 agent-ui 정의 간 정합성을 검사한다. 파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, UI 의도 판단이 필요한 문제는 agent-ui/USER_REVIEW.md에 남긴다.

언제 호출할지

• agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
• view/component/frame 문서가 서로 어긋났는지 확인할 때
• view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
• 실제 UI 코드와 agent-ui view/component 정의가 동기화되어 있는지 확인할 때
• Excalidraw visual source와 frame index 연결을 검사할 때
• agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때

입력

• scope: all, internal, implementation, view:<view-id>, component:<component-id>, frame:<view-id> 중 하나. 기본값은 all (선택)
• repair: true 또는 false. 기본값은 true (선택)

먼저 확인할 것

• 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:<view-id> 또는 scope=component:<component-id>이면 해당 문서의 Source Evidence code path를 확인한다.
• scope=all 또는 scope=implementation이면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다.
• 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를 수집한다.
   • 같은 레벨의 <name>.md와 <name>/ 혼재 여부를 확인한다.

2. 구조 검증과 자동 보정

   • 필수 루트 문서가 없고 repair=true이면 템플릿으로 생성한다.
   • view/component 디렉터리에 index.md가 없고 의도가 명확하면 템플릿으로 생성한다.
   • frame 디렉터리는 visual source가 있을 때만 index.md 생성 대상으로 삼는다.
   • .excalidraw 파일이 하나 있고 frame index의 visual source가 비어 있으면 해당 파일을 등록한다.
   • archive/user-review 디렉터리가 없고 필요하면 생성한다.
   • <name>.md와 <name>/가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다.

3. definition 정합성 검사

   • 활성 Markdown 문서에 ui_doc_type frontmatter가 있는지 확인한다.
   • ui_doc_type이 경로와 맞는지 확인한다. 예: definition/views/<view-id>/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는 implemented, planned, assumed, unknown 중 하나여야 한다.
   • implemented 항목은 실제 존재하는 코드 근거가 있어야 한다.
   • implemented의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 repair=true일 때 unknown으로 낮추고 USER_REVIEW를 남길 수 있다.
   • implemented인데 code evidence 자체가 없으면 자동 변경하지 않고 USER_REVIEW로 남긴다.
   • planned, assumed, unknown 항목이 구현 완료처럼 설명되면 자동 의미 변경하지 않고 USER_REVIEW로 남긴다.
   • region id가 <view-id>.<region> 또는 <view-id>.<region>.<subregion> 형식인지 확인한다.
   • 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:<view-id> 또는 scope=component:<component-id>이면 해당 문서의 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 이름 중심으로 후보를 좁힌다.
   • 코드 후보가 명확한 route/page/view/shell이면 대응 view가 있는지 확인한다.
   • 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action이면 대응 component가 있는지 확인한다.
   • 명확한 누락이고 repair=true이면 skeleton view/component를 만들 수 있다. 이때 status는 implemented, source evidence는 해당 code path로 둔다.
   • 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다.
   • 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 implemented를 unknown으로 낮출 수 있다.

6. USER_REVIEW 생성 또는 갱신

   • active review 파일은 agent-ui/USER_REVIEW.md를 사용한다.
   • 새 항목 id는 기존 최대 UIR-NNN 다음 번호를 사용한다.
   • 같은 경로와 같은 질문의 중복 항목은 만들지 않는다.
   • 항목에는 Context, Options, Needed For를 포함한다.

7. 결과 판정

   • 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 누락 포함
• 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다.
• 명확한 구현 코드 후보에 대응되는 skeleton view/component 생성. 단, status/evidence를 함께 기록한다.
• 명시된 code evidence 경로가 실제 존재하지 않는 implemented를 unknown으로 낮추고 USER_REVIEW를 남기는 보정

USER_REVIEW 대상

• 정의에는 없는 region이 기존 frame-view에 있고 추가/삭제 의도 판단이 필요한 경우
• frame-view가 있는데 frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
• component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
• 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우
• 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우
• <name>.md와 <name>/가 모두 있고 둘 다 의미 있는 내용이 있는 경우
• drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우

실행 결과 검증

• 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
• 활성 Markdown 문서가 유효한 ui_doc_type frontmatter를 갖는가
• folder-first + index.md 구조가 유지되는가
• view/component에 Source Evidence와 유효한 Status가 있는가
• 명시된 code evidence 경로가 깨진 implemented가 남아 있지 않은가
• scope=implementation 또는 all이면 명확한 UI 코드 후보가 agent-ui에 반영되었거나 USER_REVIEW에 남았는가
• view/component/frame 참조가 끊기지 않는가
• visual source가 없는 view는 frame 참조가 null이거나 비어 있는 frame-view가 없는가
• 자동 수정한 파일 목록이 보고되는가
• 사용자 판단이 필요한 항목이 agent-ui/USER_REVIEW.md에 남는가
• archive 본문을 일반 검증에서 읽지 않았는가
• 검증 실패 시: 판정을 FAIL로 보고하고 자동 수정하지 못한 이유를 남긴다.

출력 형식

## agent-ui 검증 결과: <PASS|WARN|FAIL>

- Scope: <scope>
- Auto Fixed: <파일/항목 목록 또는 없음>
- User Review: <agent-ui/USER_REVIEW.md 생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>
- Checked Files: <활성 파일 목록>
- Implementation Sync: <확인/스킵/USER_REVIEW>

금지 사항

• UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
• archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
• .excalidraw 내용을 현재 UI 기준으로 단독 확정하지 않는다.
• 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
• agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.