Athlentic은 iOS, Android, Web을 각각 별도의 Git 저장소로 운영합니다. 플랫폼이 나뉘면 배포와 이력 관리는 선명해지지만, AI 에이전트에게는 다른 문제가 생깁니다. iOS 저장소만 작업공간으로 열면 Android에 이미 구현된 정책도, Web에 정리된 제품 문구도, 다음 분기의 계획도 보이지 않습니다.
우리가 선택한 방법은 단순했습니다. 각 저장소를 합치는 대신, 그 위에 제품 전체를 담는 상위 작업공간을 하나 두는 것입니다.
저장소보다 한 단계 위에서 시작하기
루트에 제품 이름을 딴 Athlentic 폴더를 만들고, 플랫폼 저장소와 공통 문서를 모두 그 아래에 배치합니다.
여기서 중요한 점은 ios, android, web이 여전히 각자의 .git을 가진다는 것입니다. 상위 폴더는 제품 차원의 문서와 규칙을 관리하고, 실제 코드는 플랫폼별 저장소에서 독립적으로 커밋하고 배포합니다.
상위 Git은 코드 저장소를 추적하지 않는다
상위 Athlentic 폴더도 Git 저장소로 만들되, 플랫폼 폴더는 .gitignore에 추가합니다. 이렇게 하면 계획 문서의 변경 이력은 남기면서 중첩 저장소가 실수로 상위 저장소에 포함되는 일을 피할 수 있습니다.
상위 저장소가 각 플랫폼의 정확한 커밋을 고정해야 한다면 submodule이 더 적합합니다. 우리는 플랫폼 저장소의 독립성을 유지하면서 로컬에서 맥락만 함께 보여주는 것이 목적이라, 단순한 ignore 방식을 선택했습니다.
AI에게는 루트 폴더 하나만 연다
Codex 같은 AI 에이전트의 작업공간을 개별 저장소가 아니라 Athlentic 루트로 지정합니다. 그러면 에이전트는 작업을 시작할 때 공통 계획과 세 플랫폼의 구현을 함께 탐색할 수 있습니다.
- Android에 먼저 구현된 기능을 읽고 iOS 방식에 맞게 옮길 수 있습니다.
- Web의 제품 설명과 앱 안의 문구가 서로 다른 지점을 찾을 수 있습니다.
- 공통 데이터 모델의 변경이 각 플랫폼에 미치는 영향을 미리 확인할 수 있습니다.
- 계획 문서를 기준으로 큰 작업을 여러 저장소에 걸쳐 나누어 진행할 수 있습니다.
예를 들어 “운동 기록 내보내기 기능을 계획하고 iOS부터 구현해 줘”라고 요청하면, 에이전트는 docs/plans에 계획을 남기고 Android의 기존 데이터 모델과 Web의 개인정보 안내까지 참고한 뒤 iOS 저장소에서 작업할 수 있습니다.
계획 문서는 에이전트의 장기 기억이 된다
폴더를 한곳에 모으는 것만으로는 충분하지 않습니다. 에이전트가 매번 같은 판단을 반복하지 않도록, 제품 차원의 맥락을 문서로 남겨야 합니다.
AGENTS.md,CLAUDE.md에는 빌드 방법, 코딩 규칙, 저장소별 주의사항을 적습니다.docs/plans에는 작업의 목표, 범위, 완료 조건을 기록합니다.docs/architecture에는 플랫폼이 공유하는 개념과 데이터 흐름을 정리합니다.docs/decisions에는 무엇을 선택했는지뿐 아니라 왜 선택했는지를 남깁니다.
이 문서들은 대화를 새로 시작해도 남아 있습니다. 즉, 채팅 기록에만 의존하던 맥락이 저장소 안의 검토 가능한 자산으로 바뀝니다. 사람에게는 온보딩 문서가 되고, AI에게는 다음 작업을 위한 장기 기억이 됩니다.
좋았던 점과 지켜야 할 경계
가장 큰 장점은 AI가 파일 하나가 아니라 제품을 기준으로 생각하게 된다는 점입니다. 비슷한 구현을 다시 만들기 전에 다른 플랫폼을 참고하고, 코드 변경 전에 제품 계획을 확인하는 흐름이 자연스럽게 생깁니다.
대신 작업 범위는 명확히 알려줘야 합니다. 루트 전체를 볼 수 있다는 것이 모든 저장소를 자유롭게 수정해도 된다는 뜻은 아닙니다. 요청할 때 대상 저장소와 완료 조건을 적고, 에이전트가 각 저장소의 Git 상태를 따로 확인하도록 규칙을 두는 것이 안전합니다.
“맥락은 제품 전체에서 읽고, 변경은 요청받은 저장소에만 한다.” 이 한 문장이 넓은 작업공간의 장점은 살리고 예상하지 못한 수정을 줄여줍니다.
마치며
AI 에이전트를 잘 활용하는 일은 더 긴 프롬프트를 쓰는 것만으로 해결되지 않았습니다. 에이전트가 필요한 정보를 발견할 수 있도록 작업공간을 설계하고, 결정과 계획을 파일로 남기는 편이 훨씬 효과적이었습니다.
여러 플랫폼으로 하나의 제품을 만들고 있다면, 저장소를 합치기 전에 먼저 그 위에 작은 제품 작업공간을 만들어 보세요. 사람과 AI 모두에게 제품의 전체 지도를 제공하는 가장 가벼운 출발점이 될 수 있습니다.