Agent UI 공통화로 반복 구현 영역 약 60% 재사용

Context

Agent마다 입력·결과 표현은 달랐지만, 입력 → 실행 → 결과 확인 흐름은 동일했습니다. 화면 복제만으로는 프로젝트가 늘수록 수정 비용과 품질 편차가 커지는 구조였습니다.

Problem

• 입력·실행 상태·결과 UI가 프로젝트마다 유사하게 재구현됨
• 상태/에러 기준 변경 시 여러 레포에 동일 수정 반복
• 신규 프로젝트마다 UI·흐름 기준이 달라짐

Options

1. 프로젝트별 독립 구현 유지
2. 화면 단위 공통 컴포넌트만 추출
3. 컴포넌트 + Hook + 상태 규약을 npm 패키지로 publish ← 선택

고객사 요구를 막지 않으면서, 반복 실행 흐름은 한 곳에서 고치고 신규 프로젝트에 빠르게 조립할 수 있어야 했습니다.

Solution

반복 인터랙션을 @ara/agent-ui 패키지로 추출해 npm publish했습니다.
소비 앱(제조 MLOps · 유통 · 의료)은 패키지를 의존성으로 설치하고, 도메인 전용 입력·결과 UI만 추가합니다.

flowchart TB
pkg["@ara/agent-ui npm"]
subgraph package [Published package]
  common[Common UI]
  core[Hooks + Zustand stores]
  parsers[Stream parsers + query keys]
end
pkg --> package
package --> mlops[제조 MLOps]
package --> retail[유통]
package --> medical[의료]

공통 흐름 · 레이어

flowchart LR
subgraph flow [공통 사용자 흐름]
  in[입력] --> run[실행]
  run --> out[결과 동기화]
end
subgraph pkg [npm package]
  L1[Common]
  L2[Execution hooks]
  L3[State stores]
end
subgraph app [Consumer app]
  D[Domain UI only]
end
pkg --> app
flow -.-> pkg

실행 상태 · 도메인 확장

패키지에는 idle → running → success/error 축을 공통 규약으로 두고, 전송 방식만 도메인에서 확장했습니다.

flowchart TB
state["공통 상태: idle → running → success / error"]
state --> ml[제조 MLOps]
state --> rt[유통]
state --> md[의료]
ml --> ml_run["SSE + Workflow 폴링"]
ml --> ml_out["실행 큐 · 로그"]
rt --> rt_run["SSE parser"]
rt --> rt_out["매칭 · 다운로드"]
md --> md_run["WebSocket partial"]
md --> md_out["Question · Report"]

재사용률 ~60% (추정): Common · store · 실행 훅 · 파서를 패키지에서 가져오고, 도메인 전용 화면만 추가하는 비율 기준.

의도적 분리: API 스키마, 이벤트 타입, 결과 렌더링, 인증·라우팅은 앱에 유지해 과도한 추상화를 피했습니다.

Results

• 3개 이상 Agent 프로젝트의 동일 수정을 패키지 한 곳으로 흡수
• 반복 구현 영역 약 60% 재사용 (추정, 패키지 vs 앱 전용 화면 비율 기준)
• 신규 Agent 초기 화면 구성 시간 단축
• 패키지 버전 기준으로 리뷰·품질 기준 일관화

What I’d do next

• semver·CHANGELOG 기준을 강화해 소비 앱 간 의존성 충돌을 줄입니다.
• breaking change 시 마이그레이션 가이드를 패키지 README에 함께 제공합니다.