---
name: update-agent-ui
version: 1.1.1
description: 화면정의서, 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`에 남긴다.

## 출력 형식

```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 실패 후 남은 코드 변경을 사용자 결정 없이 되돌리지 않는다.