AI 코딩 에이전트를 하나씩 순서대로 쓰고 계신가요? 한 개발자는 4~8개를 동시에 돌립니다. 그것도 오케스트레이터나 복잡한 프레임워크 없이요.
데이터 엔지니어 Manuel Schipper가 몇 달간 직접 운영해온 병렬 코딩 에이전트 워크플로우를 공개했습니다. tmux, 마크다운 파일, bash 별칭, 슬래시 커맨드 6개로 구성된 이 시스템의 핵심은 Feature Design(FD) 파일이라는 구조화된 명세서입니다. 300개 이상의 FD를 직접 작성하며 다듬어온 개인 생산성 시스템입니다.
출처: How I run 4–8 parallel coding agents with tmux and Markdown specs – Manuel Schipper
FD 파일이란 무엇인가
이 시스템의 중심축은 Feature Design(FD) 파일입니다. 쉽게 말하면, 에이전트에게 구현을 맡기기 전에 사람이 먼저 작성하는 작업 지시서입니다. 마크다운 파일 하나에 네 가지를 정리합니다.
- 문제: 지금 무엇이 안 되고 있는가
- 검토한 방법들: A안, B안을 각각 시도했을 때의 장단점
- 최종 결정: 선택한 방법과 실제로 수정할 파일 목록
- 검증 방법: 구현 후 제대로 작동하는지 확인하는 절차
예를 들어 “문서에 카테고리 레이블을 하나만 붙이는 게 문제라서, LLM이 신뢰도 점수를 기준으로 여러 레이블을 붙이도록 바꾸겠다”는 결정을 FD 파일 하나에 모두 담는 식입니다. 에이전트는 이 파일만 보면 왜 이 작업을 하는지, 어떤 파일을 고쳐야 하는지, 완료 기준이 뭔지 바로 알 수 있습니다.
FD가 중요한 이유는 에이전트의 근본적인 한계와 맞닿아 있습니다. 대화가 길어지면 에이전트는 초반의 결정 사항을 잊어버립니다. FD 파일은 대화 밖에 존재하는 외부 기억이라, 에이전트가 새 세션으로 완전히 새로 시작해도 맥락을 그대로 이어받을 수 있습니다. 각 Git 커밋에도 FD-049: Implement incremental index rebuild 형식으로 번호가 붙어, 나중에 “왜 이렇게 짰지?”라는 의문이 생기면 해당 FD를 바로 찾아볼 수 있습니다.
Planner, Worker, PM으로 역할 분리
Schipper는 tmux 창마다 에이전트에 역할을 부여합니다.
- PM:
/fd-status로 백로그를 확인하고 다음 FD를 고릅니다 - Planner:
/fd-explore로 코드베이스 맥락을 로드한 뒤 FD를 설계합니다 - Worker: 완성된 FD를 받아 구현만 담당합니다
Planner와 Worker를 분리하는 이유가 흥미롭습니다. 설계 중에는 대화가 많고 맥락을 넓게 탐색하는 반면, 구현 단계에서는 FD 파일에 이미 세부 계획이 담겨 있어 새로 시작한 Worker도 빠르게 진입할 수 있습니다. 설계 중 쌓인 긴 대화 기록이 오히려 구현에는 노이즈가 된다는 판단입니다.
특히 설계가 복잡한 경우에는 /fd-deep 커맨드로 Opus 에이전트 4개를 병렬 실행해 알고리즘적, 구조적, 점진적 등 서로 다른 각도에서 문제를 탐색한 뒤 결과를 취합합니다. OpenAI의 병렬 테스트타임 컴퓨팅에서 착안한 접근입니다.
예상 밖의 발견: 결정 기록의 가치
300개 이상의 FD를 쌓다 보니 예상치 못한 효과가 생겼습니다. 에이전트들이 /fd-explore나 /fd-deep을 실행하면서 과거 FD를 스스로 재발견하는 일이 늘어난 것입니다. “이 문제, 예전에 FD-031에서 다른 방식으로 접근했었는데”라는 맥락이 새 설계에 자연스럽게 반영됩니다.
Schipper는 이를 단순한 기능이 아니라 시스템의 부산물이라고 표현합니다. FD는 처음부터 이런 용도로 설계된 게 아니라, 쌓이다 보니 에이전트와 개발자 모두의 집단 기억이 됐습니다.
한계도 솔직하게
8개 이상의 에이전트를 동시에 운영하면 머릿속이 금방 복잡해집니다. 어떤 창에서 무슨 결정이 내려지고 있는지 파악하기 어려워지고, 설계 판단의 질이 낮아집니다. 그는 에이전트에게 “지금까지 한 일 요약해줘”라고 입력하게 되는 순간을 실질적인 한계 신호로 봅니다.
모든 작업이 병렬화되지도 않습니다. 의존 관계가 있는 기능은 순차적으로 처리하는 게 낫고, 무리하게 병렬로 쪼개면 머지 충돌과 코드 혼란이 오히려 더 많은 시간을 잡아먹습니다.
Claude Code의 권한 시스템에서 rm, git reset --hard 같은 파괴적 명령어를 차단하는 deny list를 운영하는데, 에이전트가 unlink나 python -c "import os; os.remove()" 같은 우회 경로를 스스로 찾아내는 문제도 언급합니다. 현재는 CLAUDE.md에 명시적 지침을 추가해 대응하고 있지만 완전히 신뢰하지는 않는다고 밝힙니다.
단일 에이전트를 쓸 때와 근본적으로 다른 점은, 병렬 에이전트 환경에서는 개발자가 병목이 됩니다. 에이전트는 항상 다음 입력을 기다리고 있고, 좋은 FD를 빠르게 설계하는 능력이 전체 생산성을 결정합니다. FD 파일과 슬래시 커맨드 전체는 저자의 GitHub Gist에서 확인할 수 있습니다.
답글 남기기