toki/oto
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oto/agent-ops/skills/common/update-agent-ui/SKILL.md

7 KiB
Raw Blame History

name version description
update-agent-ui 1.1.0 기존 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/** 활성 문서에 반영한다.
    • 활성 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를 유지한다.
    • 구현 코드 근거가 확인된 항목은 implemented, 문서 근거만 있는 항목은 planned, 사용자 명시 입력만 있고 근거가 부족한 항목은 assumed, 판단 불가 항목은 unknown으로 둔다.
    • 실제 근거 파일이 없으면 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로 이동하거나 추가한다.

  3. frame 갱신

    • 대응되는 frame/views/<view-id>/index.md가 없으면 템플릿으로 만든다.
    • visual source가 있으면 frontmatter visual_source와 본문 Visual Source에 함께 기록한다.
    • visual source가 없으면 frontmatter visual_source는 null로 둔다.
    • Excalidraw visual source의 기본 후보 파일명은 wire.excalidraw다.
    • .excalidraw를 만들거나 수정하면 주요 박스 text label 또는 customData.region_id에 region id를 넣는다.
    • 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
    • frontmatter schema 변경 여부
    • archive log 변경 여부
    • USER_REVIEW 생성/갱신 여부
    • 남은 정합성 확인 항목

실행 결과 검증

  • view/component는 folder-first + index.md 구조를 유지하는가
  • 새로 만들거나 수정한 활성 Markdown 문서가 ui_doc_type frontmatter를 포함하는가
  • 새로 만들거나 수정한 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에 남긴다.

출력 형식

## 갱신 완료

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

금지 사항

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