대규모 코드베이스 마이그레이션은 타이핑(typing)의 문제가 아닙니다. 그것은 분산 상태 머신(distributed state machine)의 문제입니다.

제가 이 migration-orchestration-skill에서 제안한 워크플로우와 같이, LLM을 사용하여 다단계, 다중 PR 리팩토링을 실행하려고 시도할 때, 당신은 단순히 코드를 작성하는 것이 아닙니다. 당신은 분산 시스템(distributed system)을 인스턴스화하고 있는 것입니다. 당신의 오케스트레이터(orchestrator)는 제어 평면(control plane)이며, 당신의 LLM 하위 에이전트(subagents)는 비동기 워커 노드(asynchronous worker nodes)이고, 로컬 저장소(local repository)는 공유 데이터베이스(shared database)입니다.

대부분의 AI 워크플로우 문서는 에이전트가 지침을 깔끔하게 읽고, 파일을 수정하며, 마크다운(Markdown) 목록을 체크하는 '해피 패스(happy path)'를 가정합니다. 이는 가장 순진한 형태의 화이트보드 아키텍처(whiteboard architecture)입니다. 현실에서 에이전트는 환각(hallucinate)을 일으키고, Git은 잠기며, 테스트 스위트(test suites)는 멈추고, 상태 파일(state files)은 손상됩니다. 실제로 마이그레이션을 완료하는 오케스트레이터를 구축하려면, 우리의 아키텍처를 환경의 기계적 현실에 맞춰 정렬해야 합니다.

컨텍스트(Context)와 제약 조건(Constraint)

핵심 비즈니스 요구사항은 동시적인 인간의 기능 개발을 차단하지 않으면서, 거대한 아키텍처 변경(예: 모놀리스를 분할된 마이크로 데이터베이스로 마이그레이션하거나 React 클래스를 훅(hooks)으로 재작성하는 것)을 안전하게 순차적으로 실행하고, 검증하며, 커밋하는 것입니다.

근본적인 분산 시스템(distributed systems)의 골칫거리는 무엇일까요? 당신은 엄격하게 순차적이고 로컬에서 잠긴 상태 저장소(local filesystem 및 Git)에 대해 동시 변이(concurrent mutations)를 시도하는 비동기적이고 비결정론적인 컴퓨팅 노드(LLM 에이전트)를 조정하고 있다는 점입니다. 엄격한 경계(boundaries)를 설계하지 않으면, 그 결과는 손상된 코드, 폭발한 컨텍스트 윈도우(context windows), 그리고 수천 달러의 낭비되는 API 토큰으로 이어집니다.

순진한 접근 방식 (MVP)

표준적인 MVP 구현 방식은 마이그레이션을 개별 단계(S1..Sn)로 나누고, 의존성 그래프(dependency graph)를 정의하며, "서로 관련 없는 파일(disjoint files)"을 다루는 모든 단계에 대해 오케스트레이터(orchestrator)가 병렬적인 서브 에이전트(subagents)를 생성하도록 지시합니다. 마이그레이션의 상태는 에이전트들이 사람이 읽을 수 있는 <slug>-progress.md 파일을 읽고 업데이트함으로써 추적됩니다. 에이전트가 테스트 스위트(test suite)를 통과하지 못하면, 테스트를 통과할 때까지 worker → reviewer → fix 루프에 진입합니다.

실제 환경의 부하(load) 상황에서는 이 방식이 거의 즉시 붕괴됩니다:

• 상태 오염 (State Corruption): 두 에이전트가 동시에 단계를 완료하고 progress.md 파일을 맹목적으로 덮어써서, 서로의 상태 업데이트 내용을 지워버립니다.
• 천둥 치는 들소 문제 (The Thundering Herd): 여러 에이전트가 npm install 또는 cargo build를 병렬로 실행하려고 시도합니다. 이들은 I/O를 고갈시키고, 메모리를 과도하게 사용(thrash)하며, 로컬 머신을 다운시킵니다.
• 잠금 경합 (Lock Contention): 동시적인 git 작업이 .git/index.lock 충돌을 유발하여, 오케스트레이터를 완전히 중단시키는 처리되지 않은 치명적 오류(fatal errors)를 발생시킵니다.

아키텍처의 진화 (반복적 개선)

이를 해결하기 위해서는 파이프라인을 해체하고 모든 실패 영역(failure domain)에 기계적 공감(mechanical sympathy)을 적용해야 합니다.

1. 상태 관리 및 합의 (State Management & Consensus)

• 함정 (The Pitfall): 단순한 Markdown 파일(<slug>-progress.md)을 동시성 데이터 저장소 (concurrent data store)로 사용하는 것입니다. 여러 에이전트가 파일을 수정할 때 경쟁 상태 (race conditions), 팬텀 읽기 (phantom reads), 그리고 업데이트 유실 (lost updates)이 발생할 것을 보장하는 꼴입니다.
• 해결책 (The Fix): 뮤텍스 (mutex)를 도입하십시오. 에이전트가 진행 상황 파일을 읽거나 수정하기 전에 반드시 로컬 파일 잠금 (local file lock)을 획득하도록 강제해야 합니다.
• 숨겨진 함정 (The Hidden Pitfall): 로컬 OS의 파일 잠금은 매우 취약하기로 악명이 높습니다. 만약 에이전트 프로세스가 세그멘테이션 결함 (segfault)을 일으키거나, 메모리 부족 (OOM)이 발생하거나, 사용자가 터미널을 강제로 종료(Ctrl+C)하면 잠금이 해제되지 않습니다. 이 경우 마이그레이션은 영구적인 데드락 (deadlock) 상태에 빠집니다.
• 결정적인 해결책 (The Definitive Fix): 시스템 상태를 위해 낙관적 동시성 제어 (Optimistic Concurrency Control, OCC)와 결합된 추가 전용 JSONL 원장 (Append-Only JSONL Ledger) 방식으로 전환하십시오. 에이전트는 과거의 라인을 수정하지 않고, 새로운 상태 이벤트인 {"step": "S2", "status": "passed", "sha": "abc1234", "timestamp": 1719154980}를 추가(append)만 합니다. Markdown 파일은 오직 오케스트레이터가 인간의 소비를 위해 생성하는, 구체화된 읽기 전용 프로젝션 (materialized, read-only projection)이어야 합니다. 만약 에이전트가 예상한 이전 상태가 최신 원장 시퀀스와 일치하지 않으면, 추가 작업은 거부되며 에이전트는 이를 조정 (reconcile)해야 합니다.

2. 병렬성 및 엣지 현실 (Parallelism & The Edge Reality)

• 함정 (The Pitfall): "서로 다른 파일"(예: 에이전트 A는 auth.ts를 수정하고, 에이전트 B는 db.ts를 수정함)을 다룬다는 가정하에 병렬 단계를 실행하면 충돌을 방지할 수 있다고 생각하는 것입니다.
• 해결책 (The Fix): Git 작업에 대해 전역 큐 (global queue)를 구현하여 비관적 잠금 (pessimistic locking)을 효과적으로 사용합니다. 에이전트들은 파일을 동시에 작성할 수 있지만, git add 및 git commit을 실행할 때는 줄을 서서 기다려야 합니다.
• 숨겨진 함정 (The Hidden Pitfall): 이는 오케스트레이터 (orchestrator)의 처리량 (throughput)을 파괴하고 치명적인 메모리 버퍼링 (memory buffering)을 유발합니다. 에이전트들은 Git 잠금 (lock)을 기다리는 동안 대기 중인 디프 (diffs)와 LLM 컨텍스트 (context)를 메모리에 유지해야만 합니다. 이는 메모리 사용량 (memory footprint)을 팽창시켜, 결국 언어 런타임 (language runtime)의 가비지 컬렉터 (garbage collector)가 과부하되어 프로세스가 충돌하게 만듭니다.
• 결정적인 해결책 (The Definitive Fix): Git Worktrees를 사용하십시오. 오케스트레이터는 모든 병렬 단계에 대해 물리적으로 격리된 디렉토리(git worktree add ../S2-branch)를 할당해야 합니다. 이를 통해 각 에이전트는 완전히 격리된 인덱스 (index), 작업 디렉토리 (working directory), 그리고 실행 환경 (execution environment)을 갖게 됩니다. 병렬성은 더 이상 환상이 아니며, OS 레벨의 파일 시스템 경계에 의해 기계적으로 강제됩니다.

3. 포이즌 필 (The Poison Pill) 및 운영상의 사각지대 (Operational Blindspots)

3. 포이즌 필 (The Poison Pill) 및 운영상의 사각지대 (Operational Blindspots)

• 함정(The Pitfall): worker → reviewer → fix 루프는 LLM이 충분히 노력하기만 하면 모든 코드 문제가 해결 가능하다고 가정합니다. 이는 무한 루프인 while(true)처럼 작동합니다.
• 해결책(The Fix): 엄격한 재시도 카운터(예: max_attempts=3)를 구현합니다. 에이전트가 실패하면 해당 단계를 blocked로 표시합니다.
• 숨겨진 함정(The Hidden Pitfall): 충돌하거나, 속도 제한에 걸리거나, 환각을 일으키는 에이전트는 보고하기 전에 멈출 수 있습니다. 이 경우 원장(ledger)에는 해당 단계가 영구적으로 in_progress로 표시됩니다. DAG의 다운스트림 단계들이 이 노드에 의존하기 때문에, 시스템은 누락된 끝부분을 기다리며 순서가 맞지 않는 시퀀스를 무한정 버퍼링합니다. 이는 전형적인 좀비 상태입니다.
• 확정적 해결책(The Definitive Fix): 임대 기반 실행 및 데드 레터 큐 (Dead Letter Queues, DLQ). 에이전트가 단계를 주장할 때, 하드 TTL(Time To Live)을 가진 임대를 원장에 기록합니다(예: expires_at: 1719155980). 오케스트레이터가 만료된 임대를 감지하면, 해당 단계는 강제로 취소되고 포이즌 필로 표시되며 DLQ로 전송됩니다. 오케스트레이터는 의존하는 노드의 실행을 중단시키고 인간 운영자에게 알림(page)을 보냅니다. 엄격한 의존성 체인은 깨진 링크를 건너뛸 수 없으며, 안전하고 예측 가능하게 멈춰야 합니다.

시사점 (The Takeaway)

화이트보드에 의존성 상자 그리는 것은 쉽습니다. 하지만 이를 물리적 제약 조건 하에서 신뢰성 있게 실행하는 것은 스태프 레벨(Staff-level)의 엔지니어링입니다.

LLM 오케스트레이션 프레임워크 역시 분산 시스템의 물리 법칙을 예외로 할 수 없습니다. 파일 잠금 경합(File lock contention), 순서가 맞지 않는 실행, 파싱할 수 없는 AST(Abstract Syntax Trees), 프로세스 충돌은 보장된 일입니다. 코드베이스 마이그레이션을 시퀀싱하기 위해 '행복한 경로(happy path)' 프롬프트에 의존한다면 시스템은 실패할 것입니다. 그러나 불변의 원장(immutable ledgers), 격리된 실행 환경, 엄격한 TTL 경계를 갖추어 AI 파이프라인을 설계한다면, 취약한 프롬프트 체인을 작성하는 수준에서 벗어나 탄력적이고 프로덕션 등급의 마이그레이션 머신을 운영하게 됩니다. 진정한 엔지니어링은 시스템이 모든 것이 잘 될 때 어떻게 작동하는지가 아니라, 실패를 처리하는 방식에서 발견됩니다.