AI와 함께 춤을.. 아니, 코딩을.. (4) - 모노레포로 개발 환경 통합하기

바이브 코딩을 하는 가장 큰 이유는 아마도 개발 생산성 향상일 것이다. 그래서인지 바이브 코딩을 하면서 자연스럽게 "어떻게 하면 효율을 더 높일 수 있을까?"를 고민하게 된다. 직접 코드를 작성하지 않으니, 그만큼 남는 시간을 프로세스 개선에 투자하게 되는 셈이다.

지난 포스팅에서 앱과 서버를 함께 개발할 때 명세 문서를 작성하고, 이를 기반으로 AI 에이전트에게 개발을 지시하는 방식을 소개했었다. 오늘은 이 방식을 실제로 사용하면서 겪었던 불편함과, 그것을 어떻게 개선했는지 이야기해보려 한다.

기존 개발 환경

앱에 기능을 추가하다 보니 서비스가 하나가 아니라 여러 개가 되었다. 당시 내 개발 환경을 간단히 그려보면 이런 구조였다.

개발 Macbook
  └─ 앱 프로젝트/
       ├─ docs/
       └─ src/

Ubuntu 서버
  ├─ server1 프로젝트/
  │    ├─ docs/
  │    └─ src/
  └─ server2 프로젝트/
       ├─ docs/
       └─ src/

iOS 앱 개발은 어쩔 수 없이 Mac에서 해야 했다. 서버는 DB도 돌려야 하고, 실제 운영 환경과 동일한 조건에서 개발하는 게 나을 것 같아 Ubuntu에서 진행했다. Macbook 용량도 부족한데 DB 서버를 계속 띄워놓기도 부담스러웠고, 초기에 API 서버가 PHP + Apache 조합이었던 것도 분리한 이유 중 하나였다.

기존 개발 프로세스

새로운 기능을 추가하거나 수정할 때는 이런 순서로 작업했다.

VS Code에서 앱 프로젝트를 열고, Claude를 이용해 명세를 작성한다.
작성된 명세를 구현이 필요한 각 프로젝트의 docs 폴더에 복사한다.
VS Code에서 각 프로젝트를 연다. 서버의 경우 VS Code의 원격 연결을 이용한다.
각 프로젝트에서 Claude를 실행하고, docs 폴더의 명세를 기반으로 개발을 지시한다.

문제점

문제 1. 명세 문서 동기화의 번거로움

명세가 수정될 때마다 관련된 모든 프로젝트에 파일을 일일이 복사해 넣어야 했다. server1과 server2 모두 참조하는 명세인데, 개발을 진행하다 보면 앱과 server1만 업데이트되고 server2는 빠지는 경우가 생겼다. 시간이 지난 후 server2 관련 기능을 수정해야 할 때, 명세 간 차이가 있다는 걸 뒤늦게 발견하고 잘못된 방향으로 개발이 진행되는 일이 있었다.

문제 2. 연동 오류 발생 시 디버깅의 복잡함

동일한 명세를 주더라도 각 에이전트가 구현하는 방식에 차이가 생긴다. 실제 동작 시 연동이 안 되거나, 명세 작성 단계에서 미처 고려하지 못한 문제로 오류가 발생하기도 한다. 경험상 이런 상황은 매우 빈번하게 일어난다.

이때 핵심은 "서버가 잘못된 건지, 앱이 잘못된 건지"를 먼저 파악하는 것이다. 사람이 개발하는 경우라면 두 개발자를 불러다 놓고 문제를 논의하면 되지만, AI 에이전트 환경에서는 사정이 다르다. 마치 서버와 앱을 각각 다른 외주 업체에 맡기고, PM이 중간에서 조율하는 구조와 비슷해진다.

실제로는 이런 식이다. 먼저 앱 쪽에 오류 원인을 분석하라고 지시한다. "서버가 이렇게 응답해야 하는데 다르게 온다"는 식의 분석 결과가 나오면, 이걸 복사해서 서버 쪽에 전달하며 분석을 지시한다. 결과를 보고 어느 쪽을 수정할지 판단해서 지시하고, 필요하면 명세도 수정한 뒤 양쪽에 다시 반영한다.

이 두 가지 문제가 겹치면, 특히 앱과 server1, server2가 모두 관련된 경우라면 디버깅 과정은 한층 더 복잡해진다.

해결: 모노레포로 통합

결국 개발 환경을 일원화하기로 했다. 흔히 "모노레포(Monorepo)"라고 불리는 방식으로, 서로 다른 단말에서 진행하던 서버와 앱 개발을 하나의 프로젝트로 통합했다.

개발 프로젝트/
  ├─ docs/        ← 통합 명세
  ├─ app/
  ├─ server1/
  └─ server2/

프로젝트 폴더 아래에 모든 코드와 문서를 한곳에 모았다. 각 프로젝트 하위에 흩어져 있던 docs 폴더를 없애고, 전체 명세를 관리하는 단일 docs 폴더를 루트에 두었다.

여기서 중요한 포인트가 하나 있다. 프로젝트 루트의 CLAUDE.md 파일에 각 폴더에 대한 설명을 상세히 기술해야 한다는 것이다. "앱 관련 지시를 받으면 app/ 폴더를 참조하라", "인증 기능은 server1/을 봐라"처럼 지시에 따라 수정해야 할 위치를 명시해주는 것이다. 이렇게 하지 않으면 기능 하나를 지시할 때 관련 파일을 찾느라 컨텍스트를 과도하게 소모하게 된다.

개선 효과

문제 1은 자연스럽게 해결되었다. 명세가 처음부터 통합 docs 폴더에 생성되니 별도로 동기화할 필요가 없어졌다.

문제 2도 크게 완화되었다. 동일한 컨텍스트 안에서 모든 코드를 접근하기 때문에, 에이전트가 코드를 생성할 때 구현 방식의 차이가 줄어들어 연동 오류 자체가 감소했다. 오류가 발생하더라도 "관련된 소스를 모두 참조해서 원인을 파악하라"고 한 번만 지시하면 종합적인 분석이 가능해져, 해결 속도가 훨씬 빨라졌다.

부가적인 장점도 있었다. 새 기능을 위한 명세를 작성할 때 모든 정보가 한 컨텍스트에 있으니, AI가 좀 더 종합적으로 판단하여 기능 배치를 적절히 하고 불필요한 의존 관계가 생기는 것을 미리 방지할 수 있었다.

마치며

바이브 코딩에서 AI 에이전트는 결국 "아주 빠르게 일하지만, 맥락 공유가 안 되면 엇나가기 쉬운 팀원"과 같다. 프로젝트가 분산되어 있으면 그만큼 PM 역할의 부담이 커지고, 통합하면 그 부담이 줄어든다. 코드를 직접 작성하지 않는 대신, AI가 효율적으로 일할 수 있는 환경을 설계하는 것이 바이브 코딩 시대의 개발자가 해야 할 중요한 일이 아닐까 생각한다.

🤝 AI와 함께 춤을 시리즈

(1) 오래된 개발자의 AI 코딩 여정기

(2) 문서화로 AI와 소통하기

(3) 서버 개발, AI와 함께 넘은 벽

(4) 모노레포로 개발 환경 통합하기 ← 현재 글

✍️ 이 글은 Claude의 도움을 받아 다듬어졌습니다.

고인물? 새내기?

이 블로그 검색