본 기사의 위치— 본 기사는 awslabs/aidlc-workflows 리포지토리의 규범 규칙 및 이용 가이드를 소재로 하여, 필자가 AI를 활용해 읽어내고 정리한 해석입니다. AWS가 공식적으로 발표한 방법론이 아니며, 1차 자료의 번역·요약도 아닙니다.

시리즈— 본 기사는 AI로 풀어보는 AI-DLC v2 시리즈의 일부입니다.

참조한 버전— Claude Code 구현을 대상으로, 2026년 6월 시점의 v2.1.3(커밋 c95070e, core/)을 참조하고 있습니다. Kiro·Codex 구현은 대상에서 제외되며, 기술 내용이 다를 수 있습니다. OSS 구현은 업데이트가 계속되고 있으므로, 최신 상태는 공식 리포지토리를 확인해 주시기 바랍니다.

swarm은 Construction(구축)의 자율 모드 하에서 여러 개의 Bolt(구축의 실행 단위)를 병렬로 실행하는 메커니즘입니다. 서로 의존하지 않는 빌드 유닛을 격리된 git worktree로 분배하며, 각각이 "테스트가 통과(green)하고 변조되지 않은(un-tampered)" 상태가 된 것들만 직렬로 base에 통합하여 되돌립니다. 각 유닛의 수렴을 권위로서 판정하는 것이 심판 역할인 레퍼리(referee)입니다.

이 부분은 자율 모드까지 깊게 파고든 임의의 심층 분석입니다. 병렬로 실행하면서 심지어 사람이 그 현장에 보고 있지 않은 상황은 본래 리스크를 동반하지만, AI-DLC v2는 이를 3자 분담이라는 설계로 안전한 방향으로 기울여 놓았습니다. 컨덕터(conductor), 툴(tool), 사람(human)이 각각 성질이 다른 관심사를 가지며, 합격했다는 자기 신고를 마지막에 다시 한번 검증한 뒤 통합합니다. 이 분담과 검증 메커니즘이 병렬 실행을 성립시킵니다.

워킹 스켈레톤(Walking Skeleton, 첫 번째 Bolt)이 승인되고, 사람이 "남은 Bolt는 자율적으로 실행해도 좋다"라고 결정하면, 서로 의존하지 않는 Bolt를 묶어서 병렬로 진행할 수 있게 됩니다. 이를 담당하는 것이 swarm입니다.

엔진이 invoke-swarm 지시(directive)를 발행하는 것은, 자율 모드가 부여되고, code-generation 스테이지에 있으며, 컴파일된 유닛 DAG(의존 관계 그래프)에 실행 가능한 병렬 배치(batch)가 갖춰져 있을 때만입니다. 자율 모드가 gated(승인 게이트를 경유함 = 자율적으로 실행하지 않음) 상태이거나 미설정된 동안에는, 엔진은 평소와 다름없이 run-stage를 계속 발행하며 아무것도 병렬화하지 않습니다. 첫 번째 Bolt는 설정과 관계없이 반드시 승인 게이트를 통과하므로 swarm의 경로에는 타지 않습니다. invoke-swarm이 하나의 지시 사항이라는 점이나 지시의 정의 자체는 별도 기사 「진행의 핵심」에서 다룹니다.

invoke-swarm의 형태는 의도적으로 최소화되어 있으며, 분배할 배치를 나타내는 units만을 가집니다. 나머지 배치 문맥은 컨덕터가 컴파일된 그래프에서 읽기 때문에, 지시 측의 내용은 더 이상 늘어나지 않습니다. 여러 리포지토리를 묶는 경우에 한하여, 대상 리포를 일의적으로 해결할 수 있을 때만 임의의 repo 필드가 추가됩니다.

swarm 설계의 정본은 툴 본체인 aidlc-swarm.ts 서두의 코멘트 한 문장에 응축되어 있습니다.

THE SPLIT (three concerns): the conductor owns fan-out + loop drive (knowledge); this tool owns the convergence verdict + merge + audit (determinism); the human grants autonomy and takes the baton on the envelope (judgement).

하나의 작업처럼 보이는 것을 성질이 다른 세 가지 관심사로 나누고 있습니다.

담당자	보유 항목	성질
컨덕터 (Conductor)	워커(worker) 기동 (N 병렬의 Task, 또는 AIDLC_USE_SWARM=1로 인라인 Workflow) 및 재시도 루프 구동	지식 (Knowledge) (다시 시도할지, 본질적으로 만들 수 없는지를 판단함)
툴 aidlc-swarm.ts	수렴 판정 · anti-tamper · 직렬 머지 · 감사 · 타입이 지정된 실패 엔벨로프(envelope)	결정론 (Determinism) (동일한 입력이라면 몇 번을 호출해도 동일한 결론)
사람 (Human)	자율 모드 부여 및 실패 엔벨로프를 받아 바통을 이어받는 것	판단 (Judgement)

워커를 기동하는 층이 왜 툴 안에 없는가. 툴의 실체인 bun의 서브 프로세스는 Task

호출을 발행할 수 없기 때문입니다. 따라서 「움직이는 지식 (moving knowledge)」은 컨덕터 (Conductor)에 두고, 결정론적 (deterministic)이어야 하는 부분만을 툴 (Tool)에 남깁니다. 툴은 상태를 가지지 않는 세 가지 서브커맨드 (prepare / check / finalize)만을 공개합니다.

병렬로 실행되는 여러 유닛 (Unit)이 서로의 작업을 침범하지 않도록, prepare는 유닛마다 격리된 git worktree (.aidlc/worktrees/bolt-<slug>/, 브랜치 bolt-<slug>)를 생성합니다. 여기에 상태·감사·그래프의 파편 (fragment)이 포크 (fork)되며, 워커 (Worker)는 각각의 worktree 내부에서만 작업합니다. 완료된 유닛은 스쿼시 머지 (squash merge)를 통해 베이스 (base)로 접혀 들어가 통합됩니다.

변조 탐지 (anti-tamper) 기준치를 어딘가에 별도로 저장하지는 않습니다. 보호 대상 파일의 「정본 (source of truth)」은 해당 worktree 자신의 git fork (HEAD)에 있는 내용 그 자체입니다. 워커가 보호 파일을 수정하면 이는 작업 트리 (working tree)의 변경으로 나타나며, git diff --quiet HEAD가 변경 사항이 있음을 반환합니다. check와 finalize 모두 이 원래의 바이트 열 (byte sequence)을 매번 그 자리에서 다시 유도해내기 때문에, 상태를 공유하지 않고도 반드시 일치하게 됩니다.

검증 대상 테스트 파일에 ../를 포함하여 worktree 외부를 가리키는 경로가 전달된 경우, 변조되지 않은 것으로 간주하지 않고 설정 오류로 처리하여 차단합니다. 이를 허용하면 변조 탐지가 조용히 무효화될 수 있기 때문입니다.

수렴 (convergence)의 신호는 프로젝트 테스트 커맨드의 exit 0만이 권위를 가집니다. 워커 자신의 「성공했습니다」라는 신고는 합격을 위조할 수 있으므로 결코 믿지 않습니다. 여기에는 두 단계의 역할 분담이 있습니다.

• check <unit>은 권고 (advisory) {unit, converged, tampered, reason}를 출력하며, 진정한 수렴 (녹색이며 변조되지 않음) 상태일 때만 exit 0을 반환합니다. 감사는 아무것도 발행하지 않으며, 아무것도 통합하지 않습니다. 이는 컨덕터의 「다시 실행할 것인가」라는 재시도 판단 (지식)에 사용될 뿐입니다.
• 컨덕터가 「수렴했다」고 신고한 집합 (finalize가 권위 게이트 = 심판 --claimed 역할을 수행)을 유일한 신뢰 입력으로 삼으면서, 머지 (merge) 직전에 각 유닛을 재검증합니다.

lying-conductor guard가 성립하는 이유는 바로 이 재검증이 있기 때문입니다. --claimed에 이름이 있더라도, 디스크 상에서 빨간색(재검증에서 테스트를 통과하지 못하거나 변조가 탐지됨)인 유닛은 머지가 거부되고 실패 엔벨로프 (failure envelope)로 떨어집니다. 따라서 컨덕터가 「수렴했다」고 속이거나 잘못 판단하더라도, 빨간색 유닛이 base에 들어가는 일은 없습니다. finalize가 반드시 재검증하기 때문에 check를 권고 수준에 머물게 할 수 있는 것입니다.

실패 이유는 타입 (type)으로 반환됩니다 (typed envelope). 컨덕터가 수렴을 주장하지 않은 유닛에는 타입이 지정된 이유가 첨부됩니다 (unsatisfiable = 본질적으로 생성 불가, budget-exhausted = 토큰 상한 도달, cap-exhausted = 수렴하지 못한 채 중단). 반면 error는 툴 자체의 재검증에 의한 판정 전용이며, 컨덕터 측에서 지정할 수 없습니다. 이는 가드를 속일 수 없도록 하기 위함입니다.

머지는 한 번에 하나씩만 수행됩니다. finalize는 진정한 합격 사례만을 slug 순서라는 결정론적인 순서로 하나씩 base에 통합합니다. 마지막으로 감사 추적 (audit trail)을 남기고, 타입이 지정된 엔벨로프를 반환하며 exit code로 마무리합니다.

• exit 0… claimed된 모든 유닛이 진정으로 수렴하여 머지된 상태. 컨덕터는 루프를 계속하며 다음 배치 (batch)로 진행합니다.
• exit 2… 어느 한 유닛이라도 실패했거나 머지가 실패한 상태. 컨덕터가 바통을 이어받아 halt-and-ask 단계에서 사람에게 문의합니다.

halt-and-ask는 자율 모드 (autonomous mode)에서도 실패하면 반드시 멈춰서 사람에게 문의하는 안전장치입니다. 병렬로 자율 실행되더라도 실패는 사람에게 돌아옵니다. 워커를 기동하는 것도 바통을 받는 것도 컨덕터 측이므로, swarm이 그 외부에서 멋대로 진행되는 일은 없습니다. 자율 모드나 첫 번째 Bolt의 취급은 별도 기사 「워킹 스켈레톤 (Walking Skeleton)」에서 다룹니다.

엔진은 상태를 읽기만 할 뿐, 컨덕터 (Conductor, 프롬프트)는 감사를 발행하지 않습니다. 따라서 swarm의 감사 이벤트 세트를 발행하는 것은 결정론적인 (Deterministic) 도구뿐입니다. aidlc-audit.ts의 등록 배열에서 실재를 확인할 수 있는 SWARM_* 이벤트는 6종입니다.

이벤트	발행처	의미
SWARM_STARTED	prepare	배치 시작. 배치마다 1회, 유닛 이름과 병렬 상한을 기록
SWARM_UNIT_CONVERGED	finalize	재검증 결과 녹색(Green)이며 변조되지 않은 유닛
SWARM_UNIT_FAILED	finalize	미신고, 신고했으나 적색(Red), 또는 변조됨. 타입이 지정된 이유를 병기
SWARM_BATON_RETURNED	finalize	실패 유닛마다 1행. 바톤이 사람에게 돌아감을 나타내는 표시
SWARM_COMPLETED	finalize	배치 종료. 수렴 수와 실패 수의 집계
SWARM_DEGRADED	prepare	AIDLC_USE_SWARM=1을 요청했으나 Workflow 도구가 부재하여, 병렬 서브 에이전트 (Parallel Sub-agent)로 격하된 기록

SWARM_DEGRADED가 나타내는 것은, 수렴 판정에 있어 실행 기반의 차이(인라인 Workflow인지 병렬 서브 에이전트인지)는 보이지 않지만, 그 격하 자체는 감사에 남긴다는 설계입니다. 레퍼리 (Referee)는 실행 기반의 차이를 수렴 결과에서 지우지만, 발생한 사실은 기록합니다. STATE_FORKED나 AUDIT_MERGED를 포함한 감사 이벤트 전체의 체계는 별도 기사 「상태와 감사」에서 다룹니다. Bolt나 code-generation 스테이지 자체의 위치 설정은 별도 기사 「공정과 에이전트」에서 다룹니다.

파일	내용
core/tools/aidlc-swarm.ts	수렴 레퍼리 본체. 서두의 주석이 설계의 정본 (THE SPLIT = 3자 분담, lying-conductor guard). prepare / check / finalize 3개 서브 커맨드, anti-tamper, 직렬 머지 (Serial Merge), 타입 지정 엔벨로프 (Typed Envelope)
core/tools/aidlc-worktree.ts	유닛별 격리 git worktree의 생성·머지·파기. .aidlc/worktrees/bolt-<slug>/, 형제 worktree로부터의 실행 거부
core/tools/aidlc-directive.ts	InvokeSwarmDirective (최소 형태·units + 임의의 repo). 엔진이 자율 모드 부여 하에 발행하고, 컨덕터가 이를 수용한다는 취지의 주석
core/tools/aidlc-bolt.ts	start --worktree (상태·감사·그래프를 fork), complete --merge (base로의 통합), release-merge (직렬 머지의 락 해제)
core/tools/aidlc-audit.ts	감사 이벤트 등록 배열. SWARM_STARTED / SWARM_UNIT_CONVERGED / SWARM_UNIT_FAILED / SWARM_BATON_RETURNED / SWARM_COMPLETED / SWARM_DEGRADED의 실재와 헤더

이전 기사: 도입 판단

목차: AI로 풀어보는 AI-DLC v2