여러 코딩 에이전트 간 작업 조정하기
당신은 조정자입니다: 작업 정의를 소유하고, 모든 결과물을 검토하며, 다음 단계를 결정합니다. 다른 모든 에이전트는 작업자입니다: 명세를 받고, 산출물을 생성한 후 중단됩니다. 공급업체 간 메시지 버스가 없으므로 조정은 턴제(turn-based)이며 파일을 매개로 이루어집니다:
당신이 task.md 작성 -> 작업자가 headless로 실행 -> 작업자가 result.md 작성 ->
당신이 읽고, 확인하고, 다음 턴 결정
agent-sync가 설치되어 있다면, 위임하기 전에 agent sync를 실행하여 모든 작업자가 당신이 가진 것과 동일한 합성 메모리로 시작하도록 하세요.
1. 작업 디렉토리 작성
task/
task.md # 명세 (아래 계약 참조)
...inputs... # 작업자에게 필요한 모든 것; 작업자는 다른 컨텍스트를 받지 않음
result.md # 작업자가 작성함; 이 파일이 존재하면 완료를 의미
task.md는 계약서와 같으며 다음을 반드시 포함해야 합니다:
- 한 문단으로 된 목표;
- 정확한 결과물 (파일, 이름 명시);
- 확인 가능한 완료 조건;
- 결과물을 작성한 후 중단하라는 지시;
- 작업자가 공유 트리를 편집할 경우 섹션 2의 잠금 또는 작업트리 규칙.
2. 누군가를 호출하기 전에 공유 모드 선택
규칙 제로: 두 에이전트가 동시에 같은 작업 트리를 변경해서는 안 됩니다.
| 상황 | 모드 |
|---|---|
| 작업자가 읽기만 하는 경우 (검토, 분석, 의견) | 동일 디렉토리, 잠금 없음 |
| 하나의 트리에서 번갈아 편집하는 경우 | 동일 디렉토리 + mkdir 잠금 |
| 병렬 시도 또는 병렬 파일 접근 하위 작업 | 작업자당 하나의 git 작업트리 |
| 두 에이전트가 하나의 트리를 동시에 편집하는 경우 | 절대 안 됨; 재구조화 |
동일 디렉토리 잠금 (mkdir은 원자적입니다; 이 지침을 task.md에도 포함하세요):
until mkdir .agent-lock 2>/dev/null; do sleep 1; done # 획득
echo "$(whoami):$$" > .agent-lock/owner
# ... 작업 ...
rm -rf .agent-lock # 해제
잠금을 시간으로 자동 만료시키지 마세요: 느린 작업자는 죽은 작업자와 구별할 수 없습니다. 오래된 잠금을 해제하기 전에 작업자 프로세스가 실제로 종료되었는지 확인하세요.
작업트리 모드: 작업자당 git worktree add ../task-<worker> -b agent/<worker>를 실행하고, 작업자는 절대 푸시하지 않으며 서로의 트리를 건드리지 않고, 메인 체크아웃은 읽기 전용으로 유지하며, 당신(조정자)이 모든 병합을 단일 직렬화된 단계로 수행합니다.
3. 작업자를 headless로 호출
| 작업자 | 명령어 |
|---|---|
| Claude Code | claude -p "Read task.md in this directory and complete it." |
| Codex CLI | codex exec --skip-git-repo-check --sandbox workspace-write "Read task.md in this directory and complete it." </dev/null |
| Gemini CLI | gemini -p "Read task.md in this directory and complete it." |
어렵게 얻은 규칙들:
- 작업 디렉토리 내부에서 작업자를 실행하고 쓰기 접근을 해당 디렉토리로 제한하세요.
- 백그라운드 작업자의 경우 stdin을 닫으세요 (
</dev/null). 그렇지 않으면 입력을 기다리며 멈출 수 있습니다. - Codex는
--skip-git-repo-check없이 신뢰할 수 없는 비-git 디렉토리를 거부합니다.
4. 확인 후 결정
- 작업자의 말이 결과물이 아닙니다.
result.md를 읽고 완료 조건과 비교하여 확인하세요. 코드의 경우 직접 테스트를 실행하세요. - 결과물이 없거나 잘못된 경우 동일한 명세를 재시도하지 말고 더 명확해진 명세와 함께 새로운 턴을 시작하세요.
- 당신이 수락하는 모든 것에 대해 책임을 집니다: 사람 계약자의 PR을 검토하듯 작업자의 diff를 검토하세요.
경계
- 작업자에게 자격 증명, 배포 권한, 또는 실제 사용자에 대한 접근 권한을 절대 부여하지 마세요. 작업자는 결과물을 생성하고, 조정자(사용자와 함께)가 이를 배포합니다.
- "간단한" 작업이라도 잠금이나 작업트리 없이 하나의 트리 내에서 병렬 편집을 위해 이 프로토콜을 실행하지 마세요.
- 어떤 에이전트가 조정자 역할을 할지 사용자가 결정합니다. 조정 권한을 작업자에게 넘기지 마세요.