블로그 개발 기록 2 - Monorepo AI 코딩 환경 구성

시작하며

이번 블로그는 AI 코딩을 공부하기 위한 프로젝트이기도 했지만 동시에 실제로 내가 사용할 블로그를 만드는 프로젝트이기도 했다.

그래서 단순히 동작하는 블로그 수준에서 끝내고 싶지는 않았다. 어차피 내가 계속 써야 할 블로그라면 제대로 만들고 싶었고 이후에도 필요한 기능을 하나씩 붙여가며 계속 만들어나가고 싶었다. 원하는 기능을 추가할 때마다 구조를 크게 바꾸지 않아도 되고 어느 컴퓨터에서든 글을 쓰고 관리할 수 있는 관리자 기능까지 갖추는 것을 최종 목표로 잡았다.

그러다 보니 자연스럽게 프로젝트 구조에 대한 고민이 커졌다. client와 server를 분리해야 하는 것인지 AI 작업을 위한 문서와 자동화는 어떻게 할 것인지... 이 질문은 아직도 무엇이 정답인지 알 수 없다. (그저 개발해보면서 고쳐나가는 수밖에)

결과적으로는 Monorepo에 가까운 작업 환경을 구성하게 되었다.

이 결정이 처음부터 명확했던 것은 아니다. AI를 제대로 활용해본 경험이 거의 없었기 때문에 무엇이 유리한지 잘 와닿지 않았다. AI가 내가 지시한 작업을 얼마나 정확히 수행할지, hallucination은 어떻게 줄일 수 있을지, token은 어떻게 아껴야 할지 등등 같은 것들도 감이 없었다.

당시 이슈가 되었던 해커톤 우승자의 파워 팁을 참고했고 AI를 잘 사용하는 것으로 추정되는 지인에게도 조언을 구했다. 그때 들은 답도 이 자료를 참고해보라는 것이었다.

그 자료를 보면서 가장 와닿았던 건 단순했다.

일단 AI에게 작업을 지시한다.
반복되는 작업이 보이면 자동화한다.
도구는 사용하면서 공부한다.
작업 지시는 일회성 명령이 아니라 계획적인 문서로 남긴다.

일단 부딪혀보자는 생각으로 내가 개발하던 방식 그대로 AI에게 작업을 지시하며 결과물을 만들어갔다. 그러다보니 Context 관리와 문서화의 필요성을 조금씩 이해할 수 있었다.

프로젝트 구성

프로젝트의 repository는 총 3개로 구성했다.

경로	Repository	역할
`/`	`pyo-sh/pyosh-blog-ai`	AI context, docs, skills, Docker/tmux 환경 관리용 root repo
`/client`	`pyo-sh/pyosh-blog-fe`	frontend용 독립 Git repo
`/server`	`pyo-sh/pyosh-blog-be`	backend용 독립 Git repo

각각은 독립 Git repo이지만, 로컬에서는 하나의 root workspace 아래 폴더 형태로 존재하도록 했다. root repo에서는 client와 server를 gitignore 처리해서 포함하지 않았다.

Repository를 나눈 이유

하나의 repository 안에서 일반적인 Monorepo 형식으로 구성하지 않은 이유는 몇 가지가 있었다.

첫 번째는 AI에게 작업을 맡길 때 불필요한 정보까지 context에 들어가는 것을 피하고 싶었기 때문이다. Front 작업을 시킬 때 Back의 세부 코드까지 항상 같이 볼 필요는 없고 반대의 경우도 마찬가지라고 생각했다.

두 번째는 GitHub workflow나 test check를 각 프로젝트 단위로 따로 가져가고 싶었다. AI가 만든 작업물일수록 검증 과정이 중요하다고 생각했고, client와 server의 검증 기준을 분리하는 편이 관리하기 쉬워 보였다.

세 번째는 CI/CD 구성을 단순하게 가져가고 싶었기 때문이다. 각각의 프로젝트가 독립적으로 배포될 수 있다면 repository도 분리되어 있는 편이 자연스럽다고 봤다.

좋았던 점

블로그를 어느 정도 완성하고 돌아보는 지금은 이 환경 구성에 들인 시간과 노력이 꽤 가치 있었다고 생각한다.

가장 좋았던 점은 client와 server의 설계와 기록을 한곳에서 관리할 수 있었다는 것이다. 계획을 작성할 때 client와 server를 함께 고려할 수 있었고 client 작업을 하면서도 server 쪽 기록을 쉽게 참조할 수 있었다. 코드 repository는 분리되어 있지만 AI와 내가 참고하는 작업 맥락은 root에 모여 있었다.

개발할 때 디렉토리를 계속 옮겨 다니지 않아도 된다는 점도 좋았다. 만약 skills나 docs 같은 AI 작업물을 각각의 repo 안에 흩어두었다면 작업할 때마다 위치를 바꿔야 했을 것이다. 지금 구조에서는 자동화 기준이나 기록 방식을 root에서 통일할 수 있었다.

불편했던 점

단점도 크게 있었다.

가장 큰 단점은 초기 구성에 시간과 노력이 많이 들어간다는 점이었다. 단순히 'Repo 결정하고 분리 끝!'이 아니라 docs 위치, 자동화 script, worktree 경로까지 하나하나 명령하거나 기록해서 작업하도록 했다.

또 하나는 AI가 작업 위치를 혼동하는 문제가 있었다는 것이다.

예를 들어 issue를 참조해서 개발하고 -> 리뷰하고 -> 다시 수정하고 -> merge하는 반복 작업을 자동화하려고 했다. 이 과정을 병렬화하기 위해 git worktree를 사용했는데 repository가 세 개이다 보니 AI에게 어느 repo 기준으로 작업하는지 명시적으로 알려주지 않으면 혼동이 생겼다.

코드 리뷰도 새로운 세션에서 진행해야 더 투명하다고 생각해서 headless agent 호출 방식으로 진행했다. 그런데 부모 AI의 root directory가 client나 server가 되면, 그 상위 directory에 있는 skills를 제대로 호출하지 못하는 상황도 있었다.

처음에는 번거로웠지만 이 문제가 환경 설계의 일부임을 인정하고 고칠수밖에 없었다. Monorepo처럼 보이는 작업 환경 안에 독립된 git repository를 여러 개 둔 것은 결국 내가 선택한 구조였다. 그 구조에서 생기는 side effect도 내가 해결해야 하는 문제였다.

해결책은 여러 가지가 있었을 것이다. 나는 그중 하나로 skills나 script 안에서 repository를 명시적으로 참조하도록 만들었다. 어떤 작업이 client 기준인지, server 기준인지, root 기준인지를 코드와 문서로 강제하는 방식이었다.

유일한 정답이라고 생각하지는 않지만 내 상황에서는 합리적인 선택이었다. ~~(토큰 잡아먹는 괴물이였는데 스크립트로 쌀먹)~~

지금 돌아보면

지금 다시 같은 선택을 하겠느냐고 묻는다면 상황에 따라 다를 것 같다.

1인 개발이고 프로젝트 규모가 작다면 하나의 repository로 진행하는 것이 가장 편리할 수 있다. 관리해야 할 것이 줄어들고 AI에게도 작업 맥락을 설명하기 쉽다.

반대로 협업을 할 예정이거나 프로젝트 규모가 중간 이상이라면 repository를 나누는 것이 합리적일 수 있다고 생각한다. 다만 나누는 순간 관리와 기록도 그에 맞게 체계적으로 분리되어야 한다.

여러 명이 함께 개발한다면 또 다를 수 있다. 나처럼 하나의 작업 환경 안에 여러 프로젝트를 모아두는 방식보다 각 프로젝트마다 별도의 작업 환경을 구성하는 편이 더 나을 수도 있다.

환경 구성은 항상 최종적인 목표를 생각해야하는 것 같고 꼭 완벽하지 않더라도 대응 가능하게 설정하는것이 최선인 것 같다. 블로그 프로젝트는 확장성과 관리 방식을 고려해서 이런 구조를 선택했다. 중간에 예상하지 못한 문제도 있었지만 그 문제를 해결하는 과정에서 AI 작업 환경을 어떻게 설계해야 하는지 조금씩 이해하게 되었다.

이번 작업을 하면서 나는 AI에게 일을 맡기는 일도 결국 작업의 경계와 기록 방식을 정리하는 문제에 가깝다고 느꼈다. 반복되는 작업은 그냥 넘기지 않고 자동화할 수 있는 형태로 남겨야 한다는 것도 알게 되었다.

비록 토큰을 아끼기 위해 토큰을 사용하는 바보같은 상황처럼 보이더라도, 이번 선택이 적어도 이 프로젝트에서는 근거없는 선택이였다고 말할 수 있을 것 같다.