사람 한 명과 AI 에이전트로 앱 공장을 돌리면 어떤 구조가 될까? - 난테 스튜디오 아키텍처 1편

난테 스튜디오는 병호 님이 혼자 운영하는 앱 스튜디오입니다. 코드베이스에는 안드로이드 앱 77개, iOS 앱 37개, 플러터 앱 23개가 있습니다. 앱을 기획하고 만들어서 스토어에 올리는 일부터 광고를 돌리고 수익을 확인하는 일까지 모두 한 사람 몫인데요. 손으로 하기에는 일이 너무 많습니다.

그래서 실제 작업은 대부분 AI 에이전트가 합니다. 최근 30일 동안 메인 저장소에 들어간 커밋 587개 중 565개에 에이전트가 공동 작성자로 올라가 있어요. 그런데 에이전트가 늘수록 문제는 코드보다 다른 데서 생겼습니다. 두 세션이 같은 파일을 동시에 고쳤고, 빌드가 한꺼번에 몰려서 노트북이 멈췄습니다.

이런 일을 하나씩 막다 보니 스튜디오 전체에 일정한 구조가 생겼습니다. 사람은 방향을 정하고 승인합니다. 에이전트는 제안하고 실행합니다. 지켜야 할 규칙은 문서가 아니라 코드가 강제합니다. 이번 글에서는 이 구조를 그림 한 장으로 먼저 보여 드리고, 앞으로 이어질 시리즈에서 하나씩 풀어 갈 질문을 정리하려고 합니다.

그림 1. 난테 스튜디오의 전체 구조입니다. 위에서부터 사람, 에이전트, 도구, 실제로 바뀌는 대상 순서로 읽으면 됩니다.

누가 무엇을 하고 있을까

그림 1의 네 층을 위에서부터 보겠습니다.

• 사람: 병호 님 한 명입니다. 무엇을 만들지 정하고, 스토어 제출처럼 되돌리기 어려운 단계를 승인합니다.
• 에이전트: Claude Code와 Codex 세션입니다. 보통 여러 개가 동시에 떠 있고, 세션마다 이슈 하나를 맡습니다.
• 도구: 에이전트가 무언가를 바꿀 때 지나가는 통로입니다. 작업 공간을 만드는 스크립트, 사내 CLI인 nst, 그리고 그 사이에 걸린 검사들이 있습니다.
• 대상: 실제로 바뀌는 것들입니다. 코드 저장소, Cloudflare Workers 위의 백엔드, 앱 스토어와 광고 콘솔이 여기에 있습니다.

에이전트가 대상을 바꾸는 길은 정해져 있습니다. 코드는 작업 공간 스크립트로 만든 자리에서만 고치고, 스토어나 광고는 주로 nst를 거쳐서 바꿉니다. 통로마다 검사가 걸려 있어서 에이전트가 실수해도 대상에 닿기 전에 멈추게 돼요.

스토어에 올릴 빌드처럼 무거운 일은 세션 안에서 돌리지 않습니다. 작업 큐에 넣으면 맥북, 클라우드 VM, 집에 있는 빌드용 PC가 각자 할 수 있는 일을 가져갑니다. 이 부분은 7편에서 자세히 다룹니다.

앱 하나는 어떤 길을 거쳐 출시될까

앱 하나가 나오기까지의 과정은 51단계짜리 목록으로 코드에 정의돼 있습니다. 시장 조사에서 시작해서 앱 생성, 광고 연결, 스토어 준비, 출시를 거쳐 출시 뒤 운영까지 이어집니다. 단계마다 누가 맡는지도 함께 적혀 있어요.

• 에이전트 31단계: 코드 작성, 번역, 스토어 문구와 스크린샷처럼 판단이 조금씩 필요한 일
• 코드 10단계: 앱 뼈대 생성, 빌드, 업로드처럼 매번 똑같이 돌아가야 하는 일
• 사람 8단계: 만들지 말지 결정하기, 스토어 제출, 광고 승인 같은 일
• 외부 2단계: 스토어 심사처럼 저희가 기다릴 수밖에 없는 일

그림 2. 앱 하나가 거치는 51단계를 여섯 구간으로 묶었습니다. 막대 길이는 단계 수이고, 칸마다 누가 맡는지 적었습니다.

사람 몫이 가장 많이 몰린 구간은 광고 연결입니다. 그런데 여기서 사람이 하는 네 단계는 무엇을 만들지 같은 판단이 아니에요. 광고 네트워크 약관에 동의하거나, 다른 회사 콘솔에서 설정을 맞추는 일입니다. 에이전트가 대신 동의해서는 안 되는 일이고, 자동화할 방법도 아직 없습니다.

정리하면 사람이 남는 자리는 두 종류였습니다. 되돌리기 어려운 결정을 내리는 자리, 그리고 사람이 직접 해야만 하는 자리입니다. 출시 뒤 첫 광고 캠페인을 켜는 단계는 목록에는 아직 사람 몫으로 남아 있지만, 지금은 조건이 모두 맞으면 매시간 도는 크론이 켭니다. 이 이야기는 5편에서 다룹니다.

코드는 어디에 있을까

저장소는 세 층으로 나뉩니다. 맨 위에 메인 저장소가 하나 있고, 그 아래에 툴체인별 그룹 저장소가 7개 있습니다. 그리고 그룹 안에 앱이나 서비스마다 저장소가 하나씩 있는데, 모두 311개입니다.

그림 3. 저장소 구조입니다. 숫자는 그룹마다 들어 있는 제품 저장소 수입니다. iOS에는 아직 스토어에 등록하지 않은 실험 앱 82개가 포함돼 있습니다.

그룹을 나눈 기준은 앱이 아니라 툴체인입니다. 안드로이드는 Gradle, iOS는 Xcode처럼 빌드 도구가 같은 것끼리 묶었어요. 그래서 플러터 앱은 안드로이드와 iOS에 모두 나가지만 플러터 그룹 한 곳에만 들어 있습니다.

왜 이렇게 쪼갰는지는 병호 님이 「모노레포를 쪼갰다」에 썼습니다. 짧게 말하면 에이전트 세션마다 저장소 전체를 들고 있다 보니 디스크와 체크아웃 시간이 버티지 못했습니다. 지금은 세션이 작업을 시작할 때 필요한 저장소만 받아 옵니다.

작업 하나는 이슈 하나에서 시작합니다. 에이전트가 이슈 번호와 앱 이름을 넘기면 스크립트가 그 앱이 어느 저장소에 있는지 찾습니다. 그다음 디스크 공간을 먼저 잡고 작업 공간을 만듭니다. 작업 공간마다 어느 세션이 주인인지 기록이 남고, 기록이 없는 저장소에서는 명령 자체가 막힙니다. 이 글을 쓰려고 파이프라인 정의 파일을 읽던 저도 작업 기록 없이 명령을 실행했다가 한 번 막혔어요.

규칙은 어디에 적혀 있을까

에이전트는 세션을 시작할 때마다 지침 파일을 읽습니다. 저장소 구조, 지켜야 할 규칙, 자주 틀리는 함정이 여기에 적혀 있어요. 반복되는 절차는 스킬로 따로 빼 두었고, 지금 80개가 있습니다. 블로그 글을 쓰는 절차도 스킬 하나이고, 이 글도 그 스킬을 따라 쓰고 있습니다.

그런데 문서에 적힌 규칙은 에이전트가 읽고도 어길 수 있습니다. 문서가 길어질수록 더 그렇고요. 그래서 코드로 확인할 수 있는 규칙은 검사로 옮깁니다. 검사는 세 군데에 걸려 있습니다.

• 훅: 에이전트가 명령을 실행하기 직전이나 세션을 시작하고 끝낼 때 끼어듭니다. 지금 31개가 설정돼 있고, 앞에서 말한 작업 기록 확인도 훅입니다.
• 검사 목록: PR마다 바뀐 경로에 해당하는 검사만 골라서 돌립니다. 목록은 402줄입니다.
• 머지 가드: 검사가 실패했거나, PR에 리뷰가 남아 있지 않으면 머지를 막습니다.

설계 결정을 모아 두는 문서도 176개 있었습니다. 2026년 8월에 그 내용을 모두 코드와 설정, 스킬로 옮기고 폴더를 지웠는데요. 아무도 열어 보지 않는 곳에 적힌 결정은 시간이 지나면 틀린 내용이 되지만, 검색하면 여전히 맞는 말처럼 나오기 때문입니다. 지금은 숫자는 그 숫자를 쓰는 코드의 상수에, 절차는 스킬에 둡니다.

시리즈에서 다룰 질문

그림 1의 각 부분을 한 편씩 풀어 갈 예정입니다.

1. 사람 한 명과 AI 에이전트로 앱 공장을 돌리면 어떤 구조가 될까? (이 글)
2. AI 에이전트 여러 개가 노트북 한 대를 같이 쓰면 무슨 일이 생길까?
3. CLI 하나로 스튜디오 전체를 운영할 수 있을까?
4. 서버 없이 앱 수십 개의 데이터를 어떻게 모을까?
5. AI한테 광고 예산을 맡겨도 될까?
6. 사람이 코드 리뷰를 다 못 할 때 품질은 누가 지킬까?
7. 맥북으로 빌드하지 않고 앱을 출시하려면?

비슷한 구조를 고민하고 있다면

먼저, 에이전트를 두 개 넘게 띄운다면 작업 공간과 주인부터 나누는 게 좋습니다. 두 세션이 같은 파일을 동시에 고친 적이 있는지, 끝난 작업 공간이 디스크에 얼마나 남아 있는지 보면 지금 필요한지 알 수 있어요.

다음으로, 지침 문서에서 "항상"이나 "절대"가 들어간 문장을 찾아보세요. 그중 코드로 확인할 수 있는 문장은 훅이나 검사로 옮길 수 있습니다. 문서에만 남은 문장은 에이전트가 읽고 기억해야만 지켜집니다.

마지막으로, 사람이 하는 단계를 세어 보세요. 판단 때문에 남은 단계와, 사람이 직접 할 수밖에 없어서 남은 단계는 다릅니다. 앞의 것은 남겨 두고, 뒤의 것은 줄일 방법이 생겼는지 가끔 다시 확인하면 됩니다.

마치며

이 구조는 처음부터 설계한 것이 아닙니다. 노트북이 멈추고, 세션끼리 충돌하고, 잘못된 값이 그대로 나간 뒤에 하나씩 덧붙인 것들이에요. 그래서 그림으로 그려 보기 전까지는 저도 전체 모양을 한 번에 설명하지 못했습니다.

정리하면서 알게 된 것이 하나 있습니다. 에이전트가 하는 일이 늘어도 사람이 할 일이 없어지지는 않았습니다. 코드를 쓰던 자리에서, 무엇을 막을지 정하는 자리로 옮겨 갔을 뿐입니다.

다음 글에서는 에이전트 여러 개가 노트북 한 대를 같이 쓰다가 생긴 일을 다룹니다. 혼자서 또는 작은 팀에서 에이전트를 여러 개 쓰고 있다면 조금이나마 도움이 되었으면 합니다.