제로에서 그래프 아키텍트까지: Claude 그래프 엔지니어링 14단계 로드맵

멀티에이전트 파이프라인을 만드는 사람 대부분은 결국 일직선으로 끝난다. 이걸 하고, 그다음 이걸 하고, 그다음 이걸 하고 — 그러면서 왜 모든 단계가 앞 단계를 기다리고 있는지는 한 번도 의심하지 않는다. 그 순서의 절반은 실체가 없다. 그냥 누군가 단계를 입력한 순서일 뿐이다.

이 글은 그것을 알아차리고 더 나은 것을 만드는 로드맵이다. 바로 그래프다. 독립적인 작업은 동시에 돌고, 결과는 인정되기 전에 검증되며, 전체는 하나의 대화가 머릿속에 담을 수 있는 규모를 넘어서 확장된다. Claude Code에는 이것을 실제로 실행하는 내장 방법이 있는데, dynamic workflows라고 부른다. 그래서 이 로드맵은 각 아이디어마다 실제로 구현하는 방법을 짝지어 설명하며, 이력서 스크리닝 파이프라인을 관통 예제로 사용한다.

본론에 들어가기 전에, 이런 아티클을 더 보고 싶다면 X에서 나를 팔로우하라.
X - https://x.com/waynoir

1. 노드는 작업이고, 엣지는 사실이다

노드(node)는 경계가 정해진 하나의 작업 단위다. 에이전트 하나, 입력 하나, 출력 하나. 엣지(edge)는 "그다음에"가 아니다. 엣지는 한 노드의 출력이 다른 노드에 의해 실제로 소비될 때만 존재한다. "이력서를 파싱하고, 그다음에 날씨를 확인한다"에는 엣지가 없다. 날씨 확인은 이력서를 읽지 않기 때문이다. 그렇게 사슬로 묶인 두 노드는 아무 이유 없이 큐 하나를 공유하고 있을 뿐이다.

기를 만한 습관은 이것이다. 파이프라인의 모든 "그다음에"마다, 다음 단계가 앞 단계의 산출물을 읽는지 물어라. 읽지 않는다면 엣지는 없는 것이고, 하나가 다른 하나를 기다릴 이유도 없다.

2. 당신의 일직선 에이전트는 이미 그래프다, 다만 나쁜 그래프일 뿐

"A를 하고, B를 하고, C를 하고, D를 한다"도 엄밀히 말하면 그래프다. 모든 노드가 정확히 들어오는 엣지 하나와 나가는 엣지 하나를 가지는 사슬(chain)이다. 작동은 하지만 취약하다. C가 멈추면 D는 영영 실행되지 않고, 그 상류에 있는 모든 것은 완료된 채로 쓸모없이 그냥 앉아 있게 된다.

사슬을 다시 그리는 것이 여기서 첫 번째 진짜 기술이다. 화살표 하나하나를 붙잡고 1단계의 질문을 던져라. 대부분의 사슬에는 데이터를 실어 나른 적이 한 번도 없는 화살표가 두세 개 있다. 그저 남겨진 순서일 뿐이다.

3. 모든 노드에 계약을 부여하라

고립된 상태로 추론할 수 없는 노드는 병렬화할 수 없는 노드다. 해법은 계약(contract)이다. 정의된 입력, 정의된 출력, 하나의 작업, 공유된 대화에서 암묵적으로 끌어오는 것은 아무것도 없어야 한다.

Claude Code의 dynamic workflow에서 이 계약은 agent()에 전달하는 JSON schema로 강제된다. 서브에이전트는 검증된 구조화 데이터를 반환하도록 강제된다. schema와 맞지 않으면, 손으로 파싱해야 할 자유 텍스트를 넘겨주는 대신 Claude가 자동으로 재시도한다.

const VERDICT = {
  type: 'object',
  additionalProperties: false,
  properties: {
    eligible: { type: 'boolean' },
    fit_score: { type: 'number' },
    reasoning: { type: 'string' },
  },
  required: ['eligible', 'fit_score', 'reasoning'],
};

const result = await agent(`Screen this resume against the JD:\n${resume}`, {
  label: `screen:${resume.id}`,
  schema: VERDICT,
});

4. 엣지를 순서가 아니라 데이터 계약으로 취급하라

엣지는 약속이다. 노드 A는 정확히 이 형태를 생산하고, 노드 B는 그것을 소비하도록 만들어져 있다. 엣지를 순서가 아니라 데이터로 명명하면, 형태만 유지되는 한 어느 쪽 노드든 더 나은 것으로 교체해도 다른 어떤 것도 깨지지 않는다.

5. parallel()로 팬아웃하라

이것이 로드맵의 나머지 전부를 값어치 있게 만드는 한 수다. N개의 독립적인 작업이 주어졌을 때 — 예컨대 스크리닝할 이력서 300건이나 감사할 파일 40개 — 그것들을 사슬로 묶지 마라. parallel()은 썽크(thunk) 배열을 받아, 썽크당 서브에이전트 하나를 띄우고, 전부를 기다린다.

phase('Screen');
const raw = await parallel(
  APPLICANTS.map((a) => () => agent(a.prompt, { schema: VERDICT, label: `screen:${a.id}` }))
);
const collected = raw.filter(Boolean); // a thrown thunk resolves to null, not a crash

여기서 두 가지 디테일이 중요하다. parallel()은 배리어(barrier)다. 모든 썽크가 resolve되기 전까지는 그 뒤의 어떤 것도 실행되지 않으므로, 다음 스테이지는 완전한 집합을 보게 된다. 그리고 실패한 에이전트 하나는 배치 전체를 무너뜨리는 대신 null로 resolve된다. 그래서 .filter(Boolean)이 항상 그 바로 뒤에 붙어야 하는 것이다.

6. 팬인은 스테이지가 진짜로 전체 집합을 필요로 할 때만

팬인(fan-in)은 결과가 수렴하는 곳이다. 중복 제거, 순위 매기기, 아무것도 돌아오지 않았을 때의 조기 종료. 배리어가 그 비용값을 하는 유일한 지점인데, 어떤 결정들 — 이를테면 이 300건 중 어떤 것들이 실제로 서로의 중복인가 — 은 전원을 한꺼번에 보지 않고는 내릴 수 없기 때문이다.

합치는 작업이 정말로 리스트를 평탄화하는 것뿐이라면, 그건 배리어를 둘 이유가 아니다. 그냥 평범한 코드다.

const flat = collected.filter((c) => c.eligible).sort((a, b) => b.fit_score - a.fit_score);

7. 다이아몬드: 쪼개고, 일하고, 짜내고, 결정한다

팬아웃과 팬인을 합치면 거의 모든 진지한 파이프라인 뒤에 있는 형태가 나온다. 노드 하나가 작업을 쪼개고, 여러 노드가 병렬로 일하고, 노드 하나가 병합한다. 소스 데이터와 프롬프트만 바꾸면, 같은 뼈대가 이력서 스크리닝도, 보안 감사도, 리서치 리포트도 커버한다.

8. 런타임 라우팅은 프롬프트가 아니라 조건문으로

때로는 다음 단계가 노드가 발견한 것에 따라 달라진다. 애매한(borderline) 이력서는 더 자세히 들여다보고, 명백한 탈락은 그러지 않는다. 그 라우팅 판단 자체는 Claude가 담당할 수 있지만(서브에이전트가 분류한다), 분기 자체는 코드로 쓰인 평범한 if다.

const { severity } = await agent(`Classify this application:\n${a}`, { schema: TIER });
let review = severity === 'borderline'
  ? await parallel(PANEL.map((p) => () => agent(`Review as ${p}: ${a}`)))
  : await agent(`Quick check: ${a}`);

라우팅이 코드에 살고 있기 때문에, 어떤 케이스가 어떤 경로를 탔는지에 대한 모호함이 없다. 같은 분류에 대해서는 매번 같다.

9. 엣지에 검증자를 두되, 백지 상태를 주어라

그래프를 그저 빠른 것이 아니라 신뢰할 수 있는 것으로 만드는 단 하나의 가장 큰 요소: 첫 번째 에이전트의 추론을 본 적이 없는 검사자다. 작업자가 쓴 것과 같은 대화를 읽는 검증자는 아무것도 검증하고 있지 않다. 이미 하나의 답에 정박(anchoring)되어 있고, 그 같은 컨텍스트 안에서 재고를 요청해 봐야 대부분 검증으로 분장한 동의만 나온다.

진짜 검증자는 원자료만 받는다. 이력서와 직무 기술서(JD), 그 외에는 아무것도 받지 않고, 독립적으로 스스로의 결론에 도달해야 한다.

10. 하나의 실패나 하나의 쓰기 충돌이 번지지 않도록 노드를 격리하라

parallel() 안에서 throw된 썽크는 배치를 크래시시키는 대신 이미 null로 resolve되므로, 실패 봉쇄의 대부분은 그것으로 처리된다. 더 미묘한 위험은 같은 파일에 쓰는 노드들이다. 여러 에이전트가 겹치는 파일을 병렬로 건드리면, 정말로 충돌할 수 있다.

Claude Code의 답은 worktree 격리다. 각 병렬 에이전트가 자기만의 git 체크아웃을 받아, 샌드박스 안에서 작업하고, 마지막에 깔끔하게 병합한다. 노드들이 실제로 병렬로 쓰기를 할 때만 꺼내 드는 것이지, 모든 실행마다 치러야 하는 세금이 아니다.

11. 사이클을 추가하되, 수렴을 강제하라

어떤 작업은 시작 시점에 크기를 알 수 없다. 개수를 모르는 인증 누락(missing-auth) 버그라든지, 개수를 모르는 재검토가 필요한 애매한 지원서라든지. 그럴 때 필요한 것이 사이클이다. 앞선 노드로 되돌아가는 통제된 엣지.

사이클이 영원히 돌지 않게 하는 패턴은 loop-until-dry다. 연속된 몇 라운드 동안 새로운 것이 아무것도 나오지 않을 때까지 계속하고, 그러면 멈춘다. 이것이 실제로 작동하게 만드는 디테일은, 확정된 결과만이 아니라 지금까지 본 모든 것에 대해 중복 제거를 하는 것이다. 그러지 않으면 기각된 발견이 매 라운드 다시 나타나서 루프가 영영 마르지 않는다.

12. 노드별로 모델을 티어링하라

모든 노드에 최고 모델이 필요한 것은 아니다. 이력서의 빠른 자격 요건 체크는 범위가 한정되고 반복적이다. 최종 쇼트리스트를 종합하고 그 뒤의 근거를 작성하는 일이야말로 판단력이 실제로 사는 곳이다. 기본적으로 workflow가 띄우는 모든 서브에이전트는 세션의 모델을 상속받는다. 개별 agent() 호출의 model 옵션이야말로, 그래프의 형태는 건드리지 않은 채 특정 노드만 더 저렴한 곳으로 라우팅하게 해주는 수단이다.

13. 배리어가 아니라 스트리밍을 기본값으로

조용히 가장 많은 실제 소요 시간(wall-clock time)을 잡아먹는 선택은 parallel() 대 스트리밍 파이프라인이다. parallel() 배리어는 다음 스테이지가 시작되기 전에 모든 항목이 가장 느린 하나를 기다리게 만든다. 스트리밍은 빠른 항목들이 스스로 모든 스테이지를 통과해 나아가게 한다. 이력서 #180이 아직 파싱 중일 때 이력서 #4는 이미 검증 스테이지에 가 있을 수 있다.

배리어는 한 스테이지가 진짜로 전체 집합을 한꺼번에 필요로 할 때만 꺼내라. 배치 간 중복 제거, 점수 기준 순위 매기기, 총합이 비었을 때의 조기 종료. "코드가 더 깔끔해서"는 이유가 아니다. 배리어 지연은 실재하며 측정 가능하다.

14. 그래프를 Claude가 대신 그리게 하라

마지막 한 수는, 사전에 완전히 계획할 수 없는 작업에 대해서는 그래프를 손으로 그리는 것을 그만두는 것이다. Claude Code 프롬프트에 "workflow"라는 단어를 말하거나 ultracode effort 설정을 켜면, Claude가 오케스트레이션 스크립트 자체를 작성한다. 팬아웃, schema, 검증 패스, 병합까지, 고정된 템플릿이 아니라 실제로 기술된 작업에 맞춰서 결정한다. /workflows는 실행을 라이브로 보여준다 — 지금 어느 페이즈인지, 에이전트가 몇 개나 끝났는지 — 그동안 세션은 다른 작업을 위해 자유롭게 남는다. 좋은 실행은 s로 저장할 수 있고, ~/.claude/workflows/에 이름 붙은 스크립트로 남아 나중에 다시 실행할 준비가 된다.

Dynamic workflows는 동시 실행 에이전트 16개, 실행당 1,000개가 상한이다. 코드베이스 전체 마이그레이션이 아닌 이상 거의 무엇이든 담을 만큼 넓고, 스코프가 잘못 잡힌 실행이 무한정 에이전트를 띄우는 것을 막는 확실한 천장이기도 하다. Max, Team, Enterprise 플랜에서는 기본으로 켜져 있고, Pro에서는 /config의 토글이다.

이 로드맵이 적용되지 않는 곳

이력서 한 건, 일회성 버그 픽스, 혹은 조율 체계를 만드는 시간보다 에이전트 하나가 끝내는 게 더 빠를 만큼 작은 일에는 이 중 어떤 것도 세팅할 가치가 없다. 단계들이 정말로 순차적으로 서로 의존하는 곳에서도 잘못된 도구다. 착취할 독립성이 없으니, 쪼개 봐야 오버헤드만 늘어난다. 그리고 모든 중간 결과를 직접 읽고 승인할 계획이라면, 그래프의 핵심 이점 — 아무도 각 단계를 지켜보지 않은 채 넓게 돌리는 것 — 이 오히려 그 목표에 반해서 작동한다.

진짜 전환

물을 가치가 있는 질문은 애초에 "다음에 무엇이 일어나야 하는가"가 아니었다. 그 질문은 더 긴 사슬만 만들어낼 뿐이다. 파이프라인을 만드는 방식을 바꾸는 질문은 "무엇이 실제로 무엇에 의존하고, 무엇은 의존하지 않는가"다. 그 질문에 답하고 나면, 할 일은 더 이상 더 긴 프롬프트를 쓰는 것이 아니다. 작업이 흘러가는 형태를 결정하는 것이고, 그 형태가 결과물이 빠르고 신뢰할 수 있는 것이 될지, 아니면 그저 몇 가지 일을 하나씩 처리하는 비싼 방법이 될지를 결정한다.

AI에서 일어나는 모든 것을 계속 따라잡고 싶다면.
X에서 나를 팔로우하라 : https://x.com/waynoir