Creative Agent Studio on ICE-ICE-BEAR-BLOG

Creative Agent Studio 개발일지 #5 — 폴리시 주간: LLM 토큰 텔레메트리, 멀티세션 격리, 인라인 되감기, 그리고 수정요청 어포던스

Thu, 28 May 2026 00:00:00 +0900

개요

이전 글: #4 — 5개 게이트, 4개 캔버스, 수정 모드 시스템이 빌드아웃 푸시를 끝냈다. 6일 뒤, 4 작업일에 23커밋이 폴리시 주간을 마무리했다 — 기능 완성된 시스템을 실제 사용자의 손 아래 production에서 버티는 무언가로 바꾸는 종류의 작업.

주중에 네 갈래가 병렬로 흘렀다. 첫째, LLM 호출 관측성 — 모든 모델 호출이 이제 토큰 사용량과 전파된 logCtx를 갖춘 구조화 로그를 발신하고, 런타임은 LOG_LEVEL 임계 제어를 받았다. 둘째, 새로고침 아래 프로젝트별 상태 격리 — 2026-05-26의 여덟 커밋이 멀티세션 작업이 떨어진 뒤 표면화된 hooks-order 버그, 끊긴 부트스트랩, crypto.randomUUID 격차를 사냥했다. 셋째, 인라인 과거-게이트 되감기 — 단일 feat 커밋이 사용자가 활성 콘티 세션 안에서 “GATE 2의 세 번째 카피로 바꿔줘"라고 말하고 세션을 떠나지 않을 수 있는 어포던스를 출시했다. 넷째, 수정요청 어포던스 패스 — 다섯 커밋이 모든 캔버스 탭의 마킹 카드 비주얼을 통일하고, 되돌리기 다이얼로그 카피를 다듬고, 게이트 셀렉터가 사용자가 방금 클릭한 카드를 잊는 상태 버그를 수정했다.

graph TD
 Prev["#4 — 빌드아웃 (5cb4106)"] --> Thread1["갈래 1 <br/> LLM 관측성 <br/> 토큰 사용량 + logCtx"]
 Prev --> Thread2["갈래 2 <br/> 프로젝트별 격리 <br/> hooks order + 부트스트랩 수정"]
 Prev --> Thread3["갈래 3 <br/> 인라인 과거-게이트 되감기 <br/> 채팅 주도 파이프라인 편집"]
 Prev --> Thread4["갈래 4 <br/> 수정요청 UX <br/> 통일된 마킹 카드 어포던스"]
 Thread1 --> End["#5 종료 (67b820e) <br/> 2026-05-28"]
 Thread2 --> End
 Thread3 --> End
 Thread4 --> End

관통하는 한 주제 — 기능은 끝났다. 남은 건 새로고침, 부하, 그리고 혼란스러운 사용자 아래에서 정직하게 만드는 일이었다.

갈래 1 — LLM 호출 관측성

#2에서 떨어진 구조화 로거가 토대였다 — 이번 주는 그것을 모든 LLM 호출 사이트에 꿰어서 production 텔레메트리가 실제로 의미를 갖게 했다.

두 커밋이 무거운 짐을 졌다.

feat(logger): add LOG_LEVEL threshold, silence node:sqlite warning — LOG_LEVEL env var로 production이 info 잡담을 떨구고 warn/error만 유지할 수 있다. 동반 변경은 모든 워커 fork에서 출력되던 node:sqlite 실험적 경고를 억제했다.
feat(observability): emit structured logs across worker + lifecycle paths — runtime/workers/worker-loop.js와 runtime/orchestration/run-lifecycle.js가 이제 각 의미 있는 전이(잡 클레임, 실행 시작, 게이트 발신, 단계 전진, 실행 완료/오류)에서 구조화 이벤트를 로깅.
feat(observability): instrument LLM calls with token usage + logCtx — 이게 하중 지지 조각이다. 모든 모델 호출이 이제 다음을 로깅.

// runtime/agents/_llm-instrument.js (의역)
async function callModelWithLogging(model, prompt, logCtx) {
 const start = Date.now();
 try {
 const result = await model.generate(prompt);
 logger.info("llm_call", {
 ...logCtx,
 model: result.model,
 prompt_tokens: result.usage?.input_tokens,
 output_tokens: result.usage?.output_tokens,
 duration_ms: Date.now() - start,
 cached_tokens: result.usage?.cached_input_tokens ?? 0,
 });
 return result;
 } catch (err) {
 logger.error("llm_call_failed", { ...logCtx, error: err.message, duration_ms: Date.now() - start });
 throw err;
 }
}

logCtx는 worker-loop.js에서 전파되며 { runId, projectId, stage, role }를 들고 다닌다. 그래서 단일 LLM 호출의 로그 줄이 어느 프로젝트, 어느 세션, 어느 게이트, 어느 에이전트, 어느 모델, 토큰이 얼마나 들었는지를 말해준다. #2에서 셋업했던 Grafana 대시보드에 이제 실제 데이터가 흐른다.

인프라 측 동반은 feat(terraform): widen EC2 start cron to every day + fix(terraform): update daily stop schedule to 03:00 KST. EC2 인스턴스는 프로토타입 시절부터 평일 전용 스케줄로 돌고 있었다 — cron이 이제 매일 박스를 시작하고 03:00 KST에 멈춘다. 운영, 기능 작업 아님.

갈래 2 — 새로고침 아래 프로젝트별 상태 격리

#4의 멀티세션 작업이 새로고침 시점 버그의 전체 부류를 도입했다. 사용자가 workspace 안에서 하드 새로고침하면, React 트리는 어떤 데이터도 로드되기 전에 마운트된다 — 그리고 멀티세션 로직은 사용자가 launcher에서 workspace로 들어왔을 때만 성립하는 가정(부트스트랩이 이미 일어났다)을 만들고 있었다.

2026-05-26의 여덟 커밋이 엣지 케이스를 사냥했다.

fix(web): bootstrap projects on workspace refresh, fix hooks order — workspace 페이지가 projects가 이미 로드됐다고 가정했다. 새로고침 시에는 아니었다. 수정은 workspace effect 안에 부트스트랩 호출을 추가했다 — 하지만 그게 React hooks-order 위반을 트리거했다, 부트스트랩 호출이 useEffect 안에서 조건부였기 때문. 둘 다 한 커밋으로 수정됐다.

fix(web): isolate per-project state on switch, show loader during session hydration — 프로젝트 A에서 B로 전환할 때 A의 세션 목록이 B가 로딩되는 동안 보이고 있었다. 수정 — projectId가 바뀌면 즉시 프로젝트별 슬라이스를 비우고 로더를 보여준 다음 B의 데이터를 hydrate. 사용자는 잠깐의 로더를 보지, A의 세션을 B에 잘못 귀속시키지 않는다.

fix(web): don't strand /sessions bootstrap behind a stale ref guard — ref로 구현된 “이미 부트스트랩 중이면 재부트스트랩하지 마라” 가드가 있었다. ref가 true로 세팅된 뒤 특정 에러 경로에서 클리어되지 않아, 후속 네비게이션이 stranded됐다. 수정 — 부트스트랩 상태를 ref가 아니라 슬라이스에서 추적하고, 성공 과 실패 모두에서 클리어.

fix(web): make Composer first-brief-only, flip ApproveBar toggle label — Composer(채팅 입력)가 모든 사용자 턴의 진입점이었다. 하지만 세션이 첫 브리프 너머로 가면 게이트 기반 흐름이 인계한다 — Composer의 역할은 숨겨져야 했다. 수정은 첫 브리프가 제출되기 전에만 Composer를 보이게 만들었다 — 그 뒤로는 ApproveBar가 사용자의 표면.

fix(web): make bootstrap dep stable so /sessions can't be cancelled forever — useChatStream이 의존성 배열이 불안정한 AbortController를 사용하고 있어서 매 재렌더마다 abort됐다. 수정은 dep를 안정화해서 컨트롤러가 실제 사용자 취소 또는 언마운트에서만 abort되게 했다.

fix(web): polyfill crypto.randomUUID so HTTP prod can create projects/sessions — production EC2가 일부 클라이언트에 평문 HTTP로 서빙하고 있었고(중간 프록시가 HTTPS를 떼어냈다), crypto.randomUUID는 secure context에서만 사용 가능하다. 프로젝트와 세션이 생성될 수 없었다. 폴리필이 복원.

마지막이 이 주에서 가장 “production이 dev 환경이 숨겼던 걸 드러낸다” 케이스다. 로컬호스트는 secure context. 배포 타깃은 항상 그렇지는 않다. 한 줄 폴리필이 EC2 빌드를 사용 가능하게 유지했다.

fix: preserve 분석 보고서 across key-concept revisions — 런타임 수정 동반. 사용자가 GATE 1에서 키 컨셉 선택을 수정할 때, 분석 보고서가 함께 재계산되고 있었다 — 불필요한 작업이고 매번 약간 다른 보고서를 만들었다. 수정은 키 컨셉 수정에 걸쳐 원래 분석을 고정.

그리고 docs(claude): register Diffs Runtime harness pointer in CLAUDE.md가 Claude Code 세션이 런타임의 하네스 규약을 자동으로 찾을 수 있도록 포인터를 추가했다.

갈래 3 — 채팅에서 인라인 과거-게이트 되감기

단일 커밋이 큰 UX 이동을 출시했다 — feat(web): add inline past-gate rewind for chat-driven pipeline edits.

설정 — 폴리시 주간이 되자 사용자는 현재 게이트에 대한 수정 모드를 가진 ApproveBar를 갖췄고, 워크플로는 한 번에 한 단계씩 전진했다. 그런데 사용자가 과거 결정을 바꾸고 싶으면? “사실 두 번째 키 컨셉으로 가자” — 콘티 단계에 앉아서?

이전엔 캔버스를 떠나, 수동으로 GATE 1으로 돌아가고, 재선택하고, 후속 모든 게이트를 다시 걸어야 했다. 고통스럽고, 채팅 우선 원칙 위반.

인라인 되감기는 채팅에서 과거-게이트 의도를 감지한다.

// (의역 — 결합된 chat-stream + dispatch-sse 경로)
// 백엔드가 채팅 메시지를 분류:
// "두 번째 키 컨셉으로 다시 가자" → rewind_intent: { gate: "GATE_1", selection: 2 }
// 프론트엔드가 rewind_proposal SSE 이벤트 수신:
{
 kind: "rewind_proposal",
 fromGate: "GATE_5",
 toGate: "GATE_1",
 affectedDownstreamGates: ["GATE_2", "GATE_3", "GATE_4", "GATE_5"],
}
// UI가 인라인 ConfirmRewindDialog 표시 (갈래 4에서 다듬은 것)

다이얼로그는 폐기될 것을 명시적으로 나열한다 — GATE 2의 카피 승인, GATE 4의 시나리오 승인 등 — 그래서 사용자가 확인 전 비용을 안다. 확인 시 런타임이 프로젝트를 타깃 게이트로 되돌리고, 하류 모든 것을 재생성하고, 사용자는 새 선택을 할 준비가 된 타깃 게이트의 승인 표면에 도착한다.

이건 게이트 기반 자동 실행 원칙(interaction-model.md의 결정 3)의 자연스러운 확장이다 — 단 역방향으로. 원칙은 — 각 단계는 사용자 승인에서 다음으로 전진. 되감기는 — 각 단계는 되돌아갈 수도 있고, 런타임은 무엇을 무효화할지 안다.

동반 docs(claude): add triage-prod-bug skill trigger to enforce browser-first debugging는 하네스 규칙이다 — 버그가 보고되면, 코드를 읽기 전에 브라우저를 먼저 본다(devtools, network, console). 채팅 우선 제품 원칙에는 디버깅 유사물이 있다 — 먼저 보고, 그 다음 코드.

갈래 4 — 수정요청 어포던스 패스

마지막 다섯 커밋이 모든 캔버스 탭의 수정요청 UI를 통일했다. 이 작업 전까지 모든 탭은 자기 마킹 카드 스타일을 구현하고 있었다 — Copy에는 노란 배경, KeyConcept에는 빨간 점선 테두리, Storyboard에는 파란 왼쪽 엣지 바(이거 하나만), Scene에는 비주얼 처리 전혀 없음 — 그리고 사용자가 계속 물었다 — “왜 콘티에만 파란 마크가 뜨나요?”

되돌리기 다이얼로그 카피 완화 + 폐기 리스트에서 최종 게이트 숨기기

커밋 e27316a. 첫 공격은 가장 거슬리던 카피였다. 되돌리기 다이얼로그가 이렇게 읽혔다.

“이 결정을 되돌릴까요?” “카피 검토 단계부터 다시 진행합니다.” “아래 후속 결정이 새 버전으로 대체됩니다:” – 컨셉 확정 결정 – 시나리오 검토 결정 – 최종 승인 결정 ← 이 리스트에 있으면 안 됨

두 문제 — 폐기 리스트에 최종 승인 게이트가 들어가 있었지만(그건 끝에 다시 확정하는 단계지 사라지는 단계가 아님), “결정"이라는 단어가 너무 기업스러웠다. 실제로는 초안에 대한 크리에이티브 판단이지 이사회 안건이 아니다.

// web/src/components/approve/ConfirmRewindDialog.tsx
<ul data-testid="confirm-rewind-discard-list">
 {gates
 .filter(g => g.kind !== 'final-approval')
 .map(g => <li key={g.id}>{g.softTitle}</li>)}
</ul>

폐기 미리보기에서 final-approval 게이트를 빼고, softTitle(예: “콘티 검토 결정” 대신 “콘티 검토”)을 쓴다. 같은 Gate 인터페이스에서 가져오지만 파괴적 컨텍스트와 정보성 컨텍스트에서 다르게 렌더링한다.

되돌리기 다이얼로그의 게이트 타이틀

커밋 4ddff68. 다이얼로그가 기계 생성 게이트 id(g-2, g-3)를 타이틀로 쓰고 있었다. 작은 라벨 맵이 이해도를 고쳤다.

const GATE_LABELS: Record<GateKind, string> = {
 'concept-confirm': '컨셉 검토',
 'scenario-review': '시나리오 검토',
 'storyboard-approve':'콘티 검토',
 'cut-finalize': '컷 검토',
 'final-approval': '최종 승인',
};

이제 다이얼로그가 “콘티 검토 단계부터 다시 진행합니다"라고 읽힌다 — 캔버스 탭 라벨과 정확히 일치하는 표현이라, 사용자가 되감기 후 어느 탭에 도착할지 미리 알 수 있다.

수정요청 진입 시 ApproveBar 게이트 미리 선택

커밋 c55891b. 카드의 수정요청을 누르면 ApproveBar가 게이트 셀렉터와 함께 슬라이드 업했는데, 셀렉터가 비어 있어서 사용자가 방금 마킹한 게이트를 다시 클릭해야 했다. 두 줄짜리 useEffect로 암묵적 컨텍스트를 명시적 선택으로 동기화했다.

// web/src/components/approve/ApproveBar.tsx
useEffect(() => {
 if (mode === '수정요청' && activeCard) {
 setGateSelection(activeCard.gateId);
 }
 if (mode === 'idle') {
 setGateSelection(null); // 닫기 시 초기화
 }
}, [mode, activeCard]);

이 변경의 보안 리뷰 패스가 한 가지 노트를 표면화했다 — 게이트 id가 사용자 제어 DOM 이벤트에서 서버 사이드 뮤테이션으로 흘러가는데, 서버에서 어차피 현재 워크플로의 게이트 집합과 대조 검증하니 추가 클라이언트 검증은 불필요. 다만 그 불변식이 리뷰를 통해 명시적으로 기록됐다.

다섯 탭에 걸친 마킹 카드 비주얼 통일

커밋 2804420. 비주얼 통일 패스. 통일된 처리는 디자인 토큰 하나에 모았다.

// design-system / marked-card.css
.marked-card {
 position: relative;
 outline: 2px solid var(--color-revision);
 outline-offset: -2px;
}
.marked-card::before {
 content: '';
 position: absolute;
 top: 0; bottom: 0; left: 0;
 width: 3px;
 background: var(--color-revision);
}

그리고 모든 탭 컴포넌트는 이제 카드를 이렇게 감싼다.

<div className={cn('card', card.marked && 'marked-card')}>
 {card.marked && <RevisionLabel kind={card.kind} />}
 {/* 탭별 콘텐츠 */}
</div>

RevisionLabel도 추출했다 — 예전엔 각 탭이 자기 라벨을 인라인으로 만들면서 카피가 제각각이었다 (“수정 요청됨”, “리비전”, “Edit Pending”). 이제 컴포넌트 하나, 문자열 하나다.

모든 게이트 마커를 한 번씩만 표시하고 라이브 게이트 상태 반영

이 날의 마지막 커밋(67b820e). workspace 상단의 StageStepper가 어떤 상태에서 중복 게이트 마커를 표시하고 있었다(재발신된 게이트 이벤트가 두 번째 점을 추가) 그리고 실제 gate_state 전이보다 뒤처져 있었다. 한 수정에 두 버그.

게이트 id로 중복 제거해서 각 게이트가 정확히 한 번 렌더
파이프라인 슬라이스의 라이브 gate_state(#4의 12상태 필드)를 와이어드해서 stepper가 방금 일어난 어떤 전이든 반영

12상태 gate_state 필드는 일주일 전부터 있었지만, stepper는 여전히 오래된 “마지막 완료 게이트” 추론을 쓰고 있었다. 이 커밋이 그 격차를 닫았다.

커밋 로그 (총 23개)

날짜	메시지
2026-05-25	fix stale approve gates during storyboard runs
2026-05-25	feat(terraform): widen EC2 start cron to every day
2026-05-25	refactor(canvas): drop submit prop drilling, polish selected-copy card
2026-05-25	feat(logger): add LOG_LEVEL threshold, silence node:sqlite warning
2026-05-25	feat(observability): emit structured logs across worker + lifecycle paths
2026-05-25	feat(observability): instrument LLM calls with token usage + logCtx
2026-05-25	chore: refresh lockfile peer-dep flags
2026-05-26	fix(web): bootstrap projects on workspace refresh, fix hooks order
2026-05-26	docs(claude): register Diffs Runtime harness pointer in CLAUDE.md
2026-05-26	fix: preserve 분석 보고서 across key-concept revisions
2026-05-26	fix(web): isolate per-project state on switch, show loader during session hydration
2026-05-26	fix(web): don’t strand /sessions bootstrap behind a stale ref guard
2026-05-26	fix(web): make Composer first-brief-only, flip ApproveBar toggle label
2026-05-26	fix(web): make bootstrap dep stable so /sessions can’t be cancelled forever
2026-05-26	fix(web): polyfill crypto.randomUUID so HTTP prod can create projects/sessions
2026-05-27	docs(claude): add triage-prod-bug skill trigger to enforce browser-first debugging
2026-05-27	feat(web): add inline past-gate rewind for chat-driven pipeline edits
2026-05-27	fix(terraform): update daily stop schedule to 03:00 KST in variables
2026-05-27	fix(gitignore): add harnesskit session-logs to .gitignore
2026-05-28	fix(web): soften rewind dialog copy and hide final gate from discard list
2026-05-28	fix(web): update gate titles in ConfirmRewindDialog for clarity
2026-05-28	fix(web): preselect gateSelection on 수정요청 enter, clear it on 닫기
2026-05-28	fix(web): unify 수정요청 marked-card visual and label across all tabs
2026-05-28	fix(web): show every gate marker once and reflect live gate state

인사이트

폴리시 주간의 패턴 — 관측성과 격리 모두 조용히 가정되던 상태를 드러내는 일이었다.

LLM 토큰 텔레메트리가 실제로 돈을 쓰던 것을 드러냈다 — 이전 대시보드는 큐 깊이와 잡 지속시간을 보여줬는데 둘 다 중요하지만, 느린 에이전트가 쌀 수도 있고 빠른 에이전트가 비쌀 수도 있다, 토큰 사용량에 따라. logCtx를 모든 호출에 꿰어 넣자 비용 분석이 필요로 하는 프로젝트별, 단계별, 에이전트별 분해가 표면화됐다.

멀티세션 새로고침 수정들이 workspace가 자기 부트스트랩에 대해 가정하던 것을 드러냈다. 사용자가 launcher에서 들어왔을 때 기능이 작동했던 이유는 launcher의 부트스트랩이 우연히 만족된 전제조건이었기 때문. 새로고침이 그 전제조건을 깨자 버그가 표면화됐다 — 하지만 내내 거기 있었다, 잠복해.

인라인 과거-게이트 되감기는 같은 아이디어를 사용자의 멘탈 모델에 적용한 것이다 — 사용자는 *“GATE 1로 돌아가서 뭔가 바꾸고 싶다”*고 생각한다. 되감기 기능은 그 의도를 시스템에 노출시켜 사용자가 네비게이션 단계로 번역하도록 강제하지 않는다. 채팅 우선 원칙은 단지 입력 메커니즘이 아니다 — 시스템이 의도를 이해할 것이라는 약속이다.

수정요청 어포던스 패스는 같은 빙산의 작은 보이는 끝이다. 세 겹의 명료함 — 비주얼 일관성, 정직한 카피, 상태 보존 — 이 파괴적 워크플로 동작에 적용되어, 확인을 요청하는 다이얼로그가 잃게 될 것에 대해 진실을 말한다.

다음 — 여기서부터 시스템은 기능적으로 완성됐으니, 미래 개발일지는 기능 추가보다 production 교훈으로 기울 것이다 — 에이전트 프롬프트 튜닝, 비용 추세, 실제 사용자 세션에서 떠오르는 다음 라운드의 UX 패턴. 5포스트 백필이 깔끔한 호를 닫는다 — 목업, production-readying, 메가푸시, 게이트 워크플로, 폴리시. 제품이 이제 진짜다.

Creative Agent Studio 개발일지 #4 — 5개의 게이트, 4개의 캔버스, 그리고 수정 모드 시스템

Fri, 22 May 2026 00:00:00 +0900

개요

이전 글: #3 — 134커밋 메가푸시가 PR4(ApproveSheet + 세 게이트 변형)가 머지되고 프로젝트 상태가 리로드를 살아남는 상태로 끝났다. 3일 뒤 153 커밋이 더 떨어져 4단계 에이전트 워크플로의 남은 모든 조각을 완성했다 — 단계 출력을 실체화한 4변형 캔버스 패널(PR5), 새 GATE 1의 키 컨셉 플래너로 3게이트에서 5게이트로의 워크플로 통합, 하단 드로어 ApproveSheet를 슬림 ApproveBar + 출력 탭으로 대체한 UI 재설계, 그리고 사용자가 전체 단계를 다시 하는 대신 단일 키 컨셉, 카피 드래프트, 컷, 또는 콘티 패널을 외과적으로 재실행할 수 있게 하는 수정 모드 다중 선택 시스템.

아래에서는 런타임이 Planner-Generator-Evaluator 루프, 사용자 피드백으로부터 저작되는 연속성 앵커, 프롬프트에 주입되는 진화 노트, 기획 보고서와 콘티를 위한 HTML 템플릿 세트, 그리고 한 프로젝트가 여러 병렬 시도를 들고 갈 수 있도록 하는 세션 격리를 받았다.

graph TD
 Prev["#3 — 메가푸시 (9a2f851)"] --> Theme1["흐름 1 <br/> PR5 — 4단계 캔버스 <br/> + 리사이즈 + 접기"]
 Prev --> Theme2["흐름 2 <br/> 5게이트 워크플로 <br/> GATE 1에 키 컨셉 플래너"]
 Prev --> Theme3["흐름 3 <br/> ApproveBar + 출력 탭 <br/> 드로어 교체"]
 Prev --> Theme4["흐름 4 <br/> 수정 모드 시스템 <br/> 부분 vs 일괄 수정"]
 Theme1 --> End["#4 종료 (5cb4106) <br/> 2026-05-22"]
 Theme2 --> End
 Theme3 --> End
 Theme4 --> End

네 흐름, 반복되는 한 모양 — 워크플로가 만지는 모든 레이어에서 “전부 아니면 전무"가 되기를 멈췄다.

흐름 1 — PR5: 4단계 변형의 캔버스 패널

PR2가 CanvasPanel 플레이스홀더를 예약했다. PR5가 그것을 채웠다. 캔버스는 workspace의 오른쪽 컬럼 — 현재 단계의 현재 artifact를 단계별 컴포넌트로 렌더링한다.

// web/src/components/canvas/stage-canvas.tsx (의역)
function StageCanvas({ stage }: { stage: PresentationStage }) {
 switch (stage) {
 case "research": return <ResearchCanvas />;
 case "copy": return <CopyCanvas />;
 case "scenario": return <ScenarioCanvas />;
 case "storyboard": return <StoryboardCanvas />;
 }
}

각 변형은 pipeline 슬라이스에서 데이터를 읽고 단계에 맞는 레이아웃을 렌더한다.

단계	변형	보여주는 것
research	`ResearchCanvas`	`pipelineContext`의 `AdBriefRecap` + `ResearchSummaryCards` + 활성 태스크 목록
copy	`CopyCanvas`	`copyHistory`의 `CopyOptions`로 만든 `ConceptGrid`
scenario	`ScenarioCanvas`	Act별 `SceneStrip` + `scenarioHistory`의 `CutChip` 스트립
storyboard	`StoryboardCanvas`	`storyboardImageUrls`에서 scene당 `StoryboardPage` 1개

콘티 이미지 처리는 작은 아키텍처 선택이 필요했다. base64 PNG 페이로드가 storyboard_image SSE 이벤트로 도착한다. 파이프라인 슬라이스가 각각을 blob URL(URL.createObjectURL)로 변환하고, 재생성이 이전 이미지를 누수하지 않도록 replace-on-revoke 단계를 둔다. addStoryboardImage 리듀서가 revoke 로직을 갖는다.

addStoryboardImage: (scene, base64) => set(s => {
 const old = s.storyboardImageUrls[scene];
 if (old) URL.revokeObjectURL(old);
 const blob = base64ToBlob(base64, "image/png");
 return { storyboardImageUrls: { ...s.storyboardImageUrls, [scene]: URL.createObjectURL(blob) } };
}),

리사이즈 + 접기

두 커밋이 리사이즈 어포던스를 추가했다.

feat(web): add useCanvasResizer hook (pointer capture + clamped delta -> ui.canvasWidth) — ui.canvasWidth는 ui 슬라이스에서 360..800px로 클램프
feat(web): add CanvasResizer component (vertical drag handle + warm hover tint) — 비주얼 핸들, 호버 틴트는 Creative Warmth를 따른다(미묘한 따뜻한 그라데이션, 순백 하이라이트 없음)
feat(web): WorkspacePage grid column reads ui.canvasWidth + respects canvasCollapsed — 그리드가 실제로 너비에 반응

CanvasHeader는 접기 토글을 얻어서 파워 유저가 채팅에 집중하고 싶을 때 캔버스를 완전히 숨길 수 있다.

PR6 — 폴리시 + 백엔드 스왑 + 목업 삭제

PR6은 “React로 모든 게 동작한다"와 “실제로 사용자에게 React를 서빙한다” 사이의 다리였다.

feat(web): ui slice gains fatalError + setFatalError
feat(web): add ErrorScreen (vercel_unsupported + unexpected kinds, ko/en)
feat(web): add AppErrorBoundary class component (catches descendants -> ErrorScreen)
feat(web): useChatStream detects Vercel 503 -> ui.fatalError = vercel_unsupported
feat(server): serve web/dist instead of mockup/ (MOCKUP_DIR -> WEB_DIST_DIR)
feat(deploy): vercel buildCommand + outputDirectory point to web/dist
chore: remove legacy mockup/ vanilla-JS SPA — 목업이, 탄생 6주 만에, 한 커밋으로 삭제됐다

vercel_unsupported 에러는 특정 종류다 — Vercel의 서버리스 함수는 장기 SSE 연결을 호스트할 수 없으니, 거기 백엔드를 배포하면 채팅 라우트에서 503이 나온다. 프론트엔드가 이걸 명시적으로 감지하고 일반 네트워크 에러 대신 EC2 전용 제약을 설명하는 화면을 보여준다.

흐름 2 — 워크플로가 5게이트로 통합됨

PR4까지 워크플로는 승인 지점이 세 개였다 — 카피 뒤 하나, 시나리오 뒤 하나, 콘티 끝에 하나. 5월 21일이 **GATE 1(키 컨셉 선택)**을 도입하고 게이트 수를 다섯으로 만들었다.

GATE 1이 존재해야 했던 이유

기존 흐름은 research → copy로 직접 실행했다. 사용자가 브리프를 제출하면 리서치가 일어나고, 그 다음 카피 단계가 네 가지 평행 드래프트(각각 감성/직설/유머/하이브리드 각도)를 발신했다. 문제 — 카피 드래프트는 사용자에게 어느 방향을 원하는지 묻지 않고 리서치 에이전트의 브리프 해석을 상속받았다. 프로젝트당 이틀의 수정이 사용자가 요청하지 않은 다른 각도로 카피 단계를 밀어내는 데 들어가고 있었다.

수정은 리서치와 카피 사이에 새 스페셜리스트.

research → [key_concept_planner가 10개 후보 컨셉 생성: 3-3-2-2 분배]
 → GATE 1 (사용자가 하나 선택)
 → 카피 단계가 선택된 컨셉에 앵커링되어 실행

3-3-2-2 분배(상업적 3, 감성적 3, 내러티브 2, 컨셉추얼 2)는 CATEGORY_PLAN에서 왔다. 뒤이은 리팩토링(refactor(agents): derive key_concept distribution from CATEGORY_PLAN)이 분배를 하드코딩에서 계획으로부터 계산되게 바꿔서, 한 곳의 믹스 조정이 전파된다.

프론트엔드 — ApproveGateKeyConcept

10카드 선택 UI가 ApproveGateKeyConcept로 출시됐다.

feat(web): add KeyConcept gate types
feat(web): ApproveGateKeyConcept 10-card selection drawer
feat(web): wire GATE 1 key-concept gate into ApproveGate

백엔드 조각.

feat(runtime): emit GATE 1 key-concept gate after research stage
fix(runtime): only block key_concept_planner re-enqueue while job is in flight — 느린 재렌더 dispatch가 필터아웃되던 레이스 방지
feat(runtime): route selectedKeyConcept to copy and feedback re-entry — 카피 단계가 선택된 컨셉을 받는다
feat(agents): copywriter_agent anchors copy to the selected key concept
feat(runtime): persist key_concept_set artifacts + record GATE 1 key-concept selections in diff_history

GATE 3(컨셉 승인)와 GATE 5(최종 승인)

두 게이트가 더 워크플로를 채웠다.

feat(runtime): add GATE 3 컨셉 승인 — two-phase scenario stage — 시나리오가 컨셉 승인 → 전체 시나리오로 쪼개졌다
feat: add GATE 5 (최종 승인) to the storyboard stage — 프로젝트가 완료된 것으로 간주되기 전 최종 승인

GATE 2(카피)와 GATE 4(전체 시나리오)와 결합되면, 이게 이 시점부터 모든 UI 라벨이 참조할 정전 5게이트 흐름을 만들었다.

gate_state — 12상태 라이브 전이

feat(runtime): wire gate_state 12-state live transitions가 게이트 라이프사이클을 잡 라이프사이클에서 분리했다. 12상태가 모든 의미 있는 전이를 인코딩(pending → emitted → awaiting_user → user_approved → user_revising → rerunning → reapproved → …), 각각 프론트엔드로 표면화되어 UI가 추론된 상태를 폴링하지 않고 의미 있는 “이 게이트에 무슨 일이 일어나고 있는가"를 렌더할 수 있다.

GATE 1의 기획 보고서

feat: add report_writer agent + 리서치 분석 보고서 at GATE 1이 key_concept_planner와 나란히 도는 두 번째 스페셜리스트를 추가했다 — 10개 키 컨셉 뒤의 컨텍스트를 사용자에게 주는 구조화된 리서치 분석 보고서를 생성한다. 이게 없으면 사용자는 컨셉을 차갑게 선택한다 — 있으면 기저 추론을 본다.

그 다음 후속 — feat: add report_writer planning mode for 최종 기획 보고서 — 가 같은 에이전트에게 워크플로 끝에 다른 종류의 보고서(전체 프로젝트를 요약하는 기획 보고서)를 생성하도록 가르쳤다.

HTML 템플릿 세트

보고서는 채팅 버블이 아니라 문서처럼 보여야 했다. 연속된 커밋들에서 HTML 템플릿 세트 전체가 도착했다.

feat: add base.css slide canvas and primitives
feat: add storyboard cover and continuity-grid templates
feat: add deck.css and four simple deck templates
feat: add photo-caption and fullbleed-caption deck templates
feat: add annotated-photo, product-lineup, info-card, creative-board templates
feat: add report_writer HTML conversion design spec + implementation plan
feat: add template gallery index + LLM-facing template catalog

템플릿 카탈로그가 LLM 면 조각이다 — 다중 페이지 문서를 조립할 때 선택할 템플릿의 구조화된 리스트를 에이전트가 받는다. 그래야 페이지별 레이아웃을 핸드코딩하지 않고 콘티 커버, 연속성 그리드, 트리트먼트 그리드, 콘티 시퀀스를 한 프롬프트로 만들 수 있다.

흐름 3 — ApproveBar가 드로어를 교체하고, 출력 탭이 인라인 렌더를 교체

2026-05-21까지 하단 드로어 패턴(ApproveSheet)은 UX 문제가 됐다 — 열면 캔버스를 덮었고, 캔버스가 결과가 사는 곳이었다. 사용자는 승인 중인 콘티를 보기 위해 계속 드로어를 접어야 했다.

세 커밋이 드로어를 죽였다.

feat(web): add slim ApproveBar, replace ApproveGate in ChatPanel — 채팅 패널 하단의 가로 바
refactor(web): remove ApproveSheet/StageCanvas drawer stack
feat(web): show output panel on active gate + scenario gate advances

ApproveBar는 두 버튼(승인 / 수정요청) + 게이트 컨텍스트뿐이다 — 미니멀, 드래그할 드로어 없음. 검사할 실제 artifact는 캔버스(오른쪽 컬럼)에 산다, 늘 그랬듯이.

출력 탭 — 캔버스가 “현재 단계 표시"에서 “모든 단계의 탭 히스토리"로 피벗

ApproveBar가 떨어진 직후, 캔버스 자체가 재설계됐다.

feat(web): add output-tabs definitions and visibility logic
feat(web): add activeOutputTab to ui slice
feat(web): add output fields to pipeline slice
feat(web): hydrate output slots from artifacts
feat(web): route gate/planning outputs into pipeline slice
feat(web): add analysis/keyConcept/planning/concept tab bodies
feat(web): add selectable copy tab body
feat(web): add OutputTabs container
feat(web): swap CanvasPanel body to OutputTabs

이전엔 캔버스가 현재 단계의 artifact만 보여줬다. 이제 위쪽에 탭이 있다 — 분석, 키 컨셉, 컨셉, 카피, 시나리오, 콘티 — 그리고 사용자는 현재 단계에서 작업하면서도 이전 artifact를 되돌아볼 수 있다. 그게 UX를 완전히 바꾼다 — 캔버스가 단지 현재 상태 디스플레이가 아니라 프로젝트 작업면이 됐다.

Planner-Generator-Evaluator 루프

이 UX 이동의 런타임 등가물이 Planner-Generator-Evaluator 루프다.

feat: Planner-Generator-Evaluator loop + BDI structure
feat(web): register copy_evaluator in agent-copy map
feat(runtime): extend the evaluator loop to the scenario stage (§3.4)
feat(runtime): extend the evaluator loop to the storyboard stage (§3.4)
fix(runtime): re-assess regenerations in the evaluator loop

패턴 — 모든 생성 단계가 이제 Planner → Generator → Evaluator를 돈다. Evaluator는 출력이 품질 바를 만족하는지 결정한다 — 아니면 루프가 피드백과 함께 Generator를 재실행한다. 사용자는 루프가 수렴한(또는 최대 반복 상한을 친) 뒤 최종 출력을 본다. 이게 출력 탭이 가치 있어진 이유이기도 하다 — 각 단계의 기획 artifact와 평가 노트는 사용자가 파보고 싶을 때 보인다.

흐름 4 — 수정 모드 시스템

이게 이 윈도우에서 가장 큰 UX 약속이다. 이 작업 전에는 “카드 하나만 다시 하고 싶어요"는 “전체 단계를 다시 해주세요"를 의미했다 — 사용자가 재생성하고 싶은 조각 외 모든 걸 외과적으로 고정할 방법이 없었다.

의도 분류

첫 조각(feat: add revision-intent — classify chat revision as bulk/partial)이 채팅 입력의 작은 분류기다. 사용자가 게이트 컨텍스트에서 타이핑하면, 시스템이 묻는다 — 이게 일괄 요청(“카피 전체를 더 감성적으로”)인가 부분 요청(“세 번째만 바꿔줘”)인가? 출력이 다른 런타임 경로를 결정한다.

일괄 → 피드백을 컨텍스트로 두고 전체 단계 재실행
부분 → UI에서 “수정 모드"에 진입하고 사용자가 재생성할 항목을 고름

// runtime/orchestration/revision-intent.js (의역)
function classifyRevisionIntent(message, gateContext) {
 if (hasPartialMarkers(message)) return { kind: "partial", confidence: high };
 if (hasBulkMarkers(message)) return { kind: "bulk", confidence: high };
 return { kind: "ambiguous" }; // UI가 사용자에게 명확화를 nudge
}

수정 모드 UI

프론트엔드가 ApproveBar에 수정 모드 토글과 모든 선택 가능한 탭에 다중 선택 체크박스를 얻었다.

feat: pipeline store — reviseMode + reviseSelection state
feat: add RevisionContext type + ChatContext.revision field
feat: ApproveBar revise-mode toggle with selection count
feat: KeyConceptTab multi-select checkboxes in revise mode
feat: CopyTab multi-select checkboxes in revise mode
feat: ScenarioCanvas cut-level revise checkboxes
feat: StoryboardCanvas panel-level revise checkboxes

reviseSelection은 artifact 종류별 Set<id>다. 사용자는 개별 카드를 토글한다 — 카운트가 ApproveBar에 라이브로 나타나 몇 개 항목이 재생성될지 항상 안다.

Revision-merge — 인덱스 splice

런타임 측은 재생성된 부분집합을 기존 집합으로 실제로 머지할 방법이 필요했다. 그게 revision-merge 모듈이다.

// runtime/orchestration/revision-merge.js (의역)
function mergeRevision(originalSet, regeneratedSubset, selectedIndices) {
 const merged = [...originalSet];
 regeneratedSubset.forEach((newItem, i) => {
 merged[selectedIndices[i]] = newItem;
 });
 return merged;
}

순수 함수 — 선택된 인덱스에서 splice, 나머지는 고정. 끝까지 테스트됨 — test: end-to-end partial revision keeps frozen items + 3-3-2-2.

각 에이전트가 부분 재생성을 배웠다

다섯 스페셜리스트 에이전트가 선택된 슬롯만 재생성하는 법을 배웠다.

feat: key_concept_planner regenerates selected slots (category-preserving) — 3-3-2-2 분배를 보존
feat: copywriter_agent regenerates selected copy drafts
feat: concept_anchor applies revision feedback (GATE 3, whole-doc) — GATE 3은 컨셉 앵커 자체가 단일 artifact이기 때문에 whole-doc만
feat: scene_designer cut-level revision (structure + cut count preserved) — 총 컷 수 보존
feat: storyboard_generator regenerates selected panels + images

각 에이전트는 자기의 고정 항목 제약이 무엇인지 알아야 했다. 콘티는 컷 수를 재계산하지 않고 패널 3만 재생성할 수 있었지만, scene_designer는 시나리오의 구조적 계약이 컷 수이기 때문에 총 컷 수를 보존해야 했다.

라우팅 레이어

두 라우팅 커밋이 함께 묶었다.

feat: root-planner routes context.revision to single target agent — 백엔드가 필요한 단일 스페셜리스트만 enqueue
feat: route chat revision intent — bulk runs, partial nudges revise mode — 프론트엔드가 옳은 경로로 dispatch
feat: dispatch revise_mode_hint — open revise mode on partial chat intent — 백엔드가 힌트 이벤트로 프론트엔드에 수정 모드를 제안할 수 있어서 부분 의도가 UI를 자동으로 연다

힌트 이벤트는 신중한 경계였다 — 백엔드는 결코 프론트엔드를 강제하지 않는다, 제안만 한다. 프론트엔드는 자기 로컬 상태가 이유가 있으면 오버라이드할 수 있다.

흐름 5 — 세션 격리 (프로젝트당 멀티 시도)

2026-05-22에 workspace가 프로젝트당 단일 세션에서 프로젝트당 멀티 세션으로 갔다. 프로젝트가 이제 병렬 시도를 들고 갈 수 있다 — 단일 크리에이티브 브리프를 세 가지 다른 방식으로 시도할 수 있고, 각각 자기 세션이고 자기 파이프라인 상태를 갖는다.

핵심 커밋.

Isolate workspace sessions and restore state per session
server: project sessions list endpoint
web: session restore and run recovery
Start a fresh pipeline for a new session's first brief
launcher: show per-session states on project cards
launcher/workspace: deletable sessions + per-session gate
web: scope workspace canvas to the active session
web: honor session routes and preserve revision scopes

Launcher 카드가 이제 세션별 게이트를 보여준다 — 세 세션을 가진 프로젝트, 둘은 콘티에, 하나는 카피에 있으면, 세 상태 모두 렌더한다. 세션은 개별로 삭제 가능. workspace 캔버스, 수정 모드, 게이트 상태가 모두 활성 세션으로 스코프된다.

가장 큰 보이지 않는 커밋 — Lock the session after final storyboard approval. GATE 5가 승인되면 세션은 읽기 전용이 된다. 봉인된 산출물에 우발적 편집을 막고, 사용자가 더 반복하고 싶으면 의식적으로 새 세션을 시작하도록 강제한다.

인사이트

3일에 네 흐름 — 하지만 반복되는 모양은 같다 — “전부 아니면 전무"의 무언가 granular한 것으로의 붕괴.

드로어-또는-캔버스 이진이 출력 탭 연속체가 됐다 (모든 artifact를 한 번에 볼 수 있다)
세 게이트가 다섯이 됐다 (새 게이트가 가장 비싼 하류 비용을 가드한다 — 카피 + 시나리오 + 콘티가 선택된 방향으로 실행)
전체 단계 재실행이 부분 수정이 됐다 (정확히 원하는 것만 재생성)
프로젝트당 단일 세션이 프로젝트당 멀티 세션이 됐다 (프로젝트가 병렬 아이디어를 들고 갈 수 있다)

이 이동들 각각은 이진 버전보다 더 많은 코드 비용이 들었다 — 부분 수정 하나만 해도 의도 분류, 다섯 에이전트의 고정 항목 보존 로직, 스토어의 Set-of-IDs, 인덱스 splice 머지 함수가 필요했다 — 하지만 각각이 사용자가 조용히 견디고 있던 한 부류의 좌절을 제거했다. 153커밋 카운트는 영웅적으로 보인다 — 관통하는 줄은 더 겸손하다 — 시스템이 “전부 아니면 전무"라고 말할 때마다, “당신이 의미한 것만 정확히"로 교체.

다음 — 폴리시 주간 — 관측성 계측, 새로고침 아래 프로젝트별 상태 격리, 채팅에서 인라인 과거 게이트 되감기, 그리고 모든 탭에서 비주얼 처리를 마침내 통일한 수정요청 어포던스 패스.

Creative Agent Studio 개발일지 #3 — 134커밋 메가푸시: PR1 Launcher, PR2 Workspace, PR3 SSE, PR4 ApproveGate

Tue, 19 May 2026 00:00:00 +0900

개요

이전 글: #2 — 비트버킷 마이그레이션, production-readying, React 재작성 시작이 React 인프라가 부트스트랩된 상태로 끝났다 — 빈 Zustand 스토어, Vite + Tailwind + TS, 세 프리미티브, <T> i18n 컴포넌트, 그리고 PR1 계획. 24시간 뒤 134개 비머지 커밋이 네 PR을 순차적으로 떨어뜨려, 진짜 데이터베이스 영속화와 라이브 SSE 스트리밍을 갖춘 동작하는 React 프론트엔드를 만들어냈다.

작업은 네 PR과 그 아래 한 스택으로 떨어졌다.

PR1 — Launcher (projects CRUD, ProjectCard, NewProjectCard, CreateProjectModal, ProjectGrid)
PR2 — Workspace 셸 (StageStepper, ProjectSubbar, SessionsRail, Composer, ChatPanel, CanvasPanel 플레이스홀더)
PR3 — SSE + 채팅 흐름 (chat-stream 파서, dispatch-sse 매퍼, useChatStream 훅, AgentAvatar, 7가지 FeedItem 변형 전체, ChatFeed)
PR4 — ApproveSheet + Gates (3-모드 드로어, ApproveGateCopy / Scenario / ResearchInput 변형)
아래 — projects, artifacts, diff_history 테이블, CRUD 작업, 전체 REST API, 소프트 삭제 시맨틱

graph TD
 Prev["#2 — 부트스트랩 (752095f)"] --> DB["DB 레이어 <br/> 마이그레이션 + CRUD + REST"]
 DB --> PR1["PR1 — Launcher <br/> 프로젝트가 리로드를 살아남음"]
 PR1 --> PR2["PR2 — Workspace 셸 <br/> StageStepper + SessionsRail + Composer"]
 PR2 --> PR3["PR3 — SSE 채팅 흐름 <br/> chat-stream + dispatch-sse + 7 피드 변형"]
 PR3 --> PR4["PR4 — ApproveSheet <br/> 3-모드 드로어 + 3 게이트 변형"]
 PR4 --> End["#3 종료 (9a2f851) <br/> artifacts로부터 프로젝트 게이트 복원"]

관통하는 한 가지 주제 — 표면을 아래에서 위로 짓고, 어떤 커밋도 자기가 건너서는 안 되는 레이어를 건너지 않게 하라.

데이터베이스 레이어 — UI와 같은 날

세 마이그레이션과 작은 CRUD 모듈들이 projects, artifacts, diff_history를 일급으로 만들었다. 첫 커밋(feat(db): add projects, artifacts, diff_history tables via migrations)이 모양을 잡았다.

CREATE TABLE projects (
 id INTEGER PRIMARY KEY,
 title TEXT NOT NULL,
 brand TEXT,
 gate TEXT, -- 프로젝트가 마지막으로 멈춘 게이트
 created_at INTEGER NOT NULL,
 updated_at INTEGER NOT NULL,
 deleted_at INTEGER -- 소프트 삭제
);

CREATE TABLE artifacts (
 id INTEGER PRIMARY KEY,
 project_id INTEGER REFERENCES projects(id),
 stage TEXT NOT NULL,
 kind TEXT NOT NULL,
 payload TEXT NOT NULL, -- JSON
 evidence_uri TEXT, -- §8.2 — provenance
 created_at INTEGER NOT NULL
);

CREATE TABLE diff_history (
 id INTEGER PRIMARY KEY,
 project_id INTEGER REFERENCES projects(id),
 gate TEXT NOT NULL,
 before TEXT, -- JSON (첫 선택 시 null 가능)
 after TEXT NOT NULL, -- JSON
 created_at INTEGER NOT NULL
);

세 커밋 뒤 CRUD 모듈이 떨어졌다 — createProject, listProjects(active만, updated_at desc), getProject(감사용으로 deleted 행도 반환), renameProject(부분 패치 시맨틱), softDeleteProject(idempotent — deleted_at을 두 번 플립하지 않음).

idempotency 규칙은 fix(db): softDeleteProject preserves deleted_at on idempotent re-call에서 명시적으로 테스트됐다. 원래 구현은 UPDATE ... SET deleted_at = ?를 호출해서 두 번 호출되면 이전 삭제 타임스탬프를 덮어썼다. 수정 — UPDATE ... SET deleted_at = ? WHERE deleted_at IS NULL. 작은 버그, 큰 원칙 — 소프트 삭제는 묘비지 플래그가 아니다.

그 다음 REST API가 다섯 커밋으로 위에 올라왔다.

POST /api/projects → createProject
GET /api/projects → listProjects
GET /api/projects/:id → getProject (deleted면 404 — fix(api))
PATCH /api/projects/:id → renameProject
DELETE /api/projects/:id → softDeleteProject

별개의 수정이 GET과 PATCH에서 소프트 삭제된 프로젝트를 404로 처리하도록 했다(하위 CRUD 경로에서는 감사로 보이지만 REST 표면에서는 보이지 않음). diff_history 모듈은 appendDiff를 추가했고, after가 null일 때 리터럴 'null' 문자열을 저장하지 않도록 가드를 넣었다 — 누군가의 프로젝트 히스토리에서 UI에 "null" 문자열이 렌더되는 걸 발견할 때만 명백한 종류의 버그.

PR1 — Launcher

사용자가 보는 첫 화면. 프로젝트 목록, 새로 만들기 어포던스, 검색.

페이지 아키텍처를 셋업한 구조적 커밋 몇 개.

feat(web): real projects slice (CRUD) — sort-by-updated를 갖춘 useProjects 훅
feat(web): add userName + setUserName to ui slice — 이중언어 인사말에 보이는 영속 사용자 이름
feat(web): add AppTopbar with logo + lang toggle — 사이트 크롬
feat(web): add LauncherTopbar + LauncherHero with bilingual greeting
feat(web): add SessionsRail hidden-mode stub (PR2 fills workspace mode)

그 다음 실제 목록과 생성 흐름.

feat(web): add ProjectsSearch with bilingual placeholder and count kicker
feat(web): add ProjectCard with progress bar and brand/status
feat(web): add NewProjectCard with dashed border and accent hover
feat(web): add CreateProjectModal with title + optional brand + validation
feat(web): wire ProjectGrid — search filter, modal, navigation

카드 진행 막대는 프로젝트가 진행한 같은 gate 필드를 읽는다 — 그래서 launcher 카드는 각 프로젝트가 어디까지 갔는지의 라이브 스냅샷이다. 클릭 → /projects/:projectId로 이동. 끝.

이 PR이 깔끔한 이유는 엄격한 레이어링이다 — 모든 인터랙티브 조각은 스토어에서 읽고, 스토어는 REST API에서 읽고, REST API는 CRUD 모듈에서 읽고, CRUD 모듈은 SQLite에서 읽는다. 지름길 없음. 컴포넌트 자체는 슬라이스만 안다.

PR2 — Workspace 셸

사용자가 프로젝트 카드를 클릭한 뒤 도착하는 화면. 세 컬럼 — 왼쪽 sessions rail, 가운데 채팅, 오른쪽 canvas 플레이스홀더. 실제 단계별 워크플로는 이 셸 안에 산다.

11개 구조적 커밋.

feat(web): add stage-labels lib (gate ↔ stage + ko/en short/long labels) — 단계의 이중언어 라벨로의 정전 매핑, stepper와 canvas 양쪽에서 사용
feat(web): add Session type + real workspace slice (sessions + composer) + store-init test
feat(web): add sessionsPanelOpen + toggleSessionsPanel to ui slice — 레일이 접힌다
feat(web): add StageStepper (6 dots + bilingual long-form label) — 단계 진행 표시기
feat(web): add ProjectSubbar wrapping StageStepper
feat(web): fill SessionsRail workspace mode (project header + sessions list + new + back)
feat(web): add Composer (pill input + send button, console-log submit only) — 채팅 입력, 아직 제출 와이어링 없음
feat(web): add ChatPanel skeleton (header + welcome bubble + Composer)
feat(web): add CanvasPanel placeholder (PR5 fills variants) — 명시적 연기
feat(web): assemble WorkspacePage (.shell grid) + swap workspace route

플레이스홀더 패턴을 짚을 만하다. CanvasPanel이 커밋 메시지에 명시적으로 “PR5 fills variants"라고 적힌 플레이스홀더로 추가됐다. 그것은 레이아웃에 구멍을 남기지 않고 큰 작업을 연기했다 — 레이아웃은 끝났고, 슬롯은 와이어드됐고, 실제 콘텐츠는 사용자에게 아직 출시되지 않을 스텁이었다. PR5가 깔끔하게 떨어질 수 있었던 이유는 PR2가 그 주소를 예약해놨기 때문이다.

PR3 — SSE 배관, 채팅 흐름, 그리고 7가지 피드 변형

이 PR이 정적 셸을 라이브 앱으로 바꿨다. 세 레이어에 걸친 20+ 커밋 — 스토어, 배관, 컴포넌트.

스토어 레이어

// web/src/store/slices/feed.ts (의역)
type FeedItem =
 | { kind: "user", text: string }
 | { kind: "assistant", text: string }
 | { kind: "streaming", text: string }
 | { kind: "agent_progress", agent: string, status: string }
 | { kind: "stage_complete", stage: string }
 | { kind: "system_error", message: string }
 | { kind: "task_update_note", text: string };

type FeedSlice = {
 feed: FeedItem[];
 appendChunk: (text: string) => void; // 스트리밍
 splitParagraphs: () => void; // 스트리밍 → 최종
 pushAgentProgress: (agent, status) => void;
 pushStageComplete: (stage) => void;
 // ...
};

일곱 가지 피드 아이템 타입에 대한 식별된 유니온, 슬라이스의 kind별 리듀서. 그리고 게이트/단계/컨텍스트/lastSubmit 상태를 위한 pipeline 슬라이스, tasks + activeSubAgents(agent_activity 봉투의 싱크)를 얻은 workspace 슬라이스.

배관 레이어

세 순수 모듈과 한 훅.

feat(web): add chat-stream lib (POST /api/chat + SSE parse + Zod-validated envelopes) — 와이어 레벨 파서
feat(web): add dispatch-sse mapper (SSEEnvelope → store actions) — 순수 매퍼, DOM 없음
feat(web): add useChatStream hook (submit/cancel + AbortController lifecycle) — 라이프사이클 소유자

// web/src/hooks/use-chat-stream.ts (의역)
export function useChatStream() {
 const controllerRef = useRef<AbortController | null>(null);

 const submit = useCallback(async (text: string, context: ChatContext) => {
 controllerRef.current?.abort();
 const controller = new AbortController();
 controllerRef.current = controller;

 for await (const envelope of streamChat({ text, context, signal: controller.signal })) {
 dispatchSse(envelope); // 스토어 액션
 }
 }, []);

 const cancel = useCallback(() => controllerRef.current?.abort(), []);

 return { submit, cancel };
}

분할은 — chat-stream은 파싱, dispatch-sse는 매핑, useChatStream은 라이프사이클 소유. 셋, 모듈 셋 — 어떤 모듈도 하나 이상의 일을 하지 않았다. 각각의 테스트(tighten test fetch types 등)가 같은 날 출시됐다.

컴포넌트 레이어

봉투가 스토어에 떨어질 수 있게 되자 컴포넌트가 렌더했다.

feat(web): add AgentAvatar + fix shared/events runtime exports
feat(web): add User/Assistant/Streaming bubble components
feat(web): add AgentProgress + StageComplete + SystemError + TaskUpdateNote
feat(web): add FeedItem discriminated dispatcher (7 variants)
feat(web): add AgentStrip ('Running now' active sub-agents)
feat(web): add ChatFeed (auto-scroll + FeedItem map + welcome empty state)
feat(web): wire ChatPanel to AgentStrip + ChatFeed (replaces static welcome bubble)

FeedItem 디스패처는 식별된 유니온 패턴이 보답하는 모습이다 — 모든 변형을 자기 컴포넌트로 매핑하는 한 곳, TS가 강제하는 망라성.

AgentStrip은 interaction-model.md의 결정 2 — “한 줄 상태, 전체 대시보드 없음” — 의 실체화였다. 채팅 상단을 가로지르는 가로 스트립으로 현재 실행 중인 서브 에이전트만 표시한다. 사이드 패널 아니고, 대시보드 아니고, 그냥 작업이 일어날 때 나타났다 끝나면 사라지는 인라인 스트립.

PR4 — ApproveSheet와 세 게이트 변형

채팅 전용 흐름을 채팅 + 승인 흐름으로 바꾼 조각.

ApproveSheet는 세 모드를 갖춘 하단 드로어다 — collapsed(게이트 프롬프트만), half-open(게이트 + 요약), full(게이트 + 전부). 포인터 이벤트로 드래그 리사이즈. Esc로 접힘. 세 게이트 변형이 같은 셸에 떨어진다 — 각 게이트 단계는 자기 변형 컴포넌트를 받는다.

12개의 구조적 커밋.

feat(web): add ApproveGate payload types
feat(web): add approveSheetMode + setApproveSheetMode to ui slice
feat(web): pipeline slice gains copy/scenario history + idx setters — 과거 드래프트 사이를 전환하는 백포인터 상태
feat(web): projects slice gains bumpProjectGate + assert PR4 fields in store-init
feat(web): dispatch-sse pushes copy/scenario history + bumps project gate on stage_complete — 게이트 진행을 위한 SSE → 스토어 glue

그 다음 드로어 메커닉.

feat(web): add useApproveSheetDrag hook + PointerEvent jsdom polyfill — 드래그 핸들 훅. PointerEvent는 jsdom에 기본으로 없으니 폴리필이 함께 출시.
feat(web): add ApproveSheet base (3-mode drawer + collapse toggle + drag handle)

그리고 세 게이트 변형.

feat(web): add ApproveGateCopy (grid + select + approve / request-edit) — 사용자가 N개 카피 드래프트 중 하나를 선택
feat(web): add ApproveGateScenario (acts list + approve / request-edit) — 사용자가 다막 시나리오를 승인하거나 수정
feat(web): add ApproveGateResearchInput (question + answer + send) — 다른 모양 — 에이전트가 사용자에게 리서치 질문을 하고 타이핑한 답을 기다림

ApproveGate 디스패처(변형 선택 + 제출 와이어링)로 함께 묶이고, ChatPanel 안에 마운트되고, WorkspacePage에서 submit이 forward된다. 사용자 흐름은 이제 — 채팅에서 묻고 → 에이전트가 돌고 → artifact와 함께 드로어가 올라오고 → 승인 또는 수정. interaction-model.md의 결정 3(단계 사이 게이트 기반 자동 실행)이 살아 있다.

하루 끝 상태

오늘의 마지막 커밋(9a2f851 feat(web): restore project gate from artifacts on workspace mount (Slice K))이 중요한 루프를 닫았다 — 사용자가 workspace 페이지를 리로드하면, 프로젝트의 게이트 상태가 영속된 artifacts에서 복원된다. 오늘의 작업이 새로고침을 살아남는다.

아래 스택과 PR1-PR4 사이에서, React 프론트엔드는 하루 끝에 다음을 갖췄다.

동작하는 launcher (진짜 프로젝트, 리로드를 가로질러 영속)
3컬럼 레이아웃의 workspace 셸
SSE 스트리밍 라이브 채팅
모든 7가지 피드 변형이 렌더링
3가지 게이트 변형을 가진 ApproveSheet 드로어
리로드를 살아남는 프로젝트 상태

목업은 아직 삭제되지 않았지만, 목업이 시연하려던 모든 것이 이제 React에서 돈다.

인사이트

이 날이 작동한 이유는 모든 커밋이 자기 레이어를 존중했기 때문이다. 스토어 슬라이스는 PR4가 필요로 할 모양으로 PR2에서 선언됐다. PR3의 SSE 배관은 세 모듈 — 파서, 매퍼, 라이프사이클 — 로 각각 독립적으로 테스트될 수 있었다. PR4의 ApproveGate 변형들은 PR3의 FeedItem 디스패처와 매칭되는 디스패처 패턴에 꽂혔다.

일어나지 않은 일 — 그리고 134커밋이 카오스가 아니었던 이유 — 는 레이어 교차 커밋이다. 어떤 커밋도 <button>과 SQL 컬럼을 같이 추가하지 않았다. 어떤 커밋도 CRUD 모듈에서 슬라이스로 손을 뻗지 않았다. 커밋이 레이어를 가로질러야 할 때는 한 레이어 아래의 기반 커밋이 선행하거나 한 레이어 위의 채택자 커밋이 뒤따랐다. 이 규율이 패치워크 스프린트가 됐을 것을 깔끔한 추가 스택으로 바꿨다.

새겨둘 멘탈 모델 — 빠르다는 건 지름길이 아니다. 이 날이 네 PR을 출시한 이유는 각 PR이 존재하게 한 규율 때문이지, 그 규율을 무시했기 때문이 아니다.

다음 — canvas 패널, 5게이트 워크플로, key-concept planner, 그리고 사용자가 전체 단계가 아닌 단일 카드만 외과적으로 재실행할 수 있게 하는 revise-mode 다중 선택 패턴.

Creative Agent Studio 개발일지 #2 — 비트버킷 마이그레이션, production-readying, 그리고 React 재작성의 시작

Mon, 18 May 2026 00:00:00 +0900

개요

이전 글: #1 — 4월 목업 시절과 Creative Warmth 테마를 6주 전에 올렸다. 긴 잠복기를 지나, 2026-05-18이 하루에 27커밋으로 폭발했다 — 그리고 깔끔하게 세 스택으로 떨어졌다. 첫째, 레포 이전을 표시하는 비트버킷 마이그레이션 스냅샷. 둘째, Node 런타임의 production-readying 패스 — 구조화 JSON 로거, AbortSignal 기반 graceful 워커 셧다운, /api/health + /api/metrics, 싱글 EC2 배포 자산(systemd, nginx, litestream), 그리고 모놀리식 큐를 쪼개는 세 리팩토링. 셋째, 72시간 안에 목업을 완전히 대체할 React+Vite+TypeScript 부트스트랩 — 4월에서 그대로 가져온 Creative Warmth 토큰의 Tailwind, 5개 빈 슬라이스의 Zustand 스토어, <T> i18n 컴포넌트, 그리고 첫 디자인 프리미티브.

graph TD
 Prev["#1 — 4월 목업 <br/> (21f0ebc)"] --> Stack1["스택 1 <br/> 비트버킷 마이그레이션 스냅샷"]
 Prev --> Stack2["스택 2 <br/> 런타임 강화 <br/> 로거 / 셧다운 / health / 배포"]
 Prev --> Stack3["스택 3 <br/> web/ 부트스트랩 <br/> React + Vite + Tailwind + Zustand"]
 Stack1 --> End["#2 종료 <br/> (752095f)"]
 Stack2 --> End
 Stack3 --> End

이 날의 관통 주제 — 더 이상 프로토타입처럼 다루지 마라.

스택 1 — 비트버킷 마이그레이션 스냅샷

오늘의 첫 커밋(9d414f2 chore: snapshot project state for bitbucket migration)은 코드 변경이 아니라 마커였다. 레포는 엔지니어링 외의 이유로 옮겨가고, 스냅샷 커밋은 컷오버를 가독성 있게 만든다 — 이게 옛 집에서 가져온 상태고, 이후 모든 것은 새 집이다.

미래의 “뭐가 바뀐 거지?” 조사가 “이동에서 살아남은 코드” vs “이동 이후 추가된 코드"를 찾을 때 이 커밋에서 멈출 수 있다는 점에서 기록할 가치가 있다.

스택 2 — 런타임 production-readying

구조화 JSON 로거 + 채택

커밋 ead6854와 d0b9ea4가 구조화 JSON 로거를 도입하고 채팅 라우트 + 워커 라이프사이클 경로에 채택했다. 기존 패턴은 console.log 문자열이었는데, 로그 애그리게이터에 실제 배포되면 살아남지 못한다.

// runtime/observability/logger.js (의역)
function createLogger({ component }) {
 return {
 info: (msg, ctx) => emit({ level: "info", component, msg, ...ctx, ts: Date.now() }),
 warn: (msg, ctx) => emit({ level: "warn", component, msg, ...ctx, ts: Date.now() }),
 error: (msg, ctx) => emit({ level: "error", component, msg, ...ctx, ts: Date.now() }),
 };
}

계약은 일부러 최소화 — 심각도 하나, 메시지 문자열 하나, 컨텍스트 객체 하나. 채팅 라우트가 첫 채택자였던 이유 — SSE 프레임이 발신되는 곳이고, 거기서 비구조화된 console.log는 stdout에서 프레임 헤더와 인터리브되어 로그를 망친다.

AbortSignal 기반 graceful 워커 셧다운

커밋 d9bf640. 기존 워커 루프는 무한 while (true) 클레임 앤 런이었다. 워커 프로세스에 kill -TERM을 보내면 잡 중간에 죽고, SQLite jobs 행은 running 상태에 stale worker_lock을 들고 남았다 — 결국 stale-timeout 메커니즘으로 회수되지만 몇 분의 지연이 있었다.

AbortSignal을 루프에 꿰어 넣은 수정:

// runtime/workers/worker-loop.js
export async function startWorkerLoop({ role, signal }) {
 while (!signal.aborted) {
 const job = await claimNextJob(db, role);
 if (!job) {
 await sleep(POLL_INTERVAL_MS, { signal });
 continue;
 }
 try {
 await runJob(job, { signal });
 } catch (err) {
 if (signal.aborted) {
 await releaseJobForReclaim(db, job.id); // 명시적 잠금 해제
 return;
 }
 throw err;
 }
 }
}

SIGTERM 핸들러가 controller.abort()를 호출하고 워커가 안정될 때까지 기다리는 server/index.js 변경과 결합되면, 5분 회수 윈도우가 즉시 깔끔한 셧다운으로 바뀐다 — 롤링 배포에 중요하다.

일일 유지보수 + /api/health + /api/metrics

세 커밋이 운영 격차를 닫았다.

3ac2dfa — 주기적 이벤트 로그 보존. SSE 프레임이 영속화되면서 events 테이블이 단조 증가한다. 보존 없이는 장기 실행 배포가 디스크를 채운다. cron 같은 잡이 매일 돌면서 N일보다 오래된 이벤트를 삭제한다.
89c7b05 — /api/health(부트 프로브)와 /api/metrics(Prometheus 스타일 카운터). 이제 로드 밸런서가 자기 일을 할 수 있고, Grafana 대시보드가 마침내 존재할 수 있다.
d0b9ea4 — 세 가지(셧다운, 유지보수, 로거)를 server/index.js 부트에 모두 꿰어 넣음.

Grafana 셋업 자체는 자기 문서를 받았다(4236122 docs: add Grafana Cloud setup guide for EC2 deployment) — 메트릭 셋이 한 번 배포하고 잊어버릴 만큼 작았기 때문이다. 런타임의 텔레메트리 관심사는 큐 깊이, 잡 지속시간, 게이트 승인까지의 시간뿐이었다.

싱글 EC2 배포 자산

커밋 9ac967f가 싱글 EC2 배포 스택 전체를 추가했다 — Node 서버 + 워커용 systemd 유닛 파일, TLS를 종료하고 :7878로 프록시하는 nginx 설정, 그리고 data/runtime.sqlite를 S3로 지속적으로 복제하는 Litestream 설정. Litestream이 핵심이다 — 애플리케이션 코드를 바꾸지 않고 지속적 시점 백업을 제공해서 소규모 팀 앱에 SQLite를 production 선택지로 옹호할 수 있게 한다.

런타임 리팩토링

다가올 PR0-PR4 폭주에 코드베이스를 준비시킨 세 동반 리팩토링.

1cf3bce refactor: split runtime/queue/jobs.js into runs/jobs/events modules — jobs.js가 실행 라이프사이클, 잡 클레임, 이벤트 영속화를 뒤섞은 god-module이 됐었다. 단일 책임 세 모듈로 쪼갬.
4ee661e refactor: extract stage state machine + route events through persistEvent — “실행이 어느 단계에 있고, 거기서 어디로 전이할 수 있는가” 로직이 워커 곳곳에 흩뿌려져 있었다. 단일 상태 머신 모듈로 추출. 모든 이벤트 쓰기는 persistEvent를 거치니 빠진 이벤트가 silent 버그가 될 수 없다.
c7291af refactor: consolidate Google AI SDK on @google/genai — 코드베이스가 두 Google SDK 패키지를 동시에 사용하고 있었다. @google/genai로 통합.

런타임 SQLite는 data/로 이전됐다(2e3ac8a) — .gitignore-by-intent 파일이 WAL/SHM 저널 옆 전용 서브디렉토리에 살 수 있도록.

스택 3 — React 재작성 부트스트랩

목업의 날들은 카운트다운 중이었다. 디자인 스펙(253f83d docs: add design spec for mockup → web/ (React + Vite + TS) rebuild)과 구현 계획(c81b248 docs: add PR0 implementation plan for web/ infra bootstrap)이 타깃을 선언했다. 20개 커밋이 그것을 실체화했다.

패키지 + 툴링

web/package.json React 18 + Vite + TypeScript
web/tsconfig.{json,app.json,node.json} Vite 표준 3-파일 분할
web/vite.config.ts /api 프록시 → :7878 (Express 포트와 매칭)
web/tailwind.config.ts Creative Warmth 토큰
web/vitest.config.ts jsdom + RTL 셋업

Tailwind 설정(17aecd9)은 짚을 가치가 있다 — 4월 목업 CSS의 모든 Creative Warmth 토큰이 손으로 Tailwind 확장으로 번역됐다.

// web/tailwind.config.ts (의역)
export default {
 theme: {
 extend: {
 colors: {
 'warm-white': '#FAF7F2', // 본문 배경
 'warm-paper': '#F5F1EA', // 떠올린 표면
 'text-primary': '#2A2622', // 순흑 아님
 },
 fontFamily: {
 display: ['"DM Serif Display"', 'serif'],
 hand: ['Caveat', 'cursive'],
 },
 },
 },
};

디자인 토큰은 하나도 재유도되지 않았다 — 그대로 끌어올렸다. 목업은 일회용 코드였지만, 디자인 시스템은 하중을 지탱하고 있었다.

스토어 스캐폴드

커밋 0b469b8 feat(web): scaffold Zustand store with 5 empty slices는 어떤 기능 코드보다 먼저 상태 아키텍처를 셋업했다.

// web/src/store/index.ts
type Store = UiSlice & ProjectsSlice & WorkspaceSlice & FeedSlice & PipelineSlice;

export const useStore = create<Store>()((set, get, api) => ({
 ...createUiSlice(set, get, api),
 ...createProjectsSlice(set, get, api),
 ...createWorkspaceSlice(set, get, api),
 ...createFeedSlice(set, get, api),
 ...createPipelineSlice(set, get, api),
}));

5개 슬라이스 — ui, projects, workspace, feed, pipeline — 가 1일차에 빈 상태로 선언됐고, 모양을 잠그는 테스트(9543922 test(web): assert store init exposes all five slices)가 따라붙었다. 그래야 후속 커밋들이 슬라이스를 잊지 않고 필드를 추가할 수 있다. 그 결정이 다음 3일 동안 100+ 커밋이 그 슬라이스들에 병렬로 필드를 추가할 때 보상을 줬다.

`<T>` i18n 컴포넌트

커밋 24ff23e feat(web): add <T> i18n component with KO/EN toggle + tests. 앱의 주 언어는 한국어지만, 영어 지원을 시작부터 띄운다는 건 어떤 컴포넌트가 쓰이기 전에 이중언어 prop 패턴이 확립됐다는 뜻이다.

<T ko="키 컨셉을 선택하세요" en="Select a key concept" />

작은 선택 — 두 props vs i18n 키 조회 — 이지만 소스 오브 트루스를 소비자와 같이 두는 효과가 있다. 단일 개발자 크리에이티브 도구에서는 어떤 프레임워크 레벨 i18n 추상화보다 나았다.

디자인 프리미티브

뒤에 오는 모든 것을 정착시킬 세 프리미티브가 1일차에 출시됐다.

bf3ebaa feat(web): add cn() helper + minimal Button primitive — 조건부 classname을 위한 cn() 유틸 + 이미 Creative Warmth를 입은 Button.
a0cc67e feat(web): add Radix-backed Dialog primitive with warm scrim — 접근성을 위한 Radix, 디자인 언어에 맞춘 따뜻한 scrim(rgba(42, 38, 34, 0.4) — text-primary의 반투명, 순흑 아님).
c2ee60f feat(web): add Input primitive with Creative Warmth styling — soft-edged warm-paper 배경의 입력 필드.

공유 이벤트 스키마

커밋 0c37093 feat(shared): add SSE event Zod schemas + type re-exports — SSE 이벤트 타입을 shared/events/index.mjs로 옮겨서 백엔드(Express)와 프론트엔드(React)가 같은 Zod 스키마를 import할 수 있게 했다. 양쪽 모두 타입 안전 SSE, 파서 레이어에서 검증.

PR1 전주곡

하루는 PR1 계획 문서(558e7ec docs: add PR1 (Launcher) implementation plan)와 첫 launcher 빌딩 블록 — Project 타입, 필터/정렬/진행 헬퍼(752095f) — 로 끝났다. Launcher 페이지 자체 — 사용자가 처음 보는 화면 — 의 구현은 내일이었다.

커밋 로그 (선별, 총 27개)

스택	커밋
비트버킷 마이그레이션	snapshot project state
런타임 강화	structured JSON logger; AbortSignal 셧다운; event-log retention; /api/health + /api/metrics; boot에 셋 다 꿰기
배포 스택	single-EC2 systemd/nginx/litestream; Node ≥ 22.5 engines 필드; SQLite를 data/로; @google/genai 통합
리팩토링	queue/jobs를 runs/jobs/events로 분할; stage state machine 추출; agents snake_case 리네임; 4월 plan 아카이브
문서	Grafana Cloud 셋업; web/ 재구축 디자인 스펙; PR0 구현 계획; PR1 launcher 계획
web/ 부트스트랩	package.json + Vite + tsconfig; Creative Warmth 토큰의 Tailwind; Vitest + jsdom + RTL; Zustand 5-슬라이스 스토어; T i18n 컴포넌트; cn() + Button + Dialog + Input 프리미티브; shared/의 SSE Zod 스키마; React Router 셸

인사이트

하루 27커밋이 커밋 메시지에서는 무관해 보일 세 가지를 했지만 결국 한 결정이었다 — production 타깃에 commit하라. 런타임은 배포에서 살아남는 데 필요한 관측성과 셧다운 시맨틱을 받았다. 배포 스택 자체가 위키 페이지가 아닌 코드로 그려졌다. 그리고 React 재작성은 production 버전이 필요한 같은 디자인 토큰, 타입 검증 SSE, 아키텍처 솔기로 0일차에 시작됐다.

가르치는 건 이 날 일어나지 않은 일들이다. 기능 코드 없음. 새 에이전트 없음. 프롬프트 튜닝 없음. 원칙은 — 바닥을 먼저 강화하고, 강화된 바닥 위에 기능을 다음에 짓는다. 다음 날 134커밋 메가푸시는 이게 없었으면 안전하지 않았을 것이다 — god-module 큐, console.log 코드베이스, 깔끔하게 셧다운하지 않는 워커 위에서 하루에 PR1 → PR4를 돌리는 건 진짜 버그를 운영 노이즈 아래에 묻었을 것이다.

다음 — 하루 134커밋. PR1 Launcher, PR2 Workspace 셸, PR3 SSE + 채팅 흐름, PR4 ApproveGate, 그리고 이 모든 것 아래의 데이터베이스 레이어.

Creative Agent Studio 개발일지 #1 — 4월 목업 시절, 그리고 Creative Warmth 테마를 입은 이유

Tue, 07 Apr 2026 00:00:00 +0900

개요

Creative Agent Studio의 첫 개발일지다 — 한국어 기반 광고 크리에이티브 멀티 에이전트 시스템. 사용자의 단일 메시지가 채팅 우선 파이프라인에 진입해 네 가지 프레젠테이션 단계 — 리서치 → 카피 → 시나리오 → 콘티 — 를 거치며, 단계 사이에 명시적 사람 승인 게이트를 둔다.

4월은 목업의 시대였다. 이틀 동안 12개의 커밋이 캔버스의 정적 HTML/JS 프로토타입, 런타임 흐름 스펙, 결국 React 재작성에서도 살아남는 “Creative Warmth” 디자인 테마, 그리고 Vercel에 올릴 배포 모양을 만들어냈다. 나중에 버려지는 코드는 핵심이 아니었다 — 핵심은 interaction-model.md에 적어둔 결정들과 목업에 박힌 디자인 토큰이었다.

graph TD
 Idea["사용자 브리프 (채팅)"] --> Research["리서치 단계 <br/> 리서치 에이전트"]
 Research --> Gate1["GATE 1 <br/> 키 컨셉 선택"]
 Gate1 --> Copy["카피 단계 <br/> 4개 드래프트 워커"]
 Copy --> Gate2["GATE 2 <br/> 카피 승인"]
 Gate2 --> Scenario["시나리오 단계 <br/> 3 스페셜리스트"]
 Scenario --> Gate3["GATE 3-4 <br/> 시나리오 승인"]
 Gate3 --> Storyboard["콘티 단계 <br/> 이미지 생성"]
 Storyboard --> Gate5["GATE 5 <br/> 최종 승인"]

12개 커밋, 한 가지 관통하는 주제 — 구현이 녹슬기 전에 원칙을 못 박는다.

목업보다 오래 살아남은 세 가지 결정

4월에 추가된 가장 중요한 파일은 코드가 아니라 interaction-model.md였다 — 세 가지 제품 결정을 단일 결정문서로 결정화한 문서:

결정 1. 인터랙션 모델 — 채팅 우선. 사용자의 주 입력 수단은 자유형 채팅이다. 단계를 직접 클릭하거나 버튼으로 다음으로 넘어가는 방식은 사용하지 않는다. 오케스트레이터가 사용자의 발화를 해석해 적절한 에이전트를 호출한다.

결정 2. 에이전트 투명성 — 한 줄 상태 표시. 에이전트 실행 중에는 피드에 한 줄짜리 상태 메시지만 표시한다. 전체 에이전트 대시보드나 실시간 로그는 노출하지 않는다.

결정 3. 게이트 기반 자동 실행. 각 단계가 완료되면 파이프라인은 멈추고, 다음 단계를 자동으로 실행하기 전에 명시적 사람 승인을 기다린다.

뒤이은 모든 UI 커밋은 — 4월 내내, 그리고 5월 재작성을 가로질러 — 이 세 규칙에 비춰 검증됐다. 목업의 첫 커밋(b67eb98 Add Diffs creative agent studio mockup)부터 이미 DOM 구조로 인코딩돼 있었다 — “다음 단계” 버튼 없음, 에이전트는 대시보드가 아니라 글머리 기호 목록으로, 컴포저가 유일한 진입점.

“Creative Warmth” — 디자인 테마

세 번째 커밋(72e0fdc)이 모든 걸 견뎌낸 비주얼 베이스라인이었다 — “Redesign: Apply Creative Warmth theme (warm white, DM Serif Display, Caveat).”

토큰 셋, 이유 셋:

토큰	값	이유
배경	Warm white (#FAF7F2)	순백은 소프트웨어처럼 읽힌다. 따뜻한 톤은 작업실처럼 읽힌다.
본문 서체	DM Serif Display	크리에이티브 도구는 생산성 코드가 아니라 문학적인 느낌이어야 한다.
손글씨 라벨	Caveat	스페셜리스트 에이전트 이름에 손글씨 배지를 — 밀도 높은 작업면에 인간미를 한 줄 입히는 작은 장치.

규칙은 부정형이었다 — 순흑도, 순백도, 어디에도 쓰지 않는다. 후속 커밋(640c755)이 로고 가시성을 고쳐야 했는데 — 원본 SVG가 어두운 색이라 따뜻한 배경 위에서 보이지 않았다 — 수정 방법은 에셋을 재출력하는 대신 filter: brightness(0) CSS 핵으로 반전시키는 것이었다. 실용적이긴 했지만, 기저 제약은 그대로였다 — 디자인 시스템이 시스템과 싸우는 에셋을 위해 굽혀지지는 않는다.

이 토큰들은 6주 뒤 React 측 첫 feat(web) 커밋에서 web/tailwind.config.ts로 그대로 이주한다 — 디자인 결정이 옳은 하중 지지 레이어였다는 증거.

목업을 정직하게 만든 세 가지 UI 정리

연속된 세 커밋(3c225c9, 1be5253, d37b4c9)이 세 결정을 위반하던 것들을 공격했다.

- <p class="eyebrow">Project Management</p>
- <ul class="agents">
- <li><span class="dot dot-1"></span>Agent 1</li>
- <li><span class="dot dot-2"></span>Agent 2</li>
- </ul>
+ <ul class="agents">
+ <li>리서치 에이전트</li>
+ <li>Copy Draft Workers</li>
+ </ul>

3c225c9 — 전체를 PM 도구로 프레임하던 “Project Management” eyebrow 제거. 색상 코드 칩 대신 글머리 기호로 에이전트 이름을 표시 — 칩은 대시보드를 암시했기 때문.

1be5253 — 상태 레일에서 “Background Agents” 섹션을 완전히 제거. 결정 2(한 줄 상태, 전체 대시보드 없음)를 위반했다.

d37b4c9 — 컴포저 개편. 모델 셀렉터를 입력 바 안으로 옮기고, 파일 첨부 아이콘을 추가하고, 모델 목록을 업데이트했다. 왜 중요한가 — 컴포저는 결정 1의 전체 표면적이다. “더 도전적으로” 또는 “이 두 개 합쳐줘"를 타이핑할 적절한 장소처럼 느껴지지 않는다면, 채팅 우선 원칙은 사고로 실패한다.

이것들은 기능이 아니었다 — 스펙을 강제하는 삭제였다.

런타임 흐름 다듬기 — 목업 아래 뼈대

2026-04-07의 세 문서와 한 feat 커밋이 런타임 토대를 깔았다.

ecac2e5 docs: add production poc state and routing spec — 런타임이 네 단계에 걸쳐 어떤 상태를 들고 다닐지 정의.
7e26c12 docs: add runtime state cleanup spec — 실행 간 상태가 어떻게 정리될지 정의 (나중에 React 앱이 세션별 상태를 격리해야 할 때 의미를 가짐).
97df876 feat: refine workspace runtime flow — 실제 흐름 코드를 다듬음.
21f0ebc chore: add deployment and design reference files — 배포 모양과 디자인 참조 폴더를 커밋.

“배포 참조"는 목업 디렉토리를 가리키는 Vercel buildCommand였다. 그 배포 타깃은 재작성에서도 살아남았다 — 5월에 React 프론트엔드가 출시됐을 때 vercel.json의 유일한 변경은 outputDirectory: "web/dist"였다.

커밋 로그

날짜	메시지
2026-04-06	Add Diffs creative agent studio mockup
2026-04-06	Fix logo path for Vercel deployment
2026-04-06	Redesign: Apply Creative Warmth theme (warm white, DM Serif Display, Caveat)
2026-04-06	Fix logo visibility: apply brightness(0) filter for dark logo on light bg
2026-04-06	UI: Remove ‘Project Management’ eyebrow, show agent names as bullets, add LLM dropdown
2026-04-06	Remove Background Agents section from status rail
2026-04-06	Composer: move model selector into input bar, add file attach icon, update models
2026-04-07	docs: add production poc state and routing spec
2026-04-07	docs: add runtime state cleanup spec
2026-04-07	feat: refine workspace runtime flow
2026-04-07	chore: ignore local workspace artifacts
2026-04-07	chore: add deployment and design reference files

인사이트

4월은 한 조각의 소프트웨어(정적 목업)와 세 조각의 글(interaction-model.md, 라우팅 스펙, 런타임 클린업 스펙)을 만들었다. 목업은 6주 뒤 삭제된다 — chore: remove legacy mockup/ vanilla-JS SPA 커밋이 메가푸시에 떨어진다 — 하지만 글의 모든 단락은 여전히 하중을 지탱한다.

새겨둘 만한 교훈 — 제품 원칙은 구현보다 오래 산다. “채팅 우선, 한 줄 상태, 게이트 기반 자동 실행"을 — 기능으로도, UI 요구사항으로도 아니라 — 결정 헤딩과 이유 헤딩이 붙은 결정으로 적어두니, 뒤이은 모든 UI 커밋이 통과해야 할 재판소가 생겼다. 5월에 React 재작성이 시작됐을 때, 그 세 결정은 새 web/ 트리의 원칙으로 그대로 복사됐다. 목업은 일회용이었다 — 원칙은 아니었다.

다음 — 비트버킷 마이그레이션, 런타임 production-readying, 그리고 한 주말 동안 목업 전체를 대체하게 될 React+Vite+TypeScript 재작성의 시작.

Creative Agent Studio on ICE-ICE-BEAR-BLOG

Creative Agent Studio 개발일지 #5 — 폴리시 주간: LLM 토큰 텔레메트리, 멀티세션 격리, 인라인 되감기, 그리고 수정요청 어포던스

개요

갈래 1 — LLM 호출 관측성

갈래 2 — 새로고침 아래 프로젝트별 상태 격리

갈래 3 — 채팅에서 인라인 과거-게이트 되감기

갈래 4 — 수정요청 어포던스 패스

되돌리기 다이얼로그 카피 완화 + 폐기 리스트에서 최종 게이트 숨기기

되돌리기 다이얼로그의 게이트 타이틀

수정요청 진입 시 ApproveBar 게이트 미리 선택

다섯 탭에 걸친 마킹 카드 비주얼 통일

모든 게이트 마커를 한 번씩만 표시하고 라이브 게이트 상태 반영

커밋 로그 (총 23개)

인사이트

Creative Agent Studio 개발일지 #4 — 5개의 게이트, 4개의 캔버스, 그리고 수정 모드 시스템

개요

흐름 1 — PR5: 4단계 변형의 캔버스 패널

리사이즈 + 접기

PR6 — 폴리시 + 백엔드 스왑 + 목업 삭제

흐름 2 — 워크플로가 5게이트로 통합됨

GATE 1이 존재해야 했던 이유

프론트엔드 — ApproveGateKeyConcept

GATE 3(컨셉 승인)와 GATE 5(최종 승인)

gate_state — 12상태 라이브 전이

GATE 1의 기획 보고서

HTML 템플릿 세트

흐름 3 — ApproveBar가 드로어를 교체하고, 출력 탭이 인라인 렌더를 교체

출력 탭 — 캔버스가 “현재 단계 표시"에서 “모든 단계의 탭 히스토리"로 피벗

Planner-Generator-Evaluator 루프

흐름 4 — 수정 모드 시스템

의도 분류

수정 모드 UI

Revision-merge — 인덱스 splice

각 에이전트가 부분 재생성을 배웠다

라우팅 레이어

흐름 5 — 세션 격리 (프로젝트당 멀티 시도)

인사이트

Creative Agent Studio 개발일지 #3 — 134커밋 메가푸시: PR1 Launcher, PR2 Workspace, PR3 SSE, PR4 ApproveGate

개요

데이터베이스 레이어 — UI와 같은 날

PR1 — Launcher

PR2 — Workspace 셸

PR3 — SSE 배관, 채팅 흐름, 그리고 7가지 피드 변형

스토어 레이어

배관 레이어

컴포넌트 레이어

PR4 — ApproveSheet와 세 게이트 변형

하루 끝 상태

인사이트

Creative Agent Studio 개발일지 #2 — 비트버킷 마이그레이션, production-readying, 그리고 React 재작성의 시작

개요

스택 1 — 비트버킷 마이그레이션 스냅샷

스택 2 — 런타임 production-readying

구조화 JSON 로거 + 채택

AbortSignal 기반 graceful 워커 셧다운

일일 유지보수 + /api/health + /api/metrics

싱글 EC2 배포 자산

런타임 리팩토링

스택 3 — React 재작성 부트스트랩

패키지 + 툴링

스토어 스캐폴드

<T> i18n 컴포넌트

디자인 프리미티브

공유 이벤트 스키마

PR1 전주곡

커밋 로그 (선별, 총 27개)

인사이트

Creative Agent Studio 개발일지 #1 — 4월 목업 시절, 그리고 Creative Warmth 테마를 입은 이유

개요

목업보다 오래 살아남은 세 가지 결정

“Creative Warmth” — 디자인 테마

목업을 정직하게 만든 세 가지 UI 정리

런타임 흐름 다듬기 — 목업 아래 뼈대

커밋 로그

인사이트

`<T>` i18n 컴포넌트