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

7.6 KiB
Raw Blame History

name version description
sync-agent-ui 1.0.0 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-state.json 기준점을 갱신한다. "agent-ui와 코드 동기화", "화면정의서대로 코드 반영" 요청 시 사용한다.

sync-agent-ui

목적

정합화된 agent-ui/ 변경분을 실제 UI 코드에 반영한다. 기본 동작은 .sync-state.json의 last_synced_head 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.

언제 호출할지

  • 사용자가 "agent-ui와 코드 동기화", "화면정의서대로 코드 반영", "wireframe 변경사항 구현"을 요청할 때
  • update-agent-ui 또는 validate-agent-ui가 code sync 필요성을 판단했고 현재 범위에 미해결 USER_REVIEW가 없을 때
  • 사용자가 "agent-ui와 코드 전체 동기화"처럼 full sync를 명시할 때

입력

  • mode: incremental 또는 full. 기본값은 incremental (선택)
  • scope: all, view:<view-id>, component:<component-id> 중 하나. 기본값은 all (선택)
  • validated: true 또는 false. 기본값은 false (선택)
  • sync-intent-source: manual, update-agent-ui, validate-agent-ui 중 하나 (선택)
  • push: true 또는 false. 기본값은 true (선택)

먼저 확인할 것

  • agent-ops/rules/common/rules-agent-ui.md를 읽는다.
  • agent-ui/와 agent-ui/definition/index.md 존재 여부를 확인한다.
  • validated=true가 아니면 먼저 validate-agent-ui를 실행한다.
  • agent-ui/USER_REVIEW.md가 있으면 현재 sync 범위와 관련된 미해결 항목이 없는지 확인한다.
  • agent-ui/.sync-state.json을 읽는다. 없고 mode=incremental이면 legacy baseline migration 필요로 보고 code sync를 시작하지 않는다.
  • 수정할 UI 코드 경로에 해당하는 project/domain rule을 먼저 읽는다.
  • 코드 변경 검증이 필요하면 작업 환경의 agent-test/<env>/rules.md를 읽는다. 환경 미지정은 local로 본다.
  • git status --short와 현재 HEAD를 확인한다.
  • unrelated dirty worktree가 있으면 sync commit 전에 범위를 보고하고, agent-ui와 관련 코드 파일만 stage한다.
  • 이전 sync 실패로 남은 관련 작업트리 변경이 있으면 보존할지, 사용자 결정과 충돌하는지 확인한다.

실행 절차

  1. 동기화 범위 확정

    • .sync-state.json이 없고 mode=incremental이면 현재 agent-ui를 legacy baseline 후보로 본다.
    • legacy baseline 후보는 validate-agent-ui 통과 후 agent-ui baseline commit과 .sync-state.json commit을 남기는 migration으로 처리하고, 같은 실행에서 코드 반영은 하지 않는다.
    • mode=incremental이면 .sync-state.json.last_synced_head 이후 현재 HEAD/worktree까지의 agent-ui 변경분을 확인한다.
    • 변경분 판정에서 agent-ui/.sync-state.json 자체는 제외한다.
    • mode=full이면 현재 활성 agent-ui/definition/**과 agent-ui/frame/** 전체를 코드와 대조한다.
    • mode=full에서 .sync-state.json이 없으면 code sync 성공 후 새 sync state를 만든다.
    • 가정 또는 불명확 상태 항목은 코드 반영 대상에서 제외하고 USER_REVIEW로 남긴다.
    • 현재 범위에 미해결 USER_REVIEW가 있으면 중단한다.

  2. 코드 반영

    • 계획 상태의 view/component/frame 요구사항을 UI 코드에 반영한다.
    • existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
    • definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
    • wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.
    • 코드 반영이 끝난 항목은 agent-ui 문서의 status를 구현됨으로 갱신하고 Source Evidence에 코드 경로를 남긴다.

  3. 검증

    • 관련 domain rule과 agent-test rule에 맞는 최소 검증을 실행한다.
    • 검증 실패가 명확하고 에이전트가 해결 가능하면 수정과 검증을 반복한다.
    • 구현 방향 충돌, 환경/권한 차단, 반복 실패, 사용자 판단이 필요한 시각 결과는 agent-ui/USER_REVIEW.md에 남기고 중단한다.
    • USER_REVIEW로 중단하면 commit/push하지 않고 .sync-state.json도 갱신하지 않는다.
    • USER_REVIEW로 중단할 때 관련 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, 재개 진입점과 변경 파일을 USER_REVIEW에 남긴다.

  4. sync state와 commit/push

    • 검증이 통과하면 agent-ui/code 변경을 먼저 commit한다.
    • 방금 만든 sync 결과 commit hash를 agent-ui/.sync-state.json의 last_synced_head에 기록한다.
    • .sync-state.json이 없으면 agent-ops/skills/common/_templates/agent-ui/sync-state-template.json 기준으로 새로 만든다.
    • .sync-state.json에는 last_sync_mode, last_synced_at, agent_ui_paths, code_paths, notes를 갱신한다.
    • .sync-state.json 변경을 별도 commit한다.
    • commit message는 예를 들어 sync: apply agent-ui to code와 sync: record agent-ui sync state처럼 목적이 분리되게 쓴다.
    • push=true이면 두 commit을 push한다.

  5. 결과 보고

    • sync mode와 scope
    • 반영한 agent-ui 파일과 코드 파일
    • 변경한 status
    • 실행한 검증
    • sync 결과 commit hash와 sync-state commit/push 결과
    • USER_REVIEW 생성/갱신 여부

실행 결과 검증

  • validate-agent-ui가 먼저 실행되었거나 validated=true 근거가 있는가
  • 현재 sync 범위에 미해결 USER_REVIEW가 없는가
  • 가정 또는 불명확 항목을 코드로 반영하지 않았는가
  • 코드 반영된 항목의 status가 구현됨이고 code evidence가 있는가
  • 관련 검증이 통과했는가
  • 실패 또는 차단 시 commit/push와 .sync-state.json 갱신을 하지 않았는가
  • 실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
  • 성공 시 sync 결과 commit과 .sync-state.json commit이 분리되었는가
  • .sync-state.json.last_synced_head가 sync 결과 commit hash를 가리키는가
  • unrelated dirty file이 sync commit에 포함되지 않았는가
  • 검증 실패 시: 에이전트가 해결할 수 없으면 agent-ui/USER_REVIEW.md에 남기고 중단한다.

출력 형식

## agent-ui 코드 동기화 결과: <PASS|USER_REVIEW|FAIL>

- Mode: <incremental|full>
- Scope: <scope>
- Agent UI Changes: <파일 목록 또는 없음>
- Code Changes: <파일 목록 또는 없음>
- Status Updates: <구현됨 전환 목록 또는 없음>
- Verification: <명령과 결과>
- Sync Commit: <hash 또는 없음>
- Sync State Commit/Push: <완료/생략/실패>
- USER_REVIEW: <생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>

금지 사항

  • validate-agent-ui를 거치지 않고 코드 동기화를 시작하지 않는다.
  • 미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
  • 가정 또는 불명확 상태 항목을 코드로 구현하지 않는다.
  • 검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
  • .sync-state.json을 agent-ui 변경분 판정 대상으로 삼지 않는다.
  • 정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
  • 실패한 sync의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.