iOS 개발자가 Swift로 Claude Code 스타일의 코딩 에이전트를 9단계에 걸쳐 구현하며 동시성 버그가 AI 로직 버그보다 훨씬 복잡함을 발견

Context

Claude Code와 같은 코딩 에이전트의 내부 아키텍처를 이해하고 싶었으나, 기존 문서는 API 수준의 정보만 제공했다. 에이전트 설계가 얼마나 복잡해야 효과적인지, 실제로는 어떤 부분이 버그를 유발하는지 불명확했다.

Technical Solution

• Swift 6.2의 엄격한 동시성(strict concurrency) 활성화로 데이터 레이스를 컴파일 타임에 감지: 런타임 크래시 방지
• 2개 타겟 아키텍처 도입: Core 라이브러리(에이전트 로직 + 테스트 가능) + CLI 실행파일(REPL 진입점)
• 9단계 진화 설계 적용: 파일 연산 → 셀 실행 → 서브에이전트 → 컨텍스트 압축 → 작업 DAG → 백그라운드 작업 → 스킬 로딩, 각 단계마다 기존 구조 변경 없음
• Process 생성 시 stdout/stderr 버퍼 관리: waitUntilExit() 호출 전 데이터 읽음으로써 파이프 버퍼 오버플로우로 인한 프로세스 행(hang) 방지
• Linux와 macOS의 SIGTERM 처리 차이 흡수: 자식 프로세스의 신호 처리 방식을 플랫폼별로 분기 처리
• AsyncHTTPClient 직접 사용 + 원시 HTTP 요청: Anthropic API SDK 제외로 의존성 최소화

Key Takeaway

코딩 에이전트의 효과성은 복잡한 오케스트레이션보다 적은 수의 우수한 도구와 긴밀한 루프 설계에서 나온다. 에이전트 루프 자체는 약 20줄 코드로 매우 단순하며, 실제 어려움은 AI 로직이 아니라 언어 수준의 동시성 관리와 저수준 프로세스 I/O 다루기에 있다.