본 기사의 위치— 본 기사는 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는 이를 '삼자 분담'이라는 설계로 안전한 방향으로 기울여 놓았습니다. 컨덕터(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).

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

워커(Worker)를 기동하는 계층이 왜 도구(Tool) 안에 없을까요? 도구의 실체인 bun의 서브 프로세스는 Task 호출을 발행할 수 없기 때문입니다. 따라서 "움직이는 지식(Knowledge)"은 컨덕터(Conductor)에 두고, 결정론적(Deterministic)이어야 하는 부분만 도구에 남깁니다. 도구는 상태를 가지지 않는 세 가지 서브 커맨드(prepare / check / finalize)만을 공개합니다.

격리된 worktree

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

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

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

check는 조언, finalize는 확정

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

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

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)에서도 실패할 경우 반드시 멈춰서 사람에게 문의하는 안전밸브입니다. 병렬로 자율 실행 중이더라도, 실패는 사람에게 돌아갑니다. 워커(worker)를 기동하는 것도 바톤(baton)을 이어받는 것도 컨덕터(conductor) 측이므로, swarm이 그 외부에서 마음대로 진행되는 일은 없습니다. 자율 모드나 최초의 Bolt 처리는 별도 기사 「Walking Skeleton」에서 다룹니다.

감사가 남기는 것

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

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

참조 원본

관련 기사

이전 기사: 도입 판단

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

Discussion