toki/agentic-framework
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agentic-framework/agent-ops/skills/common/validate-agent-ui/SKILL.md
toki 18add61a71 sync: from oto v1.1.157
2026-06-25 10:18:20 +09:00

14 KiB
Raw Blame History

name version description
validate-agent-ui 1.1.0 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:<view-id>, component:<component-id>, frame:<view-id> 중 하나. 기본값은 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:<view-id> 또는 scope=component:<component-id>이면 해당 문서의 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를 수집한다.
    • 같은 레벨의 <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는 구현됨, 계획, 가정, 불명확 중 하나여야 한다.
    • 구현됨 항목은 코드 반영 완료 상태여야 한다. 코드 근거가 있으면 실제 존재하는 code evidence path를 가져야 한다.
    • 구현됨의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 repair=true일 때 계획으로 낮추고 USER_REVIEW를 남길 수 있다.
    • 가정, 불명확 항목이 코드 동기화 가능한 정의처럼 설명되면 자동 의미 변경하지 않고 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 이름 중심으로 후보를 좁힌다.
    • 운영 단계에서는 코드 후보만 보고 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 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우
  • 계획 항목을 코드로 반영하려 했지만 구현 방향, 환경, 권한, 검증 실패를 에이전트가 해결하지 못한 경우
  • <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 경로가 깨진 구현됨이 남아 있지 않은가
  • 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로 보고하고 자동 수정하지 못한 이유를 남긴다.

출력 형식

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

- Scope: <scope>
- Auto Fixed: <파일/항목 목록 또는 없음>
- User Review: <agent-ui/USER_REVIEW.md 생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>
- Checked Files: <활성 파일 목록>
- Sync Intent: <inherited|required|skip|auto 판단 결과>
- sync-agent-ui: <실행/보류/생략 사유>

금지 사항

  • UI 의도 판단이 필요한 문제를 자동 수정하지 않는다.
  • archive 본문을 일반 검증 컨텍스트로 읽지 않는다.
  • .excalidraw 내용을 현재 UI 기준으로 단독 확정하지 않는다.
  • 사용자 확인 없이 의미 있는 문서를 병합하거나 삭제하지 않는다.
  • agent-ui 검증과 무관한 앱 구현 파일을 수정하지 않는다.
  • 전달받은 sync intent가 있으면 같은 내용을 재판단하지 않는다.
  • sync-agent-ui보다 뒤에 실행되어서는 안 된다.
  • 운영 단계에서 코드 후보만 근거로 agent-ui view/component skeleton을 자동 생성하지 않는다.