toki/rara
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rara/agent-ops/skills/common/create-agent-ui/SKILL.md
toki fdc86c7ff4
Some checks are pending
ci / validate (push) Waiting to run
Details
initial commit
2026-07-18 18:41:17 +09:00

11 KiB
Raw Blame History

name version description
create-agent-ui 1.1.0 프로젝트 코드 또는 문서 근거를 분석해 agent-ui 기본 스캐폴드와 최초 코드 동기화 기준선을 생성하는 스킬

create-agent-ui

목적

프로젝트의 기존 UI 코드나 컨셉 문서를 근거로 agent-ui/ 기본 구조와 UI 정의 초안을 생성한다. ops/dev UI를 1차 대상으로 하며, 생성 결과를 최초 agent-ui 기준선으로 보고 .sync-state.json을 만든다.

언제 호출할지

  • 사용자가 agent-ui 생성, UI 스캐폴드 생성, 화면 정의 구조 생성을 요청할 때
  • 프로젝트에 agent-ui/가 없고 기존 코드 또는 문서에서 UI 정의 문맥을 추출할 때
  • UI 코드가 있으면 구현 상태와 동기화된 view/component/frame 초안이 필요할 때
  • UI 코드가 아직 부족하면 README, roadmap, SDD, docs 같은 컨셉 문서 기반 최소 view tree가 필요할 때

입력

  • surface-type: ops-dev 또는 product. 기본값은 ops-dev (선택)
  • source-mode: auto, code-first, concept-first, blank 중 하나. 기본값은 auto (선택)
  • views: 초기 생성할 view id 목록, kebab-case (선택)
  • components: 초기 생성할 component id 목록, kebab-case 또는 path id (선택)

먼저 확인할 것

  • agent-ops/rules/common/rules-agent-ui.md를 읽는다.
  • 생성 대상 agent-ui/ 존재 여부를 확인한다.
  • 기존 agent-ui/가 있으면 덮어쓰지 않고 update-agent-ui 또는 validate-agent-ui 대상인지 보고한다.
  • 템플릿 경로 agent-ops/skills/common/_templates/agent-ui/ 하위 파일을 확인한다.
  • source-mode=auto이면 UI 코드 후보와 컨셉 문서 후보를 모두 가볍게 확인한다.
  • baseline commit/push를 위해 현재 git status와 HEAD를 확인한다.
  • unrelated dirty worktree가 있으면 baseline commit 전에 범위를 보고하고, agent-ui 생성 파일만 stage한다.

실행 절차

  1. 생성 대상 확정

    • 생성 루트는 agent-ui/로 고정한다.
    • surface-type이 없으면 ops-dev로 둔다.
    • source-mode가 없으면 auto로 둔다.
    • product UI가 명시되어도 기본 구조는 유지하고 product 전용 레이어는 요청된 경우에만 추가 후보로 보고한다.

  2. 근거 수집

    • code-first 또는 auto에서는 UI 구현 후보를 찾는다.
      • 예: apps/**/lib/**, packages/**/lib/**, src/**, app/**, pages/**, screens/**, views/**, components/**, widgets/**, route/navigation/shell 파일
      • 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
      • 코드가 많으면 전체 정독하지 말고 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
    • concept-first 또는 auto에서는 컨셉 문서 후보를 찾는다.
      • 예: README.md, docs/**, agent-roadmap/current.md, 활성 Phase/Milestone, 승인된 SDD, agent-ops/rules/project/rules.md
      • roadmap 문서는 agent-ops/rules/common/rules-roadmap.md의 loading/archive 접근 규칙을 따른다.
      • archive 문서는 사용자가 과거 근거를 명시하지 않는 한 읽지 않는다.
    • 근거가 없거나 사용자가 빈 구조를 요청하면 blank로 처리한다.

  3. source-mode 결정

    • auto에서 route, shell, page/view, widget/component 후보 중 하나 이상이 실제 파일 경로로 확인되면 code-first로 생성한다.
    • UI 구현 후보가 부족하고 컨셉 문서 후보가 있으면 concept-first로 생성한다.
    • 코드와 문서 근거가 모두 부족하면 blank로 생성하고 부족한 근거를 결과에 보고한다.
    • 명시된 views 또는 components는 선택된 mode와 함께 생성 후보로 반영한다.

  4. 기본 구조 생성

    • 다음 활성 문서를 템플릿 기준으로 만든다.
      • agent-ui/README.md
      • agent-ui/definition/index.md
      • agent-ui/definition/views/index.md
      • agent-ui/definition/components/index.md
      • agent-ui/frame/index.md
    • 생성하는 활성 Markdown 문서에는 rules-agent-ui.md의 Frontmatter Schema를 적용한다.
    • 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 .gitkeep을 둘 수 있다.
      • agent-ui/definition/archive/views/
      • agent-ui/definition/archive/components/
      • agent-ui/archive/user-review/
    • USER_REVIEW.md는 사용자 판단 항목이 있을 때만 만든다.

  5. 초기 view 생성

    • code-first에서는 구현 코드에서 확인된 route/page/view/shell 단위를 view 후보로 만든다.
    • concept-first에서는 문서에서 확인된 운영 업무, 화면, 콘솔 영역을 view 후보로 만든다.
    • blank에서는 명시 views가 있을 때만 view 후보를 만든다.
    • 각 view 후보마다 다음 문서를 만든다.
      • agent-ui/definition/views/<view-id>/index.md
    • view 문서에는 Source Evidence와 Status를 반드시 남긴다.
      • 코드 근거가 있으면 status: 구현됨
      • 문서 근거만 있으면 status: 계획
      • 명시 입력만 있고 근거가 부족하면 status: 가정
      • 판단 불가하면 status: 불명확과 USER_REVIEW 항목을 남긴다.
    • 실제 근거 파일이 없으면 frontmatter source_evidence[].path는 null로 둔다.
    • visual source가 없는 초기 view 문서의 frontmatter frame은 null로 둔다.
    • frontmatter의 status, source_evidence, regions와 본문 Status, Source Evidence, Regions가 같은 기준을 말하게 작성한다.
    • .excalidraw 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다.
    • .excalidraw 또는 다른 visual source를 만들거나 연결할 때만 agent-ui/frame/views/<view-id>/index.md를 만든다.
    • .excalidraw를 만들거나 연결하면 주요 박스 text label 또는 customData.region_id에 region id를 넣는다.
    • view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다.

  6. 초기 component 생성

    • code-first에서는 반복 widget/component/table/filter/log/status/action 단위를 component 후보로 만든다.
    • concept-first에서는 문서상 반복 패턴이 분명한 data table, status badge, filter bar, log viewer 같은 구성요소만 component 후보로 만든다.
    • blank에서는 명시 components가 있을 때만 component 후보를 만든다.
    • 각 component 후보마다 agent-ui/definition/components/<component-id>/index.md를 만든다.
    • component 문서에는 Source Evidence와 Status를 반드시 남긴다.
    • 실제 근거 파일이 없으면 frontmatter source_evidence[].path는 null로 둔다.
    • component id가 path id이면 하위 디렉터리 구조로 만든다.
    • view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다.

  7. 불확실성 분리

    • 코드와 문서가 충돌하면 임의로 통합하지 않고 agent-ui/USER_REVIEW.md에 남긴다.
    • view 경계, component 신규 생성 여부, page/drawer/split 같은 UX 판단은 USER_REVIEW로 남긴다.
    • 문서 근거만 있는 계획 항목을 구현 완료처럼 쓰지 않는다.

  8. 정합성 검증과 baseline 기록

    • 생성 직후 validate-agent-ui를 실행해 scaffold와 문서 간 정합성을 확인하고 자동 보정한다.
    • agent-ui/.sync-state.json에 기록할 baseline 내용을 준비한다.
    • baseline_mode는 선택된 source-mode로 둔다.
    • code-first, concept-first, blank 모두 생성된 agent-ui를 최초 기준선으로 본다.
    • baseline commit은 두 단계로 남긴다.
      • 먼저 .sync-state.json을 제외한 agent-ui 생성/보정 파일을 commit한다.
      • 그 commit hash를 새 agent-ui/.sync-state.json의 last_synced_head에 기록한 뒤 별도 commit한다.
    • commit message는 예를 들어 docs(agent-ui): create baseline과 sync: record agent-ui baseline처럼 목적이 분리되게 쓴다.
    • 두 commit을 push한다.
    • USER_REVIEW가 생성되어도 생성 baseline은 남길 수 있다. 단, 이후 sync-agent-ui는 관련 USER_REVIEW가 해결될 때까지 실행하지 않는다.

  9. 결과 보고

    • 선택된 source-mode
    • 읽은 근거 파일과 생성에 사용한 evidence
    • 생성한 파일
    • 적용한 frontmatter schema
    • 생성한 view/component의 status
    • USER_REVIEW 생성 여부
    • .sync-state.json 생성 여부와 baseline commit hash
    • baseline commit/push 결과
    • product UI 확장 후보
    • 후속 권장 작업

실행 결과 검증

  • agent-ui/README.md가 생성되었는가
  • definition/index.md, definition/views/index.md, definition/components/index.md, frame/index.md가 생성되었는가
  • 활성 Markdown 문서가 ui_doc_type frontmatter를 포함하는가
  • view/component는 folder-first + index.md 구조를 사용하는가
  • 생성한 view/component에 Source Evidence와 Status가 있는가
  • 구현 근거 없는 항목을 구현됨으로 표시하지 않았는가
  • visual source가 없는 view에 빈 frame/views/<view-id>/index.md를 만들지 않았는가
  • 코드/문서 충돌이나 UI 의도 판단이 필요한 항목이 USER_REVIEW에 남았는가
  • 같은 레벨에 <name>.md와 <name>/가 함께 생기지 않았는가
  • archive 본문 파일을 불필요하게 생성하지 않았는가
  • validate-agent-ui 결과가 PASS 또는 자동 보정 완료 WARN으로 보고되었는가
  • .sync-state.json이 생성되었고 last_synced_head가 baseline commit을 가리키는가
  • baseline commit/push가 완료되었는가
  • unrelated dirty file이 baseline commit에 포함되지 않았는가
  • 검증 실패 시: 누락된 scaffold만 보완하고 기존 문서를 덮어쓰지 않는다.

출력 형식

## 생성 완료

- 루트: agent-ui/
- source-mode: <code-first|concept-first|blank>
- evidence: <주요 근거 파일 목록>
- 생성 파일: <목록>
- frontmatter schema: <적용/부분 적용/없음>
- views: <view-id=status 목록 또는 없음>
- components: <component-id=status 목록 또는 없음>
- USER_REVIEW: <생성/없음>
- sync state: <생성/없음, last_synced_head>
- baseline commit/push: <완료/실패/생략 사유>
- 확인 필요: <항목 또는 없음>
- 후속 권장: <필요 시 sync-agent-ui 또는 없음>

금지 사항

  • 기존 agent-ui/ 문서를 덮어쓰지 않는다.
  • .excalidraw 파일을 현재 UI source of truth로 만들지 않는다.
  • 코드나 문서 근거 없이 화면 의도를 확정하지 않는다.
  • 문서 근거만 있는 항목을 구현 완료 상태로 쓰지 않는다.
  • product UI 전용 레이어를 요청 없이 추가하지 않는다.
  • definition/archive/**나 archive/user-review/**에 현재 기준 문서를 만들지 않는다.
  • baseline commit 없이 .sync-state.json의 last_synced_head를 추정하지 않는다.