From a72d3cc7ef9f0a118d74309adff030857a2124c3 Mon Sep 17 00:00:00 2001 From: toki Date: Wed, 29 Jul 2026 08:08:35 +0900 Subject: [PATCH] =?UTF-8?q?feat(agent-ui):=20=EC=99=84=EB=A3=8C=20?= =?UTF-8?q?=EC=A0=95=ED=95=A9=ED=99=94=20=EA=B2=BD=EB=A1=9C=EB=A5=BC=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 계획 기반 UI 작업의 완료 근거와 상태 갱신을 명확히 연결한다. --- agent-ops/rules/common/rules-agent-ui.md | 9 +++++++-- .../_templates/agent-ui/definition-index-template.md | 1 + .../skills/common/_templates/agent-ui/readme-template.md | 3 ++- agent-ops/skills/common/router.md | 6 ++++-- 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/agent-ops/rules/common/rules-agent-ui.md b/agent-ops/rules/common/rules-agent-ui.md index d3375c5..6747523 100644 --- a/agent-ops/rules/common/rules-agent-ui.md +++ b/agent-ops/rules/common/rules-agent-ui.md @@ -12,7 +12,7 @@ ```text agent-ui/ README.md - .sync-state.json # 선택: agent-ui -> code 동기화 기준점 + .sync-state.json # 선택: agent-ui -> code 동기화 기준점과 pending code-work 매핑 USER_REVIEW.md # 선택: 사용자 판단이 필요한 활성 리뷰 archive/ user-review/ @@ -92,7 +92,9 @@ agent-ui/ - 사용자가 "agent-ui와 코드 전체 동기화"처럼 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다. - `update-agent-ui` 또는 수동 `validate-agent-ui`가 코드 반영 필요성을 판단했으면 그 판단을 다음 단계로 전달한다. 전달된 판단이 있으면 뒤 단계는 문서 정합성과 sync intent 자체를 재판단하지 않지만, `sync-agent-ui`는 실제 코드 반영 방식 판정을 수행한다. - 직접 sync가 검증되면 반영된 view/component의 `status`를 `구현됨`으로 바꾼다. -- `sync-agent-ui`가 코드 작업을 `plan-required`로 라우팅한 경우에는 plan이 `Agent UI Completion`을 남기고, code-review PASS 시점에 해당 view/component/frame만 `구현됨`으로 반영한다. 이 경로에서는 `sync-agent-ui`가 status를 직접 변경하지 않는다. +- `sync-agent-ui`가 코드 작업을 `plan-required`로 라우팅한 경우에는 일반 plan/review 문서에 agent-ui 전용 completion section을 추가하지 않는다. +- plan pair 생성 뒤 `sync-agent-ui mode=prepare-code-work`가 `.sync-state.json.pending_code_work`에 task path, agent-ui 문서, 코드 후보, 검증 기준을 기록한다. +- 일반 code-review PASS와 exact `complete.log` 생성 뒤 `sync-agent-ui mode=reconcile-completion`이 matching pending entry만 사용해 `update-agent-ui`와 `validate-agent-ui`를 순서대로 실행하고 해당 view/component/frame을 `구현됨`으로 반영한다. - `sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅해 `agent-ui 상태 반영: 대기`를 남긴 Milestone만 종료 검토 통과 시 `구현됨` 반영 gate가 된다. 최종 검증과 code evidence가 확인된 view/component/frame만 반영하며, Milestone 완료만으로 agent-ui 전체 status를 일괄 변경하지 않는다. - 사용자 확인 또는 후속 검증에서 불일치가 발견되면 해당 항목은 `계획`으로 되돌릴 수 있다. - `sync-agent-ui`가 검증 실패, 환경 차단, 구현 방향 충돌, 반복 실패를 스스로 해결하지 못하면 commit/push하지 않고 `agent-ui/USER_REVIEW.md`에 게이트를 남긴다. @@ -105,6 +107,9 @@ agent-ui/ - 기존 방식으로 생성되어 `.sync-state.json`이 없는 agent-ui는 legacy 상태다. 이 경우 기본 변경분 sync를 시작하지 말고 validate 후 baseline migration으로 기준점을 먼저 만든다. - baseline은 `code-first`, `concept-first`, `blank` 모두에서 생성된 agent-ui 기준선을 뜻한다. `concept-first` baseline은 코드 구현 완료가 아니라 agent-ui 기준선 확정이다. - `last_synced_head`는 agent-ui 변경분과 코드 반영이 들어간 sync 결과 commit hash다. `.sync-state.json` 자체를 기록한 commit hash가 아니다. +- schema version 2의 `pending_code_work`는 `plan-required` 코드 작업의 task/UI 매핑이다. 일반 plan/review/complete.log는 이 매핑 schema를 알 필요가 없다. +- pending entry는 `prepare-code-work`만 생성/갱신하고 `reconcile-completion` 검증 통과 시에만 제거한다. 실패, ambiguous completion, evidence 부족에서는 유지한다. +- `reconcile-completion`은 matching agent-ui/code 결과를 모두 포함하는 commit hash가 검증된 경우에만 `last_synced_head`를 갱신한다. 그렇지 않으면 기존 기준점을 보존하고 notes에 사유를 남긴다. - baseline 또는 sync 완료 시 commit은 두 단계로 남길 수 있다. 먼저 agent-ui/code 변경 commit을 만들고, 그 commit hash를 `.sync-state.json`에 기록한 별도 commit을 만든 뒤 push한다. - 변경분 판정에서는 `.sync-state.json` 자체 변경을 제외한다. 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 1bb8d3b..bf58c06 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 @@ -50,6 +50,7 @@ source_evidence: - frame은 definition을 대체하지 않는다. - `구현됨`, `계획`, `가정`, `불명확` 상태를 섞어 쓰지 않는다. - 기본 코드 동기화는 `.sync-state.json` 기준 이후 변경분만 대상으로 한다. +- plan-required 코드 작업의 task/UI 매핑과 완료 정합화는 `.sync-state.json.pending_code_work`를 사용한다. - 전체 동기화는 사용자가 명시한 경우에만 수행한다. ## Decision History 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 1b1a0e7..1afa79d 100644 --- a/agent-ops/skills/common/_templates/agent-ui/readme-template.md +++ b/agent-ops/skills/common/_templates/agent-ui/readme-template.md @@ -16,7 +16,7 @@ surface_type: ops-dev - `definition/`: 현재 UI 정의 source of truth - `frame/`: visual source가 있는 view의 wireframe 연결 -- `.sync-state.json`: agent-ui -> code 동기화 기준점 +- `.sync-state.json`: agent-ui -> code 동기화 기준점과 plan-required pending task 매핑 - `USER_REVIEW.md`: 사용자 판단이 필요한 활성 질문 - `archive/user-review/`: 해결된 사용자 리뷰 로그 @@ -26,4 +26,5 @@ surface_type: ops-dev - visual wireframe은 visual source가 있을 때만 `frame/**`에 둔다. - `.excalidraw` 파일만으로 UI 기준을 확정하지 않는다. - 초기 생성 이후 기본 흐름은 `agent-ui -> code` 방향이다. +- plan-required 코드 작업은 `.sync-state.json.pending_code_work`로 연결하고 일반 code-review 완료 뒤 `sync-agent-ui`가 정합화한다. - `definition/archive/**`와 `archive/user-review/**`는 과거 기록이며 일반 작업에서 읽지 않는다. diff --git a/agent-ops/skills/common/router.md b/agent-ops/skills/common/router.md index f556c71..24b11ec 100644 --- a/agent-ops/skills/common/router.md +++ b/agent-ops/skills/common/router.md @@ -10,6 +10,8 @@ - SDD 생성/갱신/잠금 해제는 `roadmap-sdd` 또는 `update-roadmap` 요청으로 처리한다. - 런타임이 `origin-task`/`complete-log` 단건 완료 이벤트를 전달한 경우는 `update-roadmap`으로 처리한다. - active/archive `complete.log`, 관련 파일, git history를 종합해 Milestone 작업 상태를 복구하거나 확인하는 요청은 `sync-milestone-workstate`로 처리한다. +- plan 요청에 사용할 테스트 환경 규칙이 있으면 `update-test mode=resolve-context`로 read-only `Verification Context`를 만든 뒤 `plan`에 전달한다. 규칙이 없거나 매칭되지 않으면 파일을 생성하지 않고 plan의 repository-native fallback을 사용한다. +- `sync-agent-ui`가 `plan-required`로 라우팅한 작업은 plan pair 생성 뒤 `sync-agent-ui mode=prepare-code-work`로 task/UI 매핑을 기록한다. 일반 code-review PASS와 exact `complete.log` 생성 뒤에는 `sync-agent-ui mode=reconcile-completion`으로 해당 매핑만 정합화한다. | 요청 키워드 | SKILL.md | |------------|----------| @@ -19,9 +21,9 @@ | agent-ui 생성, UI 스캐폴드 생성, UI 정의 구조 생성, 화면 정의 구조 생성, agent-ui scaffold | `agent-ops/skills/common/create-agent-ui/SKILL.md` | | agent-ui 갱신, agent-ui 업데이트, view 추가, component 추가, frame 추가, wireframe 추가, 화면 정의 갱신, 화면 정의서 갱신, 화면정의서 수정, 화면 정의서에 추가, 화면 정의서에서 제거, 와이어프레임 수정, 와이어프레임에 추가, wireframe 수정, wireframe에 추가, agent-ui USER_REVIEW 해결, UIR 결정 반영 | `agent-ops/skills/common/update-agent-ui/SKILL.md` | | agent-ui 검증, agent-ui validate, UI 정의 정합성 확인, wireframe 정합성 확인, 화면정의서와 wireframe 맞춰, 화면 정의서와 와이어프레임 정합성 확인, 화면정의서와 코드가 안 맞아, UI 스캐폴드 검사 | `agent-ops/skills/common/validate-agent-ui/SKILL.md` | -| agent-ui와 코드 동기화, agent-ui와 코드 전체 동기화, 화면정의서대로 코드 반영, 화면 정의서 변경사항 구현, wireframe 변경사항 구현 | `agent-ops/skills/common/sync-agent-ui/SKILL.md` | +| agent-ui와 코드 동기화, agent-ui와 코드 전체 동기화, 화면정의서대로 코드 반영, 화면 정의서 변경사항 구현, wireframe 변경사항 구현, agent-ui 코드 작업 준비, agent-ui 완료 정합화 | `agent-ops/skills/common/sync-agent-ui/SKILL.md` | | create-test, 테스트 룰 작성, 테스트 룰 생성, 테스트 규칙 작성, 테스트 규칙 생성, 테스트 환경 생성, 상황별 테스트 문서 생성, 도메인별 테스트 문서 생성, 검증 시나리오별 테스트 문서 생성, test rule 생성, agent-test 생성 | `agent-ops/skills/common/create-test/SKILL.md` | -| update-test, 테스트 룰 수정, 테스트 룰 갱신, 테스트 규칙 수정, 테스트 규칙 갱신, 테스트 환경 수정, 상황별 테스트 문서 수정, 도메인별 테스트 문서 수정, 검증 시나리오별 테스트 문서 수정, test rule 수정, agent-test 수정 | `agent-ops/skills/common/update-test/SKILL.md` | +| update-test, 테스트 룰 수정, 테스트 룰 갱신, 테스트 규칙 수정, 테스트 규칙 갱신, 테스트 환경 수정, 상황별 테스트 문서 수정, 도메인별 테스트 문서 수정, 검증 시나리오별 테스트 문서 수정, test rule 수정, agent-test 수정, 테스트 컨텍스트 해석, Verification Context 생성 | `agent-ops/skills/common/update-test/SKILL.md` | | 계약 생성해, 프로젝트 계약 생성해, 프로젝트 계약 생성, contract 생성, agent-contract 생성, 계약 문서 생성, inner 계약 생성, outer 계약 생성 | `agent-ops/skills/common/create-contract/SKILL.md` | | 계약 업데이트해, 프로젝트 계약 업데이트해, 프로젝트 계약 업데이트, 계약 갱신해, 계약 갱신, 계약 수정, 계약 정리, contract update, agent-contract 갱신, inner 계약 갱신, outer 계약 갱신 | `agent-ops/skills/common/update-contract/SKILL.md` | | 스펙 생성, 구현 스펙 생성, 현재 구현 문서화, agent-spec 생성, living spec 생성, 완료된 기능 스펙 작성 | `agent-ops/skills/common/create-spec/SKILL.md` |