Athlentic은 iOS, Android, Web을 각각 별도의 Git 저장소로 운영합니다. 플랫폼이 나뉘면 배포와 이력 관리는 선명해지지만, AI 에이전트에게는 다른 문제가 생깁니다. iOS 저장소만 작업공간으로 열면 Android에 이미 구현된 정책도, Web에 정리된 제품 문구도, 다음 분기의 계획도 보이지 않습니다.

우리가 선택한 방법은 단순했습니다. 각 저장소를 합치는 대신, 그 위에 제품 전체를 담는 상위 작업공간을 하나 두는 것입니다.

저장소보다 한 단계 위에서 시작하기

루트에 제품 이름을 딴 Athlentic 폴더를 만들고, 플랫폼 저장소와 공통 문서를 모두 그 아래에 배치합니다.

여기서 중요한 점은 ios, android, web이 여전히 각자의 .git을 가진다는 것입니다. 상위 폴더는 제품 차원의 문서와 규칙을 관리하고, 실제 코드는 플랫폼별 저장소에서 독립적으로 커밋하고 배포합니다.

상위 Git은 코드 저장소를 추적하지 않는다

상위 Athlentic 폴더도 Git 저장소로 만들되, 플랫폼 폴더는 .gitignore에 추가합니다. 이렇게 하면 계획 문서의 변경 이력은 남기면서 중첩 저장소가 실수로 상위 저장소에 포함되는 일을 피할 수 있습니다.

# Athlentic/.gitignore ios/ android/ web/ # 로컬 도구와 운영체제 파일 .DS_Store .idea/ .vscode/
Git submodule과는 목적이 다릅니다.

상위 저장소가 각 플랫폼의 정확한 커밋을 고정해야 한다면 submodule이 더 적합합니다. 우리는 플랫폼 저장소의 독립성을 유지하면서 로컬에서 맥락만 함께 보여주는 것이 목적이라, 단순한 ignore 방식을 선택했습니다.

AI에게는 루트 폴더 하나만 연다

Codex 같은 AI 에이전트의 작업공간을 개별 저장소가 아니라 Athlentic 루트로 지정합니다. 그러면 에이전트는 작업을 시작할 때 공통 계획과 세 플랫폼의 구현을 함께 탐색할 수 있습니다.

  • Android에 먼저 구현된 기능을 읽고 iOS 방식에 맞게 옮길 수 있습니다.
  • Web의 제품 설명과 앱 안의 문구가 서로 다른 지점을 찾을 수 있습니다.
  • 공통 데이터 모델의 변경이 각 플랫폼에 미치는 영향을 미리 확인할 수 있습니다.
  • 계획 문서를 기준으로 큰 작업을 여러 저장소에 걸쳐 나누어 진행할 수 있습니다.

예를 들어 “운동 기록 내보내기 기능을 계획하고 iOS부터 구현해 줘”라고 요청하면, 에이전트는 docs/plans에 계획을 남기고 Android의 기존 데이터 모델과 Web의 개인정보 안내까지 참고한 뒤 iOS 저장소에서 작업할 수 있습니다.

계획 문서는 에이전트의 장기 기억이 된다

폴더를 한곳에 모으는 것만으로는 충분하지 않습니다. 에이전트가 매번 같은 판단을 반복하지 않도록, 제품 차원의 맥락을 문서로 남겨야 합니다.

  1. AGENTS.md,CLAUDE.md에는 빌드 방법, 코딩 규칙, 저장소별 주의사항을 적습니다.
  2. docs/plans에는 작업의 목표, 범위, 완료 조건을 기록합니다.
  3. docs/architecture에는 플랫폼이 공유하는 개념과 데이터 흐름을 정리합니다.
  4. docs/decisions에는 무엇을 선택했는지뿐 아니라 왜 선택했는지를 남깁니다.

이 문서들은 대화를 새로 시작해도 남아 있습니다. 즉, 채팅 기록에만 의존하던 맥락이 저장소 안의 검토 가능한 자산으로 바뀝니다. 사람에게는 온보딩 문서가 되고, AI에게는 다음 작업을 위한 장기 기억이 됩니다.

저장소를 합칠지 나눌지 — 판단 기준

"모노레포로 갈까, 저장소를 나눌까"는 이 구조를 시작하기 전에 대부분 한 번은 겪는 결정입니다. 정답은 팀 크기와 배포 리듬에 따라 다르지만, 아래 기준으로 나누면 실수는 줄어듭니다.

항목 저장소 분리 상위 워크스페이스만 ──────────────────────────────────────────────────────────────── 배포 주기 다름 유리 문제없음 CI 러너 종류 다름 유리(파이프라인 단순) 러너 매트릭스 필요 플랫폼별 담당자 분리 유리 권한 관리가 번거로움 공유 코드 비중 큼 불리 유리(경로 임포트 가능) 언어·툴체인 다름 유리 IDE 인덱싱 무거워짐 릴리스 태그가 겹침 분리 권장 단일 태그가 애매해짐

Athlentic처럼 iOS(Swift), Android(Kotlin), Web(정적 HTML/Eleventy)이 언어와 배포 주기가 모두 다른 경우 저장소는 나눠 두는 편이 여전히 유리합니다. 하지만 계획과 결정 기록까지 각 저장소에 흩어 두면 AI가 제품 단위로 보지 못합니다. 그래서 상위 워크스페이스는 합치기가 아니라 덮어씌우기에 가깝습니다.

문서를 어디에 두느냐가 곧 규칙이 된다

같은 내용을 두 군데에 두면 반드시 어긋납니다. 어떤 문서를 상위 워크스페이스에 두고 어떤 문서를 각 저장소에 둘지의 원칙을 먼저 정하는 게 유지 비용을 크게 줄여줍니다.

  • 상위 워크스페이스에 둘 것: 제품 정의, 기능 계획, 여러 플랫폼에 걸친 결정, 데이터 모델·API 계약, 브랜드·문구·법무 정책. 즉 플랫폼이 바뀌어도 그대로인 것.
  • 각 저장소에 둘 것: 빌드·배포 방법, 플랫폼 특유의 코딩 규칙, 그 저장소만의 폴더 규약, CI 워크플로. 즉 해당 코드와 함께 움직여야 하는 것.
  • 두 곳에 두면 안 되는 것: 동일한 사양 문서. 상위에 원본을 두고, 저장소의 CLAUDE.md 에서는 링크만 겁니다. 원본을 옮길 때 링크만 고치면 됩니다.

이렇게 나누면 새로운 팀원이 iOS 저장소만 열어도 이 저장소에서 지켜야 할 규칙은 그 안에서 다 보이고, 제품 맥락은 링크를 타고 상위로 넘어가면 되는 흐름이 됩니다.

규칙 파일이 무시되는 경우와 대처

AGENTS.md 나 CLAUDE.md 를 아무리 자세히 써도 에이전트가 지키지 않는 상황이 종종 생깁니다. 원인은 대개 셋 중 하나입니다.

증상 원인 대처 ───────────────────────────────────────────────────────────────── 같은 실수를 반복한다 규칙이 예시 없이 추상적 "이렇게 하지 마" 대신 잘못된 예/올바른 예 일부만 지킨다 파일이 너무 길어 컨텍스트 초과 저장소별 CLAUDE.md 로 쪼갠다 아예 참고하지 않는 것 같다 파일 위치가 관례에서 벗어남 루트 또는 각 저장소 루트에 둔다

가장 자주 놓치는 지점은 두 번째입니다. 상위 워크스페이스의 CLAUDE.md 에 모든 플랫폼 규칙을 몰아 두면 iOS 작업 중에 Android 규칙이 컨텍스트를 차지합니다. 상위에는 공통 규칙만, 나머지는 각 저장소 CLAUDE.md 에 두는 편이 더 잘 지켜집니다.

기존 저장소를 이 구조로 옮기는 절차

이미 각 저장소에 계획 문서와 결정 기록이 흩어져 있다면, 옮기는 작업 자체가 리스크입니다. 아래 순서면 히스토리 손실 없이 이동할 수 있습니다.

1. 상위 폴더 Athlentic/ 을 만들고 새 git init 2. 기존 저장소를 그 아래로 clone — 원격 URL은 그대로 유지 3. Athlentic/.gitignore 에 ios/ · android/ · web/ 추가 4. 각 저장소의 docs/plans/ · docs/decisions/ 를 검토해 - "제품 정의·계획·결정" → Athlentic/docs/ 로 git mv 하고 히스토리 채로 이동 - "빌드·플랫폼 규칙" → 각 저장소에 그대로 남긴다 5. 옮긴 문서에 대한 참조를 각 저장소 CLAUDE.md 에서 상대경로 링크로 바꾼다 6. 첫 주는 상위 커밋과 저장소 커밋을 반드시 별도 PR 로 나눈다 — 리뷰 범위가 섞이지 않게

5번을 건너뛰면 참조가 깨져도 빌드가 잡지 않기 때문에 며칠 뒤 발견되는 문제가 생깁니다. 처음 옮기고 나면 각 저장소에서 상위 문서로 걸린 링크를 한 번 훑어 확인하는 편이 안전합니다.

좋았던 점과 지켜야 할 경계

가장 큰 장점은 AI가 파일 하나가 아니라 제품을 기준으로 생각하게 된다는 점입니다. 비슷한 구현을 다시 만들기 전에 다른 플랫폼을 참고하고, 코드 변경 전에 제품 계획을 확인하는 흐름이 자연스럽게 생깁니다.

대신 작업 범위는 명확히 알려줘야 합니다. 루트 전체를 볼 수 있다는 것이 모든 저장소를 자유롭게 수정해도 된다는 뜻은 아닙니다. 요청할 때 대상 저장소와 완료 조건을 적고, 에이전트가 각 저장소의 Git 상태를 따로 확인하도록 규칙을 두는 것이 안전합니다.

우리가 사용하는 간단한 원칙

“맥락은 제품 전체에서 읽고, 변경은 요청받은 저장소에만 한다.” 이 한 문장이 넓은 작업공간의 장점은 살리고 예상하지 못한 수정을 줄여줍니다.

자주 묻는 질문

플랫폼 저장소들이 서로 다른 GitHub 조직에 있어도 되나요?

됩니다. 상위 워크스페이스는 로컬 폴더일 뿐이고 각 저장소의 원격 URL은 그대로 유지됩니다. 다만 조직이 다르면 CI 시크릿과 접근 권한도 조직별로 관리되므로, 어떤 문서를 어느 조직 안에서만 볼 수 있는지 미리 정해 두세요. 상위 워크스페이스는 개인 저장소, 각 플랫폼은 회사 조직이라면 회사 정보를 상위에 두면 안 됩니다.

모노레포로 옮기는 게 더 낫지 않나요?

공유 코드 비중이 크고(예: 웹·앱이 같은 TS 코드를 씀) 배포 리듬이 비슷하면 모노레포가 더 낫습니다. 하지만 언어와 배포 주기가 각각 다른 경우 모노레포는 CI 매트릭스와 인덱싱 부담이 커집니다. 위 판단 기준 표에서 왼쪽 항목이 3개 이상이면 저장소는 그대로 두는 편이 유리합니다.

서브모듈이나 git worktree 를 쓰지 않는 이유는?

서브모듈은 상위 저장소가 각 플랫폼의 정확한 커밋을 고정해야 할 때 필요합니다. 우리는 그 반대로, 각 플랫폼이 자기 흐름대로 배포되기를 원했기 때문에 고정 기능이 오히려 방해가 됩니다. git worktree 는 같은 저장소의 여러 브랜치를 병렬로 열 때 쓰는 기능이라 이 문제와는 층위가 다릅니다.

계획 문서에 무엇을 얼마나 자세히 써야 하나요?

기준은 "6개월 뒤의 나 자신이 다시 읽었을 때 결정을 재현할 수 있는가"입니다. 목표·결정·근거 세 가지가 있으면 됩니다. 진행 과정의 채팅 로그를 통째로 붙이는 건 오히려 방해가 됩니다 — 결론이 어디에 있는지 흐려집니다. 실행 세부는 각 저장소 PR 설명이 담당합니다.

마치며

AI 에이전트를 잘 활용하는 일은 더 긴 프롬프트를 쓰는 것만으로 해결되지 않았습니다. 에이전트가 필요한 정보를 발견할 수 있도록 작업공간을 설계하고, 결정과 계획을 파일로 남기는 편이 훨씬 효과적이었습니다.

여러 플랫폼으로 하나의 제품을 만들고 있다면, 저장소를 합치기 전에 먼저 그 위에 작은 제품 작업공간을 만들어 보세요. 사람과 AI 모두에게 제품의 전체 지도를 제공하는 가장 가벼운 출발점이 될 수 있습니다.