모든 소프트웨어 프로젝트에는 잘못된 것을 만들고 있었다는 걸 깨닫는 순간이 있다. 메시지 라우터, 도구 실행 엔진, 대화 상태 관리자, 재시도 시스템을 만드는 데 몇 주를 보냈는데 — AI 제공업체가 이 모든 것을 단일 API 호출로, 당신보다 더 잘 처리한다는 걸 발견하는 순간.
그 순간이 NanoClaw의 아키텍처로 이어졌다. 전체 핵심 — WhatsApp 메시지를 도구 사용, 웹 브라우징, 파일 접근, 멀티턴 대화가 가능한 AI 에이전트 응답으로 변환하는 부분 — 은 대략 500줄의 TypeScript다. 50,000줄의 프레임워크를 임포트하는 500줄의 글루 코드가 아니다. 총 500줄, Anthropic의 Claude Agent SDK 위에 구축되었다.
소스 코드를 처음 읽는 개발자들의 반응은 보통 불신이고, 이어서 중요한 질문이 따른다: "나머지는 어디 있어?"
Claude Agent SDK가 실제로 하는 일
대부분의 AI 에이전트 프레임워크는 역사적으로 언어 모델 API가 상태 비저장이고 단순했기 때문에 존재한다. 프롬프트를 보내면 응답을 받았다. 도구 사용을 원하면 도구 실행 루프를 직접 만들어야 했다. 멀티턴 대화를 원하면 메시지 히스토리를 직접 관리해야 했다. 모델이 여러 도구 중에서 선택하게 하려면 라우팅 로직을 직접 만들어야 했다.
Claude Agent SDK는 이 방정식을 근본적으로 바꾼다. SDK는 단순히 Claude API를 호출하는 게 아니라 에이전트 루프를 실행한다. 시스템 프롬프트, 도구 세트, 사용자 메시지를 주면 SDK가 나머지를 모두 처리한다: Claude에 메시지를 보내고, 응답을 받고, Claude가 도구를 사용하려는지 확인하고, 도구를 실행하고, 결과를 Claude에 다시 보내고, Claude가 최종 응답을 생성할 때까지 반복한다. 대부분의 프레임워크가 수천 줄을 들여 구현하는 전체 도구 사용 루프가 단일 함수 호출이다.
이건 얇은 래퍼가 아니다. SDK는 스트리밍, 재시도 로직, 토큰 카운팅, 대화 상태를 처리한다. 여러 턴에 걸쳐 Claude와 도구 간의 주고받기를 관리하며, 도구 실행 실패와 컨텍스트 윈도우 제한 같은 엣지 케이스를 처리한다. NanoClaw가 구현할 필요 없는 복잡성은 빠진 게 아니라 — Anthropic 자체 엔지니어링 팀이 유지하는 잘 테스트된 SDK로 밀어 넣어진 것이다.
NanoClaw가 실제로 만드는 것
SDK가 에이전트 루프를 처리한다면, NanoClaw의 500줄은 실제로 무엇을 하는가? 답은 루프 주변의 모든 것 — API를 호출하는 것이 아닌 개인 AI 어시스턴트를 운영하는 데 특화된 부분이다.
첫 번째 책임은 채널 통합이다. NanoClaw는 Baileys 라이브러리를 통해 WhatsApp에 연결하고, 메시지를 수신하고, 적절한 에이전트 컨테이너로 라우팅한다. "누군가 WhatsApp에서 메시지를 보냈다"와 "에이전트가 이 메시지를 처리해야 한다" 사이의 접착제다. 복잡한 코드는 아니지만 필수적인 코드다 — 이것 없이는 에이전트가 사용자가 이미 있는 곳에 도달할 방법이 없다.
두 번째 책임은 컨테이너 오케스트레이션이다. 모든 에이전트 대화는 자체 Linux 컨테이너 안에서 실행된다 — macOS에서는 Apple Container, Linux에서는 Docker. NanoClaw는 컨테이너를 생성하고, 적절한 디렉토리를 마운트하고, stdin으로 시크릿을 전달하고, 응답을 수집한다. 이것이 손상된 에이전트가 샌드박스 밖의 어떤 것에도 접근하지 못하게 하는 보안 경계다. 컨테이너 라이프사이클 관리는 약 80줄의 코드지만, 그 80줄이 실제 인증 정보를 맡길 수 있는 에이전트와 그렇지 못한 에이전트의 차이다.
세 번째 책임은 영구 메모리다. NanoClaw는 대화, 그룹 상태, 예약된 작업의 SQLite 데이터베이스를 유지한다. 각 WhatsApp 그룹은 해당 그룹의 에이전트 장기 메모리 역할을 하는 자체 CLAUDE.md 파일을 갖는다. 메모리 시스템은 단순하다 — 의도적으로 — 메모리의 복잡한 부분(무엇이 관련 있는지, 무엇을 떠올릴지, 컨텍스트를 어떻게 사용할지 결정하는 것)은 Claude 자체가 처리하기 때문이다.
네 번째 책임은 예약된 작업이다. 사용자는 에이전트에게 특정 시간에 할 일을 요청할 수 있다 — "오후 3시에 알려줘" 또는 "매일 아침 이 웹사이트를 확인해줘." NanoClaw의 cron 유사 스케줄러가 적절한 시간에 에이전트 컨테이너를 트리거하는데, 이는 작지만 진정으로 유용한 기능으로 반응형 챗봇을 능동적 어시스턴트로 변환한다.
500줄이 중요한 이유
줄 수는 허영 지표가 아니다. 유지보수 표면, 버그 표면, 시스템을 이해하는 데 필요한 인지 부하의 직접적인 척도다.
NanoClaw의 핵심에서 버그가 나타나면, 그것이 존재할 수 있는 곳은 500줄이다. 개발자가 한 시간 안에 전체 코드베이스를 읽고 내려진 모든 결정을 이해할 수 있다. 50,000줄의 핵심 코드를 가진 프레임워크와 비교해보라 — 버그를 찾으려면 추상화를 탐색하고, 플러그인 시스템을 이해하고, 사용하지도 않을 수 있는 기능을 지원하기 위해 존재하는 간접 참조 계층을 통해 실행을 추적해야 한다.
보안 측면의 함의도 마찬가지로 구체적이다. 모든 코드 줄은 잠재적 취약점이다. NanoClaw의 500줄 핵심은 대부분의 프레임워크 설정 파서보다 작은 공격 표면을 가진다. 컨테이너 격리, stdin 시크릿 전달, 마운트 허용 목록 — 이 보안 기능들은 오후 한나절이면 완전히 감사할 수 있을 만큼 작은 코드로 구현되어 있다.
그리고 업그레이드 과정이 단순하다. Anthropic이 더 나은 도구 사용, 더 빠른 스트리밍, 새로운 기능을 갖춘 Claude Agent SDK 새 버전을 출시하면, NanoClaw는 단일 의존성을 업데이트하여 그 개선 사항을 얻는다. 새 SDK 기능을 노출하기 위해 업데이트해야 하는 프레임워크 추상화 계층이 없다. SDK가 곧 프레임워크다.
만들지 않는 철학
NanoClaw 아키텍처에서 가장 어려운 부분은 만드는 것이 아니라 무엇을 만들지 않을지 결정하는 것이었다. 커스텀 도구 실행 엔진, 정교한 메모리 검색 시스템, 멀티 프로바이더 추상화 계층, 플러그인 마켓플레이스를 추가하고 싶은 유혹 — 이 모든 것은 다른 프레임워크가 만든 것이고, NanoClaw가 의도적으로 갖지 않는 것이다.
이 기능들 각각은 수천 줄의 코드, 수십 개의 잠재적 버그, 수 주의 유지보수 부담을 추가할 것이다. 그리고 각각은 Claude Agent SDK가 이미 제공하거나 Claude 자체가 수작업 코드보다 더 잘 처리하는 기능을 중복시킬 것이다.
결과는 흥미로운 결정이 구현이 아닌 아키텍처에 있는 프로젝트다. 컨테이너를 어떻게 격리할 것인가? 시크릿을 어떻게 전달할 것인가? 메모리를 그룹별로 어떻게 범위 지정할 것인가? 이것이 개인 AI 어시스턴트에 중요한 질문이며, NanoClaw의 500줄이 답하는 데 전념하는 질문이다.
다음에 AI 에이전트 프레임워크를 평가할 때, 기능을 세지 말고 줄 수를 세라. 가장 적은 줄을 가진 프레임워크가 가장 능력이 떨어지는 게 아니다 — AI 제공업체에게 무거운 작업을 맡길 만큼 문제를 잘 이해한 프레임워크일 수 있다.