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

name	version	description
update-agent-ui	1.1.1	화면정의서, view, component, frame, wireframe 내용을 agent로 수정하고 후속 validate 필요성과 sync intent 전달 여부를 판단하는 스킬

update-agent-ui

목적

기존 agent-ui/의 화면정의서와 wireframe 관련 문서를 갱신한다. 사용자가 "화면정의서에 X 추가", "wireframe에 사이드바 추가"처럼 agent-ui 명사를 쓰지 않아도 UI 정의 문서 수정 요청이면 이 스킬을 사용한다. 오래된 결정이 현재 기준을 흐리면 archive log로 분리하고, 변경 후 validate-agent-ui 필요성과 code sync intent 전달 여부를 판단한다. 코드 구현 규모 판정, plan 라우팅, roadmap/milestone 라우팅은 sync-agent-ui 책임이며 이 스킬에서 수행하지 않는다.

언제 호출할지

• 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때
• wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때
• 기존 구현 코드 또는 컨셉 문서 변화에 맞춰 Source Evidence와 Status를 갱신할 때
• agent-ui 문서의 decision history, open question, user review를 갱신할 때
• ops/dev UI 정의를 제품 진행 상황에 맞춰 동기화할 때
• 사용자가 "화면정의서에 ... 추가/수정/삭제", "와이어프레임에 ... 추가/수정/삭제", "wireframe에 ... 반영"처럼 요청할 때
• 사용자가 UIR-NNN 결정, agent-ui USER_REVIEW 해결, 화면정의서와 코드 불일치 보정을 요청할 때

입력

• change: 갱신할 내용 요약 (필수)
• view-id: 대상 view id (선택)
• component-id: 대상 component id 또는 path id (선택)
• frame-source: 예: wire.excalidraw, overview.png (선택)
• evidence: 코드, 문서, 사용자 입력 근거 경로 또는 요약 (선택)
• status: 구현됨, 계획, 가정, 불명확 중 하나 (선택)
• mode: definition, frame, component, mixed 중 하나. 기본값은 mixed (선택)
• post-validate: auto, true, false 중 하나. 기본값은 auto (선택)
• post-sync: auto, true, false 중 하나. 기본값은 auto (선택)
• review-resolution: 해결할 UIR-NNN과 결정 내용 (선택)

먼저 확인할 것

• agent-ops/rules/common/rules-agent-ui.md를 읽는다.
• agent-ui/ 존재 여부를 확인한다. 없으면 create-agent-ui 대상이라고 보고하고 중단한다.
• agent-ui/definition/index.md와 agent-ui/frame/index.md를 읽는다.
• 대상 view/component/frame 문서가 있으면 해당 활성 문서만 읽는다.
• agent-ui/USER_REVIEW.md가 있으면 현재 변경과 관련된 항목만 확인한다.
• definition/archive/**와 archive/user-review/**는 사용자가 과거 확인, 복원, 비교를 요청한 경우가 아니면 읽지 않는다.
• 필요한 템플릿만 agent-ops/skills/common/_templates/agent-ui/에서 읽는다.

실행 절차

1. 대상 분류

   • view-id가 있으면 view 정의를 대상으로 삼고, frame 문서가 있거나 frame-source가 입력된 경우에만 frame 문서를 대상으로 삼는다.
   • component-id가 있으면 component 정의를 대상으로 삼는다.
   • frame-source가 있으면 대응 frame/views/<view-id>/index.md에 visual source를 연결한다.
   • 대상이 모호하면 추정으로 새 문서를 만들지 않고 agent-ui/USER_REVIEW.md에 결정 항목을 남긴다.

2. 정의 갱신

   • 현재 기준은 definition/** 활성 문서에 반영한다.
   • 활성 Markdown 문서의 frontmatter를 유지하고, 새 문서는 rules-agent-ui.md의 Frontmatter Schema를 적용한다.
   • view 문서에는 status, source evidence, purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다.
   • component 문서에는 status, source evidence, purpose, used by, anatomy, variants, states, rules, decision history를 유지한다.
   • 구현 코드 반영 완료 항목은 구현됨, 문서 기준으로 정합화됐지만 코드 반영 전이거나 재작업 대상인 항목은 계획, 사용자 입력/추정만 있는 항목은 가정, 판단 불가 항목은 불명확으로 둔다.
   • 실제 근거 파일이 없으면 frontmatter source_evidence[].path는 null로 둔다.
   • frontmatter의 status, source_evidence, regions와 본문 Status, Source Evidence, Regions가 충돌하지 않게 함께 갱신한다.
   • status가 입력되었더라도 evidence와 맞지 않으면 임의로 확정하지 않고 USER_REVIEW로 남긴다.
   • 새 view/component를 만들 때는 Source Evidence와 Status를 반드시 채운다.
   • 오래된 결정이 현재 기준을 흐리면 대응되는 definition/archive/**.log로 이동하거나 추가한다. 단순 변경 이벤트를 모두 archive로 남기지 않는다.

3. frame 갱신

   • frame-source가 있고 대응되는 frame/views/<view-id>/index.md가 없으면 템플릿으로 만든다.
   • visual source가 있으면 frontmatter visual_source와 본문 Visual Source에 함께 기록한다.
   • visual source가 없으면 새 frame-view 문서를 만들지 않는다.
   • 기존 frame-view 문서의 visual source가 제거되고 더 이상 연결할 visual source가 없으면 frame-view 삭제 후보로 보고한다. 판단이 명확하면 삭제하고 view 문서의 frame을 null로 둔다.
   • Excalidraw visual source의 기본 후보 파일명은 wire.excalidraw다.
   • .excalidraw를 만들거나 수정하면 주요 박스 text label 또는 customData.region_id에 region id를 넣는다.
   • frame-view가 있으면 required region id는 view definition의 region id와 맞춘다.
   • 정의에 없는 region이 frame-view에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다.

4. USER_REVIEW 처리

   • agent가 확정할 수 없는 화면 의도, region 추가/삭제, component 신규 생성 여부, page/drawer/split 선택은 agent-ui/USER_REVIEW.md에 남긴다.
   • USER_REVIEW 항목에는 Source Skill: update-agent-ui, Stage: definition-edit, Blocking Step을 남긴다.
   • 기존 USER_REVIEW 항목을 해결하는 변경이면 항목 상태를 갱신하고, 필요하면 agent-ui/archive/user-review/user_review_N.log로 이동한다.
   • 해결 로그를 만들 때는 현재 변경과 직접 관련된 항목만 이동한다.
   • review-resolution이 있으면 결정 내용을 관련 활성 definition/frame/component 문서에 먼저 반영한다.
   • 해결된 항목은 agent-ui/archive/user-review/user_review_N.log로 이동하고, 활성 USER_REVIEW.md에는 미해결 항목만 남긴다. 남은 항목이 없으면 활성 USER_REVIEW.md를 제거할 수 있다.
   • sync 실패 후 남은 작업트리 변경이 있고 사용자 결정과 충돌하지 않으면 보존한 채 후속 validate/sync에서 이어간다.

5. 후속 validate와 sync intent 판단

   • post-validate=false가 아니고 view/component/frame/wireframe/source evidence/status 중 하나라도 바뀌었으면 validate-agent-ui를 실행한다.
   • post-validate=true이면 변경 크기와 무관하게 validate-agent-ui를 실행한다.
   • post-sync=true 또는 코드 반영이 필요한 계획 상태 변경이 있으면 sync intent를 validate-agent-ui에 전달한다.
   • post-sync=false이면 sync intent를 전달하지 않는다.
   • 후속 단계가 실행되면 순서는 항상 validate-agent-ui 다음 sync-agent-ui다.
   • 현재 변경 범위에 미해결 USER_REVIEW가 있으면 sync-agent-ui를 실행하지 않고 차단 항목을 보고한다.
   • 사용자가 "화면정의서와 코드가 안 맞아"처럼 불일치를 보고하면 관련 항목을 계획으로 되돌릴지 확인하고 validate/sync intent를 만든다.
   • sync intent를 만들더라도 코드 반영 방식이 direct-sync, plan-required, milestone-required 중 무엇인지는 판단하지 않는다.

6. 결과 보고

   • 수정한 활성 정의 문서
   • 수정한 frame 문서와 visual source
   • frontmatter schema 변경 여부
   • archive log 변경 여부
   • USER_REVIEW 생성/갱신 여부
   • validate-agent-ui 실행 여부와 결과
   • sync-agent-ui 필요 여부와 실행/보류 사유
   • 남은 정합성 확인 항목

실행 결과 검증

• view/component는 folder-first + index.md 구조를 유지하는가
• 새로 만들거나 수정한 활성 Markdown 문서가 ui_doc_type frontmatter를 포함하는가
• 새로 만들거나 수정한 view/component에 Source Evidence와 Status가 있는가
• 구현 근거 또는 sync 완료 없이 항목을 구현됨으로 표시하지 않았는가
• frame-view가 있으면 view region id와 frame region id가 충돌하지 않는가
• view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가
• visual source가 있으면 대응 frame index에 기록되었는가
• visual source가 없는데 빈 frame-view 문서만 남아 있지 않은가
• 현재 기준이 archive에만 남지 않았는가
• 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가
• 후속 단계가 필요할 때 validate-agent-ui가 sync-agent-ui보다 먼저 실행되었는가
• USER_REVIEW 해결 요청이면 결정이 활성 문서에 반영되고 해결 로그가 archive 되었는가
• sync 실패 후 남은 작업트리를 임의로 버리지 않았는가
• 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 agent-ui/USER_REVIEW.md에 남긴다.

출력 형식

## 갱신 완료

- 수정 파일: <목록>
- view: <view-id 또는 없음>
- component: <component-id 또는 없음>
- frame source: <파일 또는 없음>
- evidence/status: <요약 또는 없음>
- frontmatter schema: <변경/유지/없음>
- archive 변경: <내용 또는 없음>
- USER_REVIEW: <생성/갱신/없음>
- USER_REVIEW resolution: <해결/부분 해결/없음>
- validate-agent-ui: <실행/PASS/WARN/FAIL/생략 사유>
- sync-agent-ui: <실행/보류/생략 사유>
- 확인 필요: <항목 또는 없음>

금지 사항

• definition/archive/**를 현재 기준으로 사용하지 않는다.
• 코드나 문서 근거 없이 status를 확정하지 않는다.
• 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
• 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다.
• view/component id를 명시적 요청 없이 바꾸지 않는다.
• .excalidraw 파일만 만들고 frame index를 생략하지 않는다.
• visual source 없이 빈 frame-view 문서를 만들지 않는다.
• agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다.
• 코드 구현 규모에 따라 plan 또는 roadmap/milestone 라우팅을 확정하지 않는다.
• validate-agent-ui를 거치지 않고 sync-agent-ui를 실행하지 않는다.
• sync 실패 후 남은 코드 변경을 사용자 결정 없이 되돌리지 않는다.