From fa12e26e0aab0a85140aef50b0a636ad741fd778 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 24 Jun 2026 22:03:22 +0900 Subject: [PATCH] update agent-ui templates and skills --- agent-ops/rules/common/rules-agent-ui.md | 23 ++++++++ .../agent-ui/archive-log-template.md | 5 ++ .../agent-ui/component-index-template.md | 22 ++++++-- .../agent-ui/components-index-template.md | 7 ++- .../agent-ui/definition-index-template.md | 23 ++++++-- .../agent-ui/frame-index-template.md | 5 ++ .../agent-ui/frame-view-index-template.md | 13 ++++- .../_templates/agent-ui/readme-template.md | 5 ++ .../agent-ui/user-review-template.md | 5 ++ .../agent-ui/view-index-template.md | 25 +++++++-- .../agent-ui/views-index-template.md | 7 ++- .../skills/common/create-agent-ui/SKILL.md | 8 +++ .../skills/common/update-agent-ui/SKILL.md | 10 +++- .../skills/common/validate-agent-ui/SKILL.md | 52 ++++++++++++++++--- 14 files changed, 188 insertions(+), 22 deletions(-) diff --git a/agent-ops/rules/common/rules-agent-ui.md b/agent-ops/rules/common/rules-agent-ui.md index 23384f5..179e722 100644 --- a/agent-ops/rules/common/rules-agent-ui.md +++ b/agent-ops/rules/common/rules-agent-ui.md @@ -55,6 +55,24 @@ agent-ui/ - 구현 코드에서 확인된 항목은 `implemented`, 문서 계획에서 온 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 표시한다. - `planned`, `assumed`, `unknown` 항목을 구현 완료처럼 설명하지 않는다. +## Frontmatter Schema + +- 활성 Markdown 문서는 YAML frontmatter를 둔다. +- `ui_doc_type`은 `readme`, `definition-index`, `views-index`, `view`, `components-index`, `component`, `frame-index`, `frame-view`, `user-review`, `archive-log` 중 하나다. +- definition-index 문서는 `surface_type`, `source_evidence`를 둘 수 있다. +- view 문서는 `view_id`, `status`, `frame`, `source_evidence`를 둔다. +- component 문서는 `component_id`, `status`, `source_evidence`를 둔다. +- frame-view 문서는 `view_id`, `definition`, `visual_source`, `regions`를 둔다. +- `status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나다. +- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다. +- `source_evidence.type`은 `code`, `docs`, `user` 중 하나다. +- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다. +- `visual_source`가 아직 없으면 `null`을 사용한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다. +- `implemented`는 존재하는 `code` evidence path가 있을 때만 사용한다. +- `planned`는 문서 근거만 있을 때, `assumed`는 사용자 명시 입력만 있을 때, `unknown`은 근거나 판단이 부족할 때 사용한다. +- frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다. +- frontmatter는 기계적 검증을 위한 최소 schema이고, 본문 Markdown은 사람과 agent가 읽는 설명을 유지한다. + ## 명명 규칙 - view id, component id, 파일명, 디렉터리명은 kebab-case를 사용한다. @@ -70,6 +88,7 @@ agent-ui/ - component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`. - view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다. - view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다. +- frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다. ## Archive 접근 @@ -90,6 +109,10 @@ agent-ui/ - VS Code Excalidraw extension은 초기 편집 워크플로우로 사용할 수 있다. - excalidraw.com import/export 워크플로우는 기본 표준으로 삼지 않는다. - Excalidraw self-host는 R&D 후보이며, 기본 agent-ui scaffold의 필수 조건이 아니다. +- `.excalidraw`는 JSON으로 다룬다. 검증 시 가능하면 JSON parser로 `elements`의 text label 또는 `customData.region_id`를 확인한다. +- visual source에 region label이 있으면 `frame-view.regions`와 `definition` region id의 집합과 비교한다. +- visual source가 있는데 region label이 없으면 frame과 definition의 연결 근거가 부족한 상태로 본다. +- visual source에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동으로 UI 의도를 확정하지 않고 USER_REVIEW로 남긴다. ## 스킬 diff --git a/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md b/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md index 7ab7fb7..ea36221 100644 --- a/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/archive-log-template.md @@ -1,3 +1,8 @@ +--- +ui_doc_type: archive-log +target: +--- + # log ## diff --git a/agent-ops/skills/common/_templates/agent-ui/component-index-template.md b/agent-ops/skills/common/_templates/agent-ui/component-index-template.md index 343b01f..d8b30b0 100644 --- a/agent-ops/skills/common/_templates/agent-ui/component-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/component-index-template.md @@ -1,3 +1,19 @@ +--- +ui_doc_type: component +component_id: +status: +source_evidence: + - type: code + path: null + notes: <구현 근거. 없으면 없음> + - type: docs + path: null + notes: <컨셉/계획 근거. 없으면 없음> + - type: user + path: null + notes: <사용자 명시 입력. 없으면 없음> +--- + # Component ID: `` @@ -8,9 +24,9 @@ Status: `` | Type | Path | Notes | |------|------|-------| -| code | `` | <구현 근거. 없으면 `없음`> | -| docs | `` | <컨셉/계획 근거. 없으면 `없음`> | -| user | `` | <사용자 명시 입력. 없으면 `없음`> | +| code | 없음 | <구현 근거. 없으면 `없음`> | +| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> | +| user | 없음 | <사용자 명시 입력. 없으면 `없음`> | ## Purpose diff --git a/agent-ops/skills/common/_templates/agent-ui/components-index-template.md b/agent-ops/skills/common/_templates/agent-ui/components-index-template.md index cb675bc..e5b6fb2 100644 --- a/agent-ops/skills/common/_templates/agent-ui/components-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/components-index-template.md @@ -1,10 +1,15 @@ +--- +ui_doc_type: components-index +components: [] +--- + # Component Definitions ## Component List | Component ID | Status | Evidence | Description | |--------------|--------|----------|-------------| -| `` | `` | `` | <반복 UI 구성요소 설명> | +| 없음 | - | - | - | ## Rules diff --git a/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md index a83047d..a84717f 100644 --- a/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/definition-index-template.md @@ -1,3 +1,18 @@ +--- +ui_doc_type: definition-index +surface_type: ops-dev +source_evidence: + - type: code + path: null + notes: + - type: docs + path: null + notes: <컨셉/계획 근거 요약> + - type: user + path: null + notes: <사용자 명시 입력 요약> +--- + # UI Definition ## Purpose @@ -11,11 +26,11 @@ ## Source Evidence -| Type | Path | Usage | +| Type | Path | Notes | |------|------|-------| -| code | `` | | -| docs | `` | <컨셉/계획 근거 요약> | -| user | `` | <사용자 명시 입력 요약> | +| code | 없음 | | +| docs | 없음 | <컨셉/계획 근거 요약> | +| user | 없음 | <사용자 명시 입력 요약> | ## Structure diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md index cda599c..f6363aa 100644 --- a/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/frame-index-template.md @@ -1,3 +1,8 @@ +--- +ui_doc_type: frame-index +frames: [] +--- + # UI Frames ## Purpose diff --git a/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md index 8934a03..b907b76 100644 --- a/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md @@ -1,10 +1,19 @@ +--- +ui_doc_type: frame-view +view_id: +definition: ../../../definition/views//index.md +visual_source: null +regions: + - . +--- + # Frame Definition: - `../../../definition/views//index.md` Visual Source: -- `wire.excalidraw` +- 없음 ## Frame Intent @@ -22,6 +31,6 @@ Visual Source: ## Sync Rules -- visual source의 박스 라벨은 가능한 한 region id를 포함한다. +- visual source의 주요 박스 text label 또는 `customData.region_id`는 가능한 한 region id를 포함한다. - definition에 없는 region을 frame에 추가하지 않는다. 필요한 경우 `agent-ui/USER_REVIEW.md`에 남긴다. - frame에서 제거한 region은 definition에서도 제거 대상인지 확인한다. diff --git a/agent-ops/skills/common/_templates/agent-ui/readme-template.md b/agent-ops/skills/common/_templates/agent-ui/readme-template.md index 679adfb..5629284 100644 --- a/agent-ops/skills/common/_templates/agent-ui/readme-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/readme-template.md @@ -1,3 +1,8 @@ +--- +ui_doc_type: readme +surface_type: ops-dev +--- + # agent-ui 이 디렉터리는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다. diff --git a/agent-ops/skills/common/_templates/agent-ui/user-review-template.md b/agent-ops/skills/common/_templates/agent-ui/user-review-template.md index 5bba20c..bc3ae4e 100644 --- a/agent-ops/skills/common/_templates/agent-ui/user-review-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/user-review-template.md @@ -1,3 +1,8 @@ +--- +ui_doc_type: user-review +status: open +--- + # agent-ui 사용자 리뷰 이 문서는 agent가 확정할 수 없는 UI 결정을 사용자에게 넘기기 위한 활성 리뷰 문서다. diff --git a/agent-ops/skills/common/_templates/agent-ui/view-index-template.md b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md index 3b8fb2e..a5a1ccb 100644 --- a/agent-ops/skills/common/_templates/agent-ui/view-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/view-index-template.md @@ -1,3 +1,22 @@ +--- +ui_doc_type: view +view_id: +status: +frame: ../../../frame/views//index.md +source_evidence: + - type: code + path: null + notes: <구현 근거. 없으면 없음> + - type: docs + path: null + notes: <컨셉/계획 근거. 없으면 없음> + - type: user + path: null + notes: <사용자 명시 입력. 없으면 없음> +regions: + - . +--- + # View ID: `` @@ -11,9 +30,9 @@ Status: `` | Type | Path | Notes | |------|------|-------| -| code | `` | <구현 근거. 없으면 `없음`> | -| docs | `` | <컨셉/계획 근거. 없으면 `없음`> | -| user | `` | <사용자 명시 입력. 없으면 `없음`> | +| code | 없음 | <구현 근거. 없으면 `없음`> | +| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> | +| user | 없음 | <사용자 명시 입력. 없으면 `없음`> | ## Purpose diff --git a/agent-ops/skills/common/_templates/agent-ui/views-index-template.md b/agent-ops/skills/common/_templates/agent-ui/views-index-template.md index 73868ae..a5966db 100644 --- a/agent-ops/skills/common/_templates/agent-ui/views-index-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/views-index-template.md @@ -1,10 +1,15 @@ +--- +ui_doc_type: views-index +views: [] +--- + # View Definitions ## View Tree | View ID | Status | Evidence | Description | |---------|--------|----------|-------------| -| `` | `` | `` | <화면 또는 업무 단위 설명> | +| 없음 | - | - | - | ## Navigation diff --git a/agent-ops/skills/common/create-agent-ui/SKILL.md b/agent-ops/skills/common/create-agent-ui/SKILL.md index 8d05b36..0e9ed73 100644 --- a/agent-ops/skills/common/create-agent-ui/SKILL.md +++ b/agent-ops/skills/common/create-agent-ui/SKILL.md @@ -65,6 +65,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - `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/` @@ -83,7 +84,10 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - 문서 근거만 있으면 `status: planned` - 명시 입력만 있고 근거가 부족하면 `status: assumed` - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다. + - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다. + - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 같은 기준을 말하게 작성한다. - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다. + - `.excalidraw`를 만들거나 연결하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다. - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다. 6. **초기 component 생성** @@ -92,6 +96,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - `blank`에서는 명시 `components`가 있을 때만 component 후보를 만든다. - 각 component 후보마다 `agent-ui/definition/components//index.md`를 만든다. - component 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다. + - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다. - component id가 path id이면 하위 디렉터리 구조로 만든다. - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다. @@ -104,6 +109,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - 선택된 `source-mode` - 읽은 근거 파일과 생성에 사용한 evidence - 생성한 파일 + - 적용한 frontmatter schema - 생성한 view/component의 status - USER_REVIEW 생성 여부 - product UI 확장 후보 @@ -113,6 +119,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - [ ] `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`가 있는가 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가 @@ -130,6 +137,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분 - source-mode: - evidence: <주요 근거 파일 목록> - 생성 파일: <목록> +- frontmatter schema: <적용/부분 적용/없음> - views: - components: - USER_REVIEW: <생성/없음> diff --git a/agent-ops/skills/common/update-agent-ui/SKILL.md b/agent-ops/skills/common/update-agent-ui/SKILL.md index 60c66c0..7df7325 100644 --- a/agent-ops/skills/common/update-agent-ui/SKILL.md +++ b/agent-ops/skills/common/update-agent-ui/SKILL.md @@ -49,17 +49,22 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, 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//index.md`가 없으면 템플릿으로 만든다. - - visual source가 있으면 `Visual Source`에 기록한다. + - 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로 분리한다. @@ -71,6 +76,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, 5. **결과 보고** - 수정한 활성 정의 문서 - 수정한 frame 문서와 visual source + - frontmatter schema 변경 여부 - archive log 변경 여부 - USER_REVIEW 생성/갱신 여부 - 남은 정합성 확인 항목 @@ -78,6 +84,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, ## 실행 결과 검증 - [ ] view/component는 folder-first + `index.md` 구조를 유지하는가 +- [ ] 새로 만들거나 수정한 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가 - [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가 - [ ] view region id와 frame region id가 충돌하지 않는가 @@ -97,6 +104,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence, - component: - frame source: <파일 또는 없음> - evidence/status: <요약 또는 없음> +- frontmatter schema: <변경/유지/없음> - archive 변경: <내용 또는 없음> - USER_REVIEW: <생성/갱신/없음> - 확인 필요: <항목 또는 없음> diff --git a/agent-ops/skills/common/validate-agent-ui/SKILL.md b/agent-ops/skills/common/validate-agent-ui/SKILL.md index 8985ac2..bd3d84f 100644 --- a/agent-ops/skills/common/validate-agent-ui/SKILL.md +++ b/agent-ops/skills/common/validate-agent-ui/SKILL.md @@ -1,14 +1,14 @@ --- name: validate-agent-ui version: 1.1.0 -description: agent-ui scaffold, definition/frame/component/source evidence/status 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬 +description: agent-ui scaffold, definition/frame/component/source evidence/status와 구현 코드 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬 --- # validate-agent-ui ## 목적 -`agent-ui/` 구조와 문서 간 정합성을 검사한다. +`agent-ui/` 구조, 문서 간 정합성, 구현 코드와 agent-ui 정의 간 정합성을 검사한다. 파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다. ## 언제 호출할지 @@ -16,12 +16,13 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때 - view/component/frame 문서가 서로 어긋났는지 확인할 때 - view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때 +- 실제 UI 코드와 agent-ui view/component 정의가 동기화되어 있는지 확인할 때 - Excalidraw visual source와 frame index 연결을 검사할 때 - agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때 ## 입력 -- `scope`: `all`, `view:`, `component:`, `frame:` 중 하나. 기본값은 `all` (선택) +- `scope`: `all`, `internal`, `implementation`, `view:`, `component:`, `frame:` 중 하나. 기본값은 `all` (선택) - `repair`: `true` 또는 `false`. 기본값은 `true` (선택) ## 먼저 확인할 것 @@ -30,6 +31,8 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다. - [ ] `agent-ui/definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md` 존재 여부를 확인한다. - [ ] scope에 해당하는 활성 definition/frame 문서만 읽는다. +- [ ] `scope=view:` 또는 `scope=component:`이면 해당 문서의 Source Evidence code path를 확인한다. +- [ ] `scope=all` 또는 `scope=implementation`이면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다. - [ ] archive는 경로와 tree 대응만 확인하고, 사용자가 과거 내용 확인을 요청하지 않았으면 본문을 읽지 않는다. - [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다. @@ -39,6 +42,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - `definition/views/**/index.md`에서 view 목록을 만든다. - `definition/components/**/index.md`에서 component 목록을 만든다. - `frame/views/**/index.md`에서 frame 목록을 만든다. + - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`, id, status, source_evidence, regions를 수집한다. - 같은 레벨의 `.md`와 `/` 혼재 여부를 확인한다. 2. **구조 검증과 자동 보정** @@ -49,7 +53,14 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다. 3. **definition 정합성 검사** + - 활성 Markdown 문서에 `ui_doc_type` frontmatter가 있는지 확인한다. + - `ui_doc_type`이 경로와 맞는지 확인한다. 예: `definition/views//index.md`는 `view`다. + - view/component/frame id가 경로 id와 일치하는지 확인한다. - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다. + - frontmatter `source_evidence`는 list이고 각 항목은 `type`, `path`, `notes`를 가져야 한다. + - `source_evidence.type`은 `code`, `docs`, `user` 중 하나여야 한다. + - 근거 파일이 없으면 `path: null`이어야 하며, placeholder 문자열을 근거로 보지 않는다. + - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하는지 확인한다. - `Status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나여야 한다. - `implemented` 항목은 실제 존재하는 코드 근거가 있어야 한다. - `implemented`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `unknown`으로 낮추고 USER_REVIEW를 남길 수 있다. @@ -62,19 +73,40 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu 4. **frame 정합성 검사** - view가 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다. - - frame index가 가리키는 definition 경로와 visual source가 실제 존재하는지 확인한다. + - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다. + - `visual_source`가 `null`이면 visual source 없음으로 본다. + - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다. + - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다. + - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다. + - Excalidraw region id 후보가 없고 frame required region이 있으면 USER_REVIEW로 남긴다. + - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다. + - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다. - frame required region과 view definition region을 비교한다. - definition에 있는 region이 frame index에만 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다. - frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다. - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다. -5. **USER_REVIEW 생성 또는 갱신** +5. **구현 정합성 검사** + - `scope=view:` 또는 `scope=component:`이면 해당 문서의 `source_evidence` 중 `type: code` 경로만 확인하고 전체 코드 후보 스캔은 하지 않는다. + - `scope=all` 또는 `scope=implementation`이면 전체 view/component의 `source_evidence` 중 `type: code` 경로가 실제 존재하는지 확인한다. + - 실제 UI 구현 후보를 찾는다. + - 이 후보 스캔은 `scope=all` 또는 `scope=implementation`일 때만 수행한다. + - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일 + - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다. + - 코드가 많으면 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다. + - 코드 후보가 명확한 route/page/view/shell이면 대응 view가 있는지 확인한다. + - 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action이면 대응 component가 있는지 확인한다. + - 명확한 누락이고 `repair=true`이면 skeleton view/component를 만들 수 있다. 이때 status는 `implemented`, source evidence는 해당 code path로 둔다. + - 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다. + - 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `implemented`를 `unknown`으로 낮출 수 있다. + +6. **USER_REVIEW 생성 또는 갱신** - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다. - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다. - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다. - 항목에는 Context, Options, Needed For를 포함한다. -6. **결과 판정** +7. **결과 판정** - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태 - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태 - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태 @@ -86,8 +118,9 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - 명확한 단일 후보 상대 링크 보정 - definition에 이미 있는 region의 frame index 누락 보완 - 빈 archive/user-review 디렉터리 생성 -- 템플릿 필수 섹션 누락 보완. `Source Evidence`와 `Status` 누락 포함 +- 템플릿 필수 섹션과 frontmatter 누락 보완. `ui_doc_type`, `Source Evidence`, `Status` 누락 포함 - 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다. +- 명확한 구현 코드 후보에 대응되는 skeleton view/component 생성. 단, status/evidence를 함께 기록한다. - 명시된 code evidence 경로가 실제 존재하지 않는 `implemented`를 `unknown`으로 낮추고 USER_REVIEW를 남기는 보정 ## USER_REVIEW 대상 @@ -95,15 +128,19 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - 정의에는 없는 region이 frame에 있고 추가/삭제 의도 판단이 필요한 경우 - frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우 - component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우 +- 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우 +- 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우 - `.md`와 `/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우 - drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우 ## 실행 결과 검증 - [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가 +- [ ] 활성 Markdown 문서가 유효한 `ui_doc_type` frontmatter를 갖는가 - [ ] folder-first + `index.md` 구조가 유지되는가 - [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가 - [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가 +- [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보가 agent-ui에 반영되었거나 USER_REVIEW에 남았는가 - [ ] view/component/frame 참조가 끊기지 않는가 - [ ] 자동 수정한 파일 목록이 보고되는가 - [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가 @@ -120,6 +157,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu - User Review: - Remaining Issues: <목록 또는 없음> - Checked Files: <활성 파일 목록> +- Implementation Sync: <확인/스킵/USER_REVIEW> ``` ## 금지 사항