---
name: update-agent-ui
version: 1.1.0
description: 기존 agent-ui의 view, component, frame, wireframe 연결, source evidence, status, decision history를 갱신하는 스킬
---

# update-agent-ui

## 목적

기존 `agent-ui/`의 UI 정의를 갱신한다.
view, component, frame index, Excalidraw visual source 연결, source evidence, status를 현재 기준에 맞게 수정하고, 오래된 기준은 필요한 경우 archive log로 분리한다.

## 언제 호출할지

- 화면 정의서, view 정의, component 정의를 추가하거나 수정할 때
- wireframe 또는 Excalidraw visual source 연결을 추가하거나 수정할 때
- 기존 구현 코드 또는 컨셉 문서 변화에 맞춰 Source Evidence와 Status를 갱신할 때
- agent-ui 문서의 decision history, open question, user review를 갱신할 때
- ops/dev UI 정의를 제품 진행 상황에 맞춰 동기화할 때

## 입력

- `change`: 갱신할 내용 요약 (필수)
- `view-id`: 대상 view id (선택)
- `component-id`: 대상 component id 또는 path id (선택)
- `frame-source`: 예: `wire.excalidraw`, `overview.png` (선택)
- `evidence`: 코드, 문서, 사용자 입력 근거 경로 또는 요약 (선택)
- `status`: `implemented`, `planned`, `assumed`, `unknown` 중 하나 (선택)
- `mode`: `definition`, `frame`, `component`, `mixed` 중 하나. 기본값은 `mixed` (선택)

## 먼저 확인할 것

- [ ] `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 문서를 대상으로 삼는다.
   - `component-id`가 있으면 component 정의를 대상으로 삼는다.
   - `frame-source`가 있으면 대응 `frame/views/<view-id>/index.md`에 visual source를 연결한다.
   - 대상이 모호하면 추정으로 새 문서를 만들지 않고 `agent-ui/USER_REVIEW.md`에 결정 항목을 남긴다.

2. **정의 갱신**
   - 현재 기준은 `definition/**` 활성 문서에 반영한다.
   - 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를 유지한다.
   - 구현 코드 근거가 확인된 항목은 `implemented`, 문서 근거만 있는 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 둔다.
   - `status`가 입력되었더라도 evidence와 맞지 않으면 임의로 확정하지 않고 USER_REVIEW로 남긴다.
   - 새 view/component를 만들 때는 `Source Evidence`와 `Status`를 반드시 채운다.
   - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다.

3. **frame 갱신**
   - 대응되는 `frame/views/<view-id>/index.md`가 없으면 템플릿으로 만든다.
   - visual source가 있으면 `Visual Source`에 기록한다.
   - Excalidraw visual source의 기본 후보 파일명은 `wire.excalidraw`다.
   - frame의 required region id는 view definition의 region id와 맞춘다.
   - 정의에 없는 region이 frame에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다.

4. **USER_REVIEW 처리**
   - agent가 확정할 수 없는 화면 의도, region 추가/삭제, component 신규 생성 여부, page/drawer/split 선택은 `agent-ui/USER_REVIEW.md`에 남긴다.
   - 기존 USER_REVIEW 항목을 해결하는 변경이면 항목 상태를 갱신하고, 필요하면 `agent-ui/archive/user-review/user_review_N.log`로 이동한다.
   - 해결 로그를 만들 때는 현재 변경과 직접 관련된 항목만 이동한다.

5. **결과 보고**
   - 수정한 활성 정의 문서
   - 수정한 frame 문서와 visual source
   - archive log 변경 여부
   - USER_REVIEW 생성/갱신 여부
   - 남은 정합성 확인 항목

## 실행 결과 검증

- [ ] view/component는 folder-first + `index.md` 구조를 유지하는가
- [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가
- [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
- [ ] view region id와 frame region id가 충돌하지 않는가
- [ ] view에서 참조한 component id가 존재하거나 USER_REVIEW에 남았는가
- [ ] visual source가 있으면 대응 frame index에 기록되었는가
- [ ] 현재 기준이 archive에만 남지 않았는가
- [ ] 확정할 수 없는 UI 결정이 임의로 확정되지 않았는가
- 검증 실패 시: 자동 보정 가능한 것은 보완하고, 판단이 필요한 것은 `agent-ui/USER_REVIEW.md`에 남긴다.

## 출력 형식

```md
## 갱신 완료

- 수정 파일: <목록>
- view: <view-id 또는 없음>
- component: <component-id 또는 없음>
- frame source: <파일 또는 없음>
- evidence/status: <요약 또는 없음>
- archive 변경: <내용 또는 없음>
- USER_REVIEW: <생성/갱신/없음>
- 확인 필요: <항목 또는 없음>
```

## 금지 사항

- `definition/archive/**`를 현재 기준으로 사용하지 않는다.
- 코드나 문서 근거 없이 status를 확정하지 않는다.
- 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
- 사용자 판단이 필요한 UI 의도를 임의로 확정하지 않는다.
- view/component id를 명시적 요청 없이 바꾸지 않는다.
- `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다.
- agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다.
