병렬 에이전트를 잘 관리하려면 격리하고 기록하고 합치는 구조가 먼저입니다

This is the long-form blog cut of a note I originally posted on LinkedIn. The claims, numbers, and product names are the same; the formatting is for reading on the site.

Context

Original framing (translated in place for key technical posts; substance preserved):

에이전트 여러 개를 동시에 돌리는 게 항상 좋은 건 아닙니다. 혼자 집중해서 한 작업을 끝내는 게 더 빠른 경우도 많아요.

그런데도 병렬 에이전트에 시간을 쓰는 이유가 있습니다. 앞으로 개발 워크플로우가 가는 방향에 제일 가깝다고 느꼈거든요.

아직 매번 배우는 중이고 삽질도 많이 했습니다. 그 과정에서 반복적으로 효과가 있었던 구조를 두 가지 경로로 나눠서 정리했습니다.

1️⃣ Parallel Path. 사람이 개입하며 방향을 잡아주는 경로

이 경로는 Plan → Spawn → Gate → Merge 순서로 움직입니다. tmux 안에서 interactive worker 를 띄우고 사람이 중간에 방향을 잡아줄 수 있는 구조예요.

• Isolate. agent_workers.py 에 작업 이름과 base 브랜치와 에이전트 CLI 를 지정하면 worktree 생성부터 에이전트 실행까지 한번에 끝남. one branch and worktree per bounded task 가 원

에이전트 여러 개를 동시에 돌리는 게 항상 좋은 건 아닙니다. 혼자 집중해서 한 작업을 끝내는 게 더 빠른 경우도 많아요.

그런데도 병렬 에이전트에 시간을 쓰는 이유가 있습니다. 앞으로 개발 워크플로우가 가는 방향에 제일 가깝다고 느꼈거든요.

아직 매번 배우는 중이고 삽질도 많이 했습니다. 그 과정에서 반복적으로 효과가 있었던 구조를 두 가지 경로로 나눠서 정리했습니다.

1️⃣ Parallel Path. 사람이 개입하며 방향을 잡아주는 경로

이 경로는 Plan → Spawn → Gate → Merge 순서로 움직입니다. tmux 안에서 interactive worker 를 띄우고 사람이 중간에 방향을 잡아줄 수 있는 구조예요.

• Isolate. agent_workers.py 에 작업 이름과 base 브랜치와 에이전트 CLI 를 지정하면 worktree 생성부터 에이전트 실행까지 한번에 끝남. one branch and worktree per bounded task 가 원칙 • Steer. 에이전트가 막히면 tmux send-keys 로 후속 프롬프트를 보냄. 미완료 worker 를 끝까지 밀어주는 게 핵심 • Control. 모든 worker 는 changelog 항목이나 fragment 를 남겨야 함. 통과한 작업만 starting branch 로 merge 되고 실패한 건 blocker report 가 생성

한 브랜치에서 에이전트 2개를 돌린 적이 있습니다. 10분 만에 둘 다 같은 컴포넌트를 수정해서 diff 가 꼬였어요. worktree 격리 없이 병렬을 돌리면 결국 사람이 충돌을 수습하느라 더 느려집니다. Spawn 단계에서 scope 를 좁게 잡아야 Gate 에서 리뷰할 분량이 줄어들어요.

2️⃣ Deterministic Path. 사람 없이 반복 가능한 경로

Parallel Path 가 사람의 개입을 전제로 한다면 이쪽은 정반대입니다.

Preflight → Backups → Logs → Pass Gate 순서로 움직이고 사람이 중간에 끼어들지 않아요. backup 이나 조건 검증이나 로그 기록처럼 매번 같은 결과가 나와야 하는 작업에 쓰는 경로입니다.

• Repeat. JSON plan 이 Bash 나 Python 루프를 렌더링. render_worker_loop.py 에 config 파일과 언어와 출력 경로를 지정하면 결정론적 스크립트가 생성됨 • Fail. preflight 단계에서 backup 이 실패하면 모든 worker 의 시작 자체를 차단. 반쪽짜리 실행을 원천 봉쇄하는 설계 • Inspect. 롤백 명령어는 기록만 해두고 자동 실행하지 않음. “recorded, not auto-fired” 가 이 경로의 핵심 원칙

두 경로의 구분 기준은 간단합니다.

에이전트에게 중간에 방향을 틀어줘야 하면 Parallel Path 로 tmux worker 를 쓰고, 매번 동일하게 돌아가야 하면 Deterministic Path 로 Python 이나 Bash 루프를 씁니다.

직접 써보니 보통의 경우 기능 개발은 Parallel Path 가 맞고 서버 마이그레이션이나 DB 백업 같은 운영 작업은 Deterministic Path 가 맞았어요.

3️⃣ Changelog Gate. 두 경로 모두를 관통하는 통제 장치

어떤 경로를 쓰든 merge 전에 반드시 거치는 관문이 changelog gate 입니다. 운영 원칙은 “Changelog first, merge back last” 예요.

• 모든 worker 가 changelog 항목이나 fragment 를 남기도록 강제. 기록 없으면 merge 불가 • diff 리뷰는 사람이 하되 에이전트가 테스트를 먼저 통과한 것만 리뷰 대상에 올림 • 통과한 작업은 starting branch 로 돌아가고 실패한 건 blocker report 에 이유가 기록

changelog gate 도입 전에는 merge 후 버그를 찾는 데 에이전트가 코드 짜는 시간보다 오래 걸렸습니다. gate 를 넣고 나서야 병렬의 속도가 실제 생산성으로 전환됐어요.

4️⃣ Harness Converter. 에이전트를 바꿔도 워크플로우는 그대로 유지

Recursive Harness Converter 는 특정 에이전트 CLI 에 종속되지 않게 만드는 변환기입니다. generic defaults 를 target agent CLI 에 매핑하는 방식이에요.

• inspect help. 대상 에이전트 CLI 의 옵션과 기본값을 자동 탐색 • convert. docs 와 scripts 와 examples 와 tests 를 한번에 변환 • log. conversion report 와 changelog status 와 merge-back blocker 목록이 자동 생성. 단위 테스트와 통합 테스트를 edge case 포함해서 광범위하게 돌리는 것까지가 converter 의 범위

현재의 에이전트 도구는 6개월이면 많은 것이 바뀝니다. Claude Code 를 쓰다가 Codex 로 갈아탈 수 있고 그 반대도 가능해야 해요. 그때 워크플로우 전체를 다시 짜는 게 아니라 harness 설정 하나만 바꾸면 되는 구조가 필요합니다.

결국 에이전트를 몇 개 돌리느냐보다 각 에이전트가 뭘 했고 어디서 막혔는지 changelog 와 blocker report 로 읽을 수 있느냐가 중요합니다. 작업을 격리하고 결과 상태를 전달하는 구조만 있으면 에이전트가 3개든 10개든 같은 방식으로 관리할 수 있어요.

병렬 에이전트가 꼭 정답인지는 아직 모릅니다. 다만 이 방향이 결국 AI 가 지향하는 방향이지 않을까 하는 마음에 오늘도 계속 도전합니다.