작성 일시: 2026-06-25

서론

프론트엔드와 백엔드를 별개의 Git 리포지토리(Repository)로 관리하는 팀은 많습니다.

리포지토리를 분리함으로써 독립적인 배포, CI/CD, 리뷰를 실현할 수 있는 반면,

AI 에이전트(AI Agent)를 사용한 개발에서는 큰 벽에 부딪히는 경우가 있습니다.

본 기사에서는 사내 프로덕트(백엔드 myapp-be / 프론트엔드 myapp-fe)의 개발에서

기존의 CI/CD, PR, 브랜치 운용을 일절 변경하지 않고, AI 에이전트가 양쪽 리포지토리를 횡단하여 개발할 수 있는 환경을

git submodule superproject를 사용하여 구축한 기록을 소개합니다.

과제: 다중 리포지토리 구성에서 AI agent를 사용하기 어렵다

Claude Code나 Cursor와 같은 AI 에이전트는 기본적으로 열려 있는 워크스페이스(Workspace) 외의 코드를 참조할 수 없습니다.

예를 들어 백엔드의 API 응답 구조를 변경할 때, 프론트엔드 측에서의 영향 확인이나 구현도 동시에 수행하고 싶은 경우가 있습니다.

하지만 myapp-be만을 열어둔 상태에서 에이전트에게 의뢰하면, myapp-fe의 코드가 보이지 않는 상태로 답변이 돌아옵니다.

반대로 myapp-fe를 열면, 이번에는 be 측의 API 구현이 보이지 않습니다.

그렇다고 해서 완전한 모노레포(Monorepo)로의 이전은 큰 비용을 수반합니다.

빌드 도구의 통일, CI/CD 파이프라인의 재설계, PR 운용의 변경, 기존 자동 배포와의 정합성 확인 등, 이미 작동하고 있는 메커니즘을 모두 다시 만드는 리스크를 감수하기는 어려운 상황이었습니다.

구하고자 했던 것은 「기존의 각 리포지토리를 완전히 그대로 유지하면서, AI 에이전트에게는 양쪽을 동시에 보여주는」 방법입니다.

해법의 선택: 왜 submodule superproject인가

모노레포 도구는 기존 구성에 대한 변경이 크다

Turborepo나 Nx는 강력한 모노레포 도구이지만, 도입을 위해서는 각 리포지토리에 설정 파일 추가 및 빌드 도구 통일이 필요합니다.

기존의 독립된 CI/CD나 PR 운용과 공존시키기 어렵기 때문에, 「기존 리포지토리에는 손을 대지 않는다」라는 제약을 충족할 수 없습니다.

상위 디렉토리 접근 방식은 git worktree와 상성이 나쁘다

가장 심플해 보이는 방법은 「양쪽 리포지토리를 포함하는 상위 디렉토리를 만들고, 거기서 Claude Code를 기동하는」 방법입니다.

~/projects/myapp-workspace/
├── myapp-be/
└── myapp-fe/

설정 없이도 AI 에이전트가 양쪽 리포지토리를 참조할 수 있지만, 두 가지 문제가 있습니다.

1. git worktree와의 대응이 되지 않는다

피처 브랜치(Feature Branch)에서 작업할 때, myapp-be와 myapp-fe 각각에서 worktree를 별도로 추출해야 합니다.

be의 feat/xxx worktree와 fe의 feat/xxx worktree를 수동으로 대응시켜 관리해야 하므로,

기능 개발을 할 때마다 「어떤 worktree끼리 한 쌍인가」를 의식해야 하는 번거로움이 생깁니다.

2. 상위 디렉토리는 git 리포지토리가 아니다

상위 디렉토리 자체는 git으로 관리되지 않기 때문에, Claude Code의 /add-dir로 추가한 상태는 세션 고유의 것이 됩니다.

세션을 넘길 때마다 재설정이 필요하며, 팀에서 공유할 수 있는 구성으로 정착시키기 어렵습니다.

git submodule superproject는 이 두 가지를 모두 해결합니다.

superproject의 worktree를 하나 추출하면, be/와 fe/의 submodule도 한 쌍이 된 상태로 따라옵니다.

또한, superproject 자체가 git 리포지토리이므로 구성을 코드로 관리하고 공유할 수 있습니다.

git submodule superproject라는 선택

git submodule의 superproject(부모 리포지토리)는 앱의 코드를 가지지 않는, 순수하게 자식 리포지토리를 묶기 위한 목적으로만 존재하는 리포지토리입니다.

• myapp-be는 지금까지처럼 독자적인 PR, CI, 배포를 가집니다 -
• myapp-fe도 마찬가지로 완전히 독립적입니다 -
• myapp (superproject)은 두 개의 submodule을 참조하는 포인터만을 가집니다 -

자식 리포지토리 (sub-repo)의 코드를 변경할 때는 계속해서 각 자식 리포지토리 내부에서 PR을 제출합니다. superproject는 **AI 에이전트가 두 리포지토리를 동시에 참조하기 위한 윈도우 (window)**로서 기능합니다.

superproject의 구조

디렉토리 구성

myapp/ ← superproject (앱 코드 없음)
├── be/ ← submodule: myapp-be (main 브랜치 추적)
├── fe/ ← submodule: myapp-fe (main 브랜치 추적)
...

.gitmodules 설정

[submodule "be"]
path = be
url = ../myapp-be.git
...

branch는 git submodule update --remote 실행 시 참조할 브랜치를 지정합니다. 일반적인 --init으로는 기록된 커밋을 checkout 하기 때문에, 이 설정만으로 항상 최신 상태를 추적하는 것은 아닙니다.

URL을 상대 경로 (../myapp-be.git)로 설정한 것이 핵심입니다.

로컬에서 SSH clone을 했다면 SSH, CI에서 HTTPS checkout을 했다면 HTTPS와 같이, 부모 리포지토리의 프로토콜을 자동으로 따릅니다. 절대 URL로 설정했을 때 CI에서만 동작이 깨지는 등의 상황을 방지할 수 있습니다.

clone 시의 명령어

superproject를 clone한 후 submodule을 초기화하는 경우:

git clone git@github.com:your-org/myapp.git
cd myapp
git submodule update --init --recursive

또는 처음부터 submodule과 함께 clone하는 경우:

git clone --recurse-submodules git@github.com:your-org/myapp.git

포인터 자동 업데이트

submodule superproject의 가장 큰 운영 과제는 "submodule의 포인터가 오래되는 것"입니다.

자식 리포지토리에서 개발이 진행되어도, superproject가 참조하는 커밋은 수동으로 업데이트하지 않는 한 과거 상태로 남게 됩니다.

이 문제를 GitHub App + GitHub Actions로 완전히 자동화했습니다.

전체 흐름

[myapp-be: main으로 push]
│
│ notify-superproject.yml
...

myapp-be의 main 브랜치로의 push가 기점이 되어, superproject의 submodule 포인터 업데이트 PR이 자동 생성 및 auto-merge될 때까지가 하나의 연쇄입니다.

왜 GITHUB_TOKEN이 아니라 GitHub App인가

GitHub Actions의 기본 토큰 (GITHUB_TOKEN)에는 두 가지 제약이 있습니다.

1. 크로스 리포지토리 (cross-repository) 액세스가 불가능함

myapp-be의 워크플로우에서 myapp (superproject)으로 repository_dispatch를 전송하거나, superproject의 워크플로우에서 프라이빗(private)한 myapp-be를 checkout 하려면 다른 리포지토리에 대한 액세스 권한이 필요합니다. GITHUB_TOKEN은 자기 자신의 리포지토리에만 액세스할 수 있습니다.

2. GITHUB_TOKEN이 생성한 PR은 CI가 실행되지 않음

GitHub은 무한 루프 방지를 위해 GITHUB_TOKEN에 의한 push 유래의 워크플로우는 실행하지 않습니다. PR의 CI는 승인 대기 상태가 되므로, auto-merge에 필요한 필수 체크(required checks)가 영구적으로 pending 상태가 되어 버립니다.

GitHub App의 installation token은 이 두 가지를 모두 해결합니다.

설치된 리포지토리 (myapp, myapp-be, myapp-fe)에 대한 스코프(scope)가 지정된 토큰을 발행할 수 있으며, App이 생성한 PR에는 CI가 평소와 다름없이 실행됩니다.

송신 측: notify-superproject.yml (be / fe 각각에 배치)

name: Notify superproject (submodule pointer)
on:
  push:
...

이 워크플로우는 myapp-be와 myapp-fe(둘 다 main 브랜치를 추적) 각각에 배치합니다. 두 곳 모두 기본 브랜치(default branch)로의 push를 트리거로 하여 superproject에 알림을 보냅니다.

수신 측: update-submodule.yml (superproject에 배치)

name: Update submodule pointer
on:
  repository_dispatch:
...

concurrency의 cancel-in-progress: false 설정이 핵심이며, be와 fe가 동시에 push되었을 때 포인터 업데이트가 충돌하지 않도록 직렬화(serialization)합니다.

AI agent의 관점에서 본 세계

여기까지를 통해 superproject의 포인터가 항상 최신 상태로 유지되는 메커니즘이 갖춰졌습니다. 실제로 AI agent에게는 어떻게 보이는지 확인해 보겠습니다.

myapp superproject를 루트(root)로 하여 Claude Code를 열면, be/와 fe/가 동일한 디렉토리 트리로 보입니다.

에이전트는 백엔드 구현과 프론트엔드를 동시에 참조할 수 있는 상태가 됩니다.

superproject의 루트에 배치한 CLAUDE.md에는 횡단 개발(cross-repository development) 규칙을 기술합니다.

"코드 변경·커밋·PR은 각 submodule 내부에서 수행한다"
"두 리포지토리를 가로지르는 기능은 be → fe 순서로 구현한다 (fe는 be의 API에 의존하기 때문)"

이와 같은 규칙을 작성해 둠으로써, 에이전트가 superproject의 소스를 직접 편집하는 실수를 방지하면서도, 횡단적인 조사 및 개발을 일관되게 수행할 수 있게 됩니다.

요약

git submodule superproject를 사용함으로써, 기존의 CI/CD·PR·브랜치 운영 방식을 전혀 바꾸지 않고도 AI 에이전트의 횡단 개발 환경을 실현할 수 있었습니다.

superproject를 루트로 열기만 하면 be와 fe를 가로지르는 조사 및 구현이 가능해집니다.

주의할 점은 두 가지가 있습니다. 첫 번째는 submodule 취급에 대한 숙련도로, git submodule update --init을 잊으면 오래된 코드를 참조하게 됩니다. 두 번째는 코드 변경을 superproject가 아닌 각 submodule 내부에서 수행하는 규율입니다.

여러 리포지토리 구성을 유지하면서 지금 바로 AI 에이전트의 횡단 개발을 시작하고 싶은 팀에게 적합한 구성입니다.

Discussion