Swift로 코딩 에이전트를 밑바닥부터 만들어보기

AI 코딩 에이전트, 직접 만들어보면 어떨까?

요즘 Claude Code, GitHub Copilot, Cursor 같은 AI 코딩 에이전트가 개발자 워크플로우에 빠르게 자리잡고 있는데요, 이런 도구들을 매일 쓰다 보면 한 번쯤 궁금해지잖아요. "이거 내부적으로 어떻게 동작하는 거지?" 그 궁금증에 대한 답을 직접 코드로 보여주는 프로젝트가 있어서 소개해요.

ivan-magda라는 개발자가 Swift로 코딩 에이전트를 밑바닥부터 만든 오픈소스 프로젝트 "swift-claude-code"를 공개했는데요, Anthropic의 Claude API를 활용해서 터미널에서 동작하는 코딩 에이전트를 구현한 거예요. 특이한 점은 Python이나 TypeScript가 아니라 Swift로 만들었다는 거예요.

코딩 에이전트의 구조를 뜯어보면

코딩 에이전트가 뭔지부터 간단히 짚어볼게요. 일반적인 AI 챗봇은 질문하면 답변을 텍스트로 주는 데서 끝나잖아요. 에이전트는 여기서 한 발 더 나가서, AI가 직접 파일을 읽고, 코드를 수정하고, 터미널 명령어를 실행하는 거예요. 이걸 가능하게 하는 핵심 개념이 "Tool Use(도구 사용)"인데요, AI 모델한테 "너는 이런 도구들을 쓸 수 있어"라고 알려주면, 모델이 상황에 맞는 도구를 골라서 호출하는 방식이에요.

이 프로젝트의 구조를 보면 코딩 에이전트의 기본 아키텍처가 어떻게 생겼는지 잘 보여요. 크게 세 가지 핵심 요소로 나눌 수 있어요.

첫째, 대화 루프(Conversation Loop)예요. 사용자의 입력을 받고, Claude API에 보내고, 응답을 처리하는 기본 루프인데요, 여기서 중요한 건 단순히 한 번 주고받는 게 아니라 "에이전트 루프"라는 걸 돌린다는 거예요. AI가 도구를 호출하면 그 결과를 다시 AI에게 돌려주고, AI가 더 이상 도구 호출이 필요 없다고 판단할 때까지 이 루프를 반복하는 거예요.

둘째, 도구 정의(Tool Definitions)예요. 이 프로젝트에서는 파일 읽기, 파일 쓰기, 셸 명령어 실행, 파일 검색 같은 도구들을 정의해놨어요. 각 도구는 이름, 설명, 파라미터 스키마를 가지고 있고, Claude API에 이 정보를 함께 보내면 모델이 적절한 도구를 선택해서 JSON 형태로 호출 요청을 보내는 구조예요.

셋째, 샌드박싱과 안전장치예요. AI가 아무 명령어나 실행할 수 있으면 위험하잖아요. 그래서 실행 전에 사용자 확인을 받는다든지, 특정 디렉토리 밖으로는 파일 접근을 제한한다든지 하는 안전장치가 들어가요.

왜 Swift로 만들었을까?

AI 관련 프로젝트는 대부분 Python이나 TypeScript로 만들어지잖아요. 라이브러리 생태계가 잘 갖춰져 있으니까요. 그런데 이 프로젝트가 Swift를 선택한 건 나름의 의미가 있어요.

일단 Swift는 Apple 생태계의 주력 언어이면서도 AI/LLM 도구 쪽에서는 상대적으로 존재감이 약한 편이에요. 그래서 Swift 개발자들이 AI 에이전트를 만들려면 참고할 만한 레퍼런스가 별로 없었거든요. 이 프로젝트가 그 빈 공간을 채워주는 셈이에요.

또 Swift의 강타입 시스템과 async/await 동시성 모델이 에이전트 개발에 꽤 잘 맞아요. 도구 호출이나 API 통신 같은 비동기 작업이 많은데, Swift의 structured concurrency가 이런 흐름을 깔끔하게 표현할 수 있게 해주거든요. 타입 안전성도 높아서 도구 파라미터를 다룰 때 런타임 에러를 줄일 수 있고요.

업계 맥락: 에이전트 프레임워크 춘추전국시대

지금 AI 에이전트 개발 프레임워크 시장은 정말 치열해요. Python 쪽에는 LangChain, CrewAI, AutoGen 같은 프레임워크들이 있고, Anthropic도 자체 Agent SDK를 제공하고 있어요. TypeScript 쪽에는 Vercel AI SDK가 있고요.

이 프로젝트는 그런 대형 프레임워크와 직접 경쟁하는 게 아니라, 교육적인 가치에 더 초점이 맞춰져 있어요. "코딩 에이전트가 내부적으로 어떻게 돌아가는지 이해하고 싶다면, 이 코드를 읽어보세요"라는 포지션이죠. 실제로 코드베이스가 비교적 작고 읽기 쉽게 구성되어 있어서 학습용으로 괜찮아요.

한국 개발자에게 주는 시사점

Swift 개발자이면서 AI에 관심 있는 분이라면 바로 클론 받아서 돌려볼 만해요. 하지만 Swift 개발자가 아니더라도 이 프로젝트에서 배울 게 있어요. 코딩 에이전트의 핵심 패턴인 에이전트 루프, 도구 정의, 컨텍스트 관리를 비교적 작은 코드베이스에서 한눈에 볼 수 있거든요. 자기가 쓰는 언어로 비슷한 걸 만들어보고 싶을 때 좋은 참고가 돼요.

특히 요즘 AI 에이전트를 제품에 통합하는 수요가 많아지고 있잖아요. 고객 지원 챗봇에 도구 사용 기능을 추가한다든지, 내부 업무 자동화 에이전트를 만든다든지. 이런 작업을 할 때 에이전트 루프가 어떻게 동작하는지 기본 원리를 알고 있으면 프레임워크를 쓸 때도 훨씬 수월해요.

핵심 정리

Swift로 만든 오픈소스 코딩 에이전트 프로젝트가, AI 에이전트의 내부 동작 원리를 코드 레벨에서 이해할 수 있는 좋은 학습 자료가 돼요.

여러분은 AI 코딩 에이전트를 어떻게 활용하고 계신가요? 직접 에이전트를 만들어본 경험이 있다면 어떤 언어와 구조로 만드셨나요?