로컬 LLM 에이전트가 알아서 코드를 짜고 배포까지 해주는 세상입니다. 하지만 정작 이를 실행하는 인프라가 엉망이면 아무 소용 없습니다. Archon 프레임워크를 쓰다 보면 YAML 파일의 노드 의존성이 꼬여 무한 루프에 빠지거나, loader.ts가 실행을 거부하는 상황을 자주 마주칩니다. 모델의 추론 능력보다 중요한 건 결국 이 비결정적인 엔진을 담아낼 그릇, 즉 하네스 엔지니어링의 안정성입니다.
YAML 앵커로 중복을 제거하고 논리적 고립 막기
Archon의 워크플로우는 명확한 입력과 출력이 정의된 유향 비순환 그래프(DAG)여야 합니다. 무턱대고 노드를 연결하다 보면 설계 단계부터 논리적 결함이 생기기 마련입니다. 특히 비슷한 설정을 노드마다 복사해서 붙여넣는 습관은 휴먼 에러의 주범입니다.
- 공통 설정 구조화: YAML 상단에
&common_config앵커를 선언하고 모델 프로바이더나 기본 인스트럭션을 정의하세요. 각 노드에서는<<: *common_config를 사용해 이를 상속받으면 설정 파일 길이를 30% 넘게 줄일 수 있습니다. - 루프 로직의 분리: 단일 DAG 내부에서 뒤로 돌아가는 선(Back-edge)을 만들지 마세요. 반복이 필요하다면 Archon의
loop_until프리미티브를 써서 별도의 실행 단위로 떼어내야 시스템이 멈추지 않습니다. - 출력 데이터의 규격화:
prompt타입 노드에 Zod 스키마를 연결하고output_format: { type: 'object' }를 강제하세요. AI의 답변이 정형화되어야$nodeId.output참조 오류를 막고 워크플로우 성공률을 25% 이상 끌어올립니다.
M4 칩 환경의 디스크 병목을 해결하는 자동 정리 파이프라인
에이전트가 독립적으로 작업할 수 있게 Git 워크트리를 생성하는 방식은 깔끔하지만 대가가 따릅니다. node_modules 같은 무거운 폴더가 복제될 때마다 수십 기가바이트의 스토리지가 사라집니다. 통합 메모리를 쓰는 M4 맥북에서는 디스크 스왑이 발생하는 순간 전체 시스템이 눈에 띄게 느려집니다.
- 워크트리 즉시 삭제: 워크플로우 마지막 단계에
git worktree remove를 수행하는 쉘 스크립트 노드를 반드시 배치하세요. 필요한 로그와 Diff 파일만$ARTIFACTS_DIR로 옮기고 나머지는 가차 없이 지워야 합니다. - 리소스 스로틀링: Docker Compose에서 동시에 돌아가는 워크트리 개수를 CPU 코어 수의 50% 수준으로 제한하세요. 무조건 많이 띄운다고 능사가 아닙니다.
- 파일 시스템 최적화: Docker Desktop 설정에서 VirtioFS를 활성화하세요. 호스트와 컨테이너 사이의 I/O 속도가 2배 이상 빨라지며, 에이전트가
npm install을 수행할 때 발생하는 지연 시간을 획기적으로 줄여줍니다.
컨테이너 점유율 지표를 활용한 노드 단위 트러블슈팅
에이전트가 갑자기 헛소리를 하거나 도구 호출을 틀린다면 컨텍스트 윈도우 점유율()을 의심해야 합니다. 프롬프트와 히스토리가 최대 토큰의 40%를 넘어서는 이른바 덤 존(Dumb Zone)에 들어가면 모델은 급격히 멍청해집니다.
이 지표가 임계치를 넘으면 전체 시스템을 손보는 대신 문제가 된 노드만 골라내서 수술해야 합니다.
- 단위 테스트 자동화: DAG 각 노드에
verification속성을 넣어 실행 직후 유닛 테스트를 돌리세요. 테스트가 깨지면 해당 노드의 인스트럭션만 이전 버전으로 롤백하거나 프롬프트를 즉시 교체하는 자가 수정 루프를 짜야 합니다. - 압축 파이프라인 가동: 상태를 유지하기 위해 Snip이나 Microcompact 같은 5단계 압축 로직을 적용하세요. 불필요한 컨텍스트를 쳐내는 것만으로도 검수 시간을 40% 절감하고 코드 품질을 일정하게 유지할 수 있습니다.
하네스 엔지니어링은 AI를 잘 쓰는 기술이 아니라, 통제 불가능한 LLM을 소프트웨어 공학의 영역으로 끌어오는 일입니다. 인프라가 탄탄해야 에이전트도 제 실력을 발휘합니다.
