폴더가 에이전트가 되는 구조

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

작성자는 Cora를 개발하며 세 달 동안 여러 AI 에이전트가 서로 조정하는 swarm을 실험했지만, 결과를 검증할 컨텍스트가 부족해 작업 속도가 오히려 관리자의 평가 한계에 묶인다는 점을 겪었습니다. 이후 모델 자체보다 CLAUDE.md, 코드, 설계 문서, runbook, 장애 기록, 전문 에이전트 정의가 들어 있는 프로젝트 폴더를 하나의 전문 에이전트로 취급했고, 서로 다른 폴더에 같은 모델을 연결해 Rails 개발과 운영 업무를 분리했습니다. Ruby daemon 기반 디스패치 레이어는 lead agent가 만든 하위 작업 파일을 읽어 적절한 폴더의 worker를 실행하고 60초마다 상태를 확인하며, /hey와 /orchestrate 명령으로 44개 에이전트의 상태와 작업 배분을 관리합니다. Anthropic 연구에서 다중 에이전트가 연구 과제 점수를 단일 에이전트보다 90% 높였지만 토큰은 15배 사용했다는 수치와 함께, 컨텍스트 드리프트·에이전트 정지·US-ASCII 인코딩 오류가 한계로 남았습니다. 따라서 새 흐름은 먼저 직접 구축하고 사용해 신뢰성을 확인한 뒤에만 오케스트레이션으로 넘겨야 한다는 결론입니다.

실용적 조언

프로젝트 폴더의 CLAUDE.md가 다른 글에서 복사한 보일러플레이트라면 명명 규칙, 테스트 패턴, 배포 절차, 설계상의 판단을 실제 코드베이스에 맞게 기록합니다.
서로 간섭하지 않도록 별도의 git worktree에서 두 에이전트를 실행하고, 사람이 결과를 평가하거나 작업 위치를 추적하는 과정에서 병목이 생기는 지점을 확인합니다.
새 자동화 흐름은 곧바로 여러 에이전트에 배포하지 말고 직접 반복 실행해 정상 동작과 실패 처리를 확인한 뒤 디스패치 레이어에 연결합니다.
운영 작업용 폴더에는 애플리케이션 소스 코드를 넣지 않고 로그, 모니터링, read replica, 고객 티켓, 배포 기록에 접근하는 기술만 배치해 실수로 production code를 수정하는 경로를 줄입니다.

섹션별 상세

01

작성자는 여러 에이전트가 서로 작업을 나누는 swarm이 단일 에이전트보다 많은 일을 처리할 것으로 기대했지만, 10개가 동시에 결과를 내놓자 신뢰할 결과를 판단할 컨텍스트가 부족해졌습니다. 병렬 Claude Code 세션은 작업을 직접 배정할 때 유용했지만, 에이전트끼리 자율적으로 조정하는 구조에서는 평가 결과 자체가 새로운 병목이 되었습니다. 이 경험은 에이전트 수를 늘리는 것만으로 생산성이 증가하지 않으며, 결과를 선별할 사람의 처리 능력과 검증 구조가 함께 필요하다는 점을 드러냅니다.

02

Folder-as-Agent 구조는 모델에 코드를 전달하는 수준을 넘어 CLAUDE.md의 명명·테스트 규칙, architecture 문서, 이메일 처리 파이프라인, runbook, 장애 조사 기록, 전문 에이전트 정의를 함께 읽히는 방식입니다. Cora의 ~/cora/ 폴더는 Rails 개발에 필요한 규칙과 설계 지식을 제공하고, 별도의 ~/cora-agent/ 폴더는 앱 코드를 포함하지 않은 채 AppSignal, Render 로그, Postgres read replica, Intercom, GitHub 배포 기록을 연결해 운영 업무를 맡습니다. 같은 모델인 Opus 4.6도 어느 폴더에서 실행하느냐에 따라 코드 수정 에이전트와 운영 에이전트로 역할이 달라집니다.

GitHub의 Cora 저장소 docs 디렉터리에 developer-docs, investigations, postmortems, runbooks, solutions 등의 폴더가 나열되어 있습니다. — Screenshot이미지는 프로젝트 폴더가 단순한 소스 저장소가 아니라 개발 규칙과 운영 지식을 축적하는 메모리 시스템으로 쓰이는 모습을 담고 있습니다. 본문에서 설명한 설계 문서, 장애 조사, 사후 분석, runbook의 계층화가 실제 디렉터리 구조로 연결되며, 새 에이전트가 이 파일들을 읽어 Cora의 작업 방식과 운영 이력을 상속받는다는 주장과 직접 이어집니다.

03

44개 에이전트를 수동으로 관리하던 방식은 터미널 탭과 작업 위치를 추적해야 했고, 5개에서는 가능했지만 10개부터 누락이 생겼으며 44개에서는 지속하기 어려웠습니다. 작성자는 Ruby daemon이 디렉터리의 spawn request를 감시하도록 만들고, lead agent가 작업을 하위 작업 파일로 나누면 daemon이 적절한 폴더에서 worker를 실행하도록 연결했습니다. worker 결과는 파일로 돌아오고 daemon은 60초마다 상태를 확인하므로, 별도의 사용자 정의 네트워크나 에이전트 간 프로토콜 없이 파일 기반 메시징으로 작업 배분과 추적을 수행합니다.

Claude Code 터미널에서 /orchestrate 명령으로 작업을 시작하고, lead agent가 Sonnet agent를 실행해 Cora의 열린 이슈를 처리하는 화면입니다. — Screenshot화면에는 /orchestrate 명령, 작업 ID, 에이전트 실행 상태, 백그라운드 polling 흐름이 표시되어 있습니다. 이는 lead agent가 작업을 시작하고 하위 에이전트를 특정 컨텍스트에서 실행한 뒤 완료 여부를 확인하는 디스패치 구조를 구체화하며, 본문에서 말한 파일 기반 daemon과 비동기 운영 방식을 뒷받침합니다.

04

오케스트레이션은 자동화만으로 안정화되지 않았고, US-ASCII 인코딩을 쓰던 daemon이 em dash와 curly quote를 처리하지 못해 작업 중간에 반복적으로 종료되는 문제도 발생했습니다. 여러 에이전트가 오래 실행되면 낡은 작업을 계속하거나 이미 끝난 일을 중복하고, API 호출 과다나 입력 대기로 working 상태에 멈추는 사례도 생겼습니다. 그래서 새 흐름은 먼저 직접 만들고 사용해 예측 가능한 상태로 만든 뒤 신뢰할 수 있을 때만 디스패치 레이어에 맡겨야 하며, 글은 이를 “Build it, use it, trust it, and then orchestrate it”이라는 순서로 정리합니다.

용어 해설

폴더형 에이전트(Folder-as-Agent): — 모델 자체를 바꾸지 않고 프로젝트 폴더에 CLAUDE.md, 기술 문서, 실행 절차, 전문 에이전트 정의를 함께 배치해 특정 업무에 맞는 컨텍스트를 제공하는 방식입니다. 모델은 폴더의 파일을 읽은 뒤 코드베이스와 운영 지식을 상속받아 전문화된 작업을 수행합니다.
디스패치 레이어(Dispatch Layer): — 여러 폴더형 에이전트에 작업을 배분하고 진행 상태를 추적하는 상위 조정 계층입니다. 이 사례에서는 Ruby daemon이 파일로 생성된 작업을 읽고 적절한 폴더에서 worker를 실행하며, 60초마다 상태를 확인합니다.
Compound Engineering: — 작업 과정에서 얻은 규칙, 설계 지식, 장애 기록, 실행 절차를 프로젝트 문서와 에이전트 정의에 축적해 다음 작업의 출발점을 개선하는 개발 방식입니다. 글에서는 폴더가 시간이 지날수록 특정 코드베이스에 맞는 전문성을 갖추는 기반으로 쓰입니다.
컨텍스트 드리프트(Context Drift): — 여러 에이전트가 오래 실행되는 동안 일부가 최신 작업 상태를 놓치거나 이미 끝난 일을 다시 수행하는 현상입니다. 에이전트 수가 늘면 중복 작업과 토큰 낭비가 발생하고, 작성자는 활성 작업을 정리하는 부담을 직접 떠안게 됩니다.
파일 기반 메시징(File-Based Messaging): — 에이전트 사이에서 별도의 네트워크 프로토콜 대신 작업 요청과 결과를 파일로 기록해 전달하는 구조입니다. 글의 디스패치 레이어는 lead가 하위 작업 파일을 만들고 daemon이 이를 읽어 worker를 실행하며, worker도 파일에 결과를 남깁니다.

언급된 도구

Claude Code추천

CLAUDE.md와 프로젝트 폴더 컨텍스트를 활용해 코드 작업을 수행하고 /hey, /orchestrate 명령으로 에이전트를 관리합니다.

Ruby daemon추천

spawn request 파일을 감시하고 lead agent의 하위 작업을 적절한 폴더의 worker agent로 배분하며 상태를 확인합니다.

tmux중립

여러 에이전트 세션을 동시에 실행하고 각 에이전트의 pane을 실시간으로 확인합니다.

AppSignal중립

Cora 운영 환경의 오류와 성능 문제를 조회합니다.

Render중립

서버 로그를 실시간으로 확인합니다.

Postgres중립

read replica에서 사용자 데이터를 조회해 live 데이터베이스에 영향을 주지 않고 운영 분석을 수행합니다.

Claude Managed Agents중립

sandboxing, state management, tool execution을 호스팅 서비스로 처리해 개발자가 에이전트의 작업에 집중하도록 합니다.