Number 3Apr 2026
UX 디자이너가 Claude Code로 AI 에이전트 다섯을 지휘해 포트폴리오 사이트와 디자인 시스템을 출시한다. 규칙은 CLAUDE.md가 정하고, hook이 강제한다. 판단은 전부 디자이너가 한다.
Devon Kim 에이전트 오케스트라
리서치 계층, 모든 에이전트의 앞단:
매핑하지 않은 엣지 케이스는 프로덕션에서 깨진다. James는 제품의 모든 경로를 기록한다. 해피 패스부터 시작해 모든 분기, 에러, 복구까지. 그의 결과물은 Sona, Kai, Miso에게 넘어간다.
핵심 팀
간격이 어긋난 곳을 누구보다 먼저 알아챈다. UX 리뷰에는 정확한 file:line 참조, 우선순위 태그, 구현 가이드가 붙는다. 막연한 제안은 하지 않는다.
AI가 쓴 글을 한눈에 알아본다. 결재를 여러 번 거쳐 무난해진 것 같은 카피는 Miso가 다시 쓴다. 병렬 구조 남발, 군더더기 표현, 뻔한 형용사를 전부 잡아낸다.
가장 좋은 코드는 쓰지 않은 코드다. Sona가 스펙을 보내면 Kai는 그대로 구현하거나, 왜 안 되는지 설명한다. 구현이 끝날 때마다 자동 QA가 돈다. 예외는 없다.
QA FAIL = FAIL. 린터가 놓치는 토큰 오용을 잡는다. DS 오버라이드가 새어 나온 건지, 일부러 적용한 스타일인지 구분할 줄 안다. "나중에 고치자"는 없다.
범례
실제 세션 하나를 예로 들면 이렇다. 프로세스 페이지 카피를 두고 외부 AI에게 피드백을 받았다. Miso를 불러 분석을 맡겼다. Miso는 sequential thinking으로 제안을 하나씩 뜯어보고, 피드백 자체에 AI 특유의 문장 구조가 있다고 짚은 뒤, 대부분 받아들이지 말라고 권했다. 나는 일부는 동의하고 일부는 동의하지 않았고, 직접 고쳤다. 타입 에러는 내가 보기도 전에 preview hook이 잡았다.
파이프라인도, 순서도도 없다. 필요한 에이전트를 부르고 다음으로 넘어갔다. 그게 가능한 건 하네스 덕분이다. 나 혼자 할 때보다 빠르게 움직이는 팀이 생긴다.
파일 하나가 아니라, 첫 프롬프트 전에 로드되는 여러 층의 묶음이다.
뿌리는 CLAUDE.md다. 책임 경계, 협업 흐름, 공통 기준, 충돌 해결 방식을 담는다. .claude/agents/에는 에이전트 정의가 있다. 페르소나, 판단 기준, 출력 형식이다. 규칙은 .claude/rules/에 둔다(다이어그램 규칙, 간격 강제 규칙). 인수인계 파일은 세션 사이의 맥락을 넘겨준다. 무엇을 했고, 무엇이 실패했고, 다음에 무엇을 이어서 할지. 계획과 메모리 파일까지 더하면 묶음이 완성된다.
프로젝트가 다르면 파일도 다르다. COLLABORATION.md, ARCHITECTURE.md처럼 그 프로젝트에 맞는 걸 쓴다. 구조는 바뀌어도 바뀌지 않는 게 있다. Claude가 시작할 때 읽는 .md 파일은 모두, 대화가 시작되기 전에 이미 행동을 제약한다.
이 프로젝트의 파일은 한국어로 썼다. 내가 한국어로 생각하기 때문이다. 에이전트는 한국어로 읽고, 내가 쓰는 언어로 답한다. 번역한 프레임워크가 아니라 내가 실제로 일하는 방식이다.
원래 워크플로에는 관문이 구현 후 QA 하나뿐이었다. 코드를 다 쓴 다음에 문제를 잡으면 비용이 크다는 걸 직접 겪고 배웠다. 다이어그램 좌표가 틀리고, 레이아웃이 겹치고, 패턴이 무시됐다. 모두 스펙 단계에서 리뷰했다면 코드 한 줄 쓰기 전에 잡았을 문제였다.
지금은 관문이 둘이다. Kai가 코드를 건드리기 전에 Sona가 스펙을 검증한다. 상태 커버리지, 패턴 충돌, 엣지 케이스, 정확한 값과 파일 참조를 본다. 스펙이 준비되지 않았으면 되돌려 보낸다. 구현이 끝나면 전처럼 Hana가 QA를 돌린다. 첫 번째 관문은 잘못된 스펙이 코드가 되는 걸 막고, 두 번째 관문은 잘못된 코드가 배포되는 걸 막는다.
CLAUDE.md에는 "구현할 때마다 자동 QA"라고 적혀 있다. 이건 규칙이다. 코드가 수정되면 실행되는 preview hook, 이게 강제다. 규칙은 건너뛸 수 있지만 hook은 건너뛸 수 없다.
Preview hook은 브라우저에 반영된 변경을 자동으로 검증한다. 따로 실행할 필요가 없다. settings.json은 에이전트별 파일 접근 범위와 권한을 정한다. MCP 연결은 할 수 있는 일의 범위를 넓힌다. 브라우저 확인은 Preview, 실제 상호작용은 Chrome, 문서는 Context7, 구조적 분석은 Sequential Thinking이 맡는다.
Kai가 코드를 쓰고 preview 서버가 돌고 있으면 hook이 실행된다. 허락을 구하지도, 명령을 기다리지도 않는다. 에러를 확인하고, 렌더링을 검증하고, 결과를 보고한다.
어떤 에이전트를 부를지 정할 때 순서도를 보지 않는다. 팀을 잘 알기 때문에 필요한 사람을 필요할 때 부른다.
하네스가 나를 지휘하는 게 아니라, 내가 하네스로 지휘한다. 외부 피드백이 "stateless/stateful 프레이밍을 넣어라"라고 하면 Miso를 불러 분석을 맡긴다. Miso의 분석은 판단 근거가 됐고, 결정은 내가 했다. 그리고 다음으로 넘어갔다.
실수는 전부 새 규칙이 된다. margin 기반 간격 때문에 레이아웃이 깨졌을 때는 CLAUDE.md와 Hana의 체크리스트에 간격 강제 규칙을 넣었다. DS 토큰이 포트폴리오 테마로 새어 나왔을 때는 분리 규칙을 넣었다. 하네스는 실패할 때마다 더 촘촘해진다. 메모리 파일은 .claude/memory/에 남아 세션이 바뀌어도 유지된다. 그래서 다음 대화는 이번 대화가 멈춘 곳에서 시작한다.