코드 공간의 건축학
소프트웨어의 디렉토리 구조는 코드라는 공간을 설계하는 일입니다. 이는 마치 건축가가 건물을 설계하듯, 개발 조직마다 고유한 철학과 문화에 맞게 코드베이스를 공간적으로 조직하는 것과 같습니다. 메타(페이스북), 마이크로소프트, 아마존 같은 빅테크 기업들은 각기 다른 개발 문화와 아키텍처 철학을 갖고 있으며, 이들이 만든 오픈소스 프로젝트들(예: React, VS Code, AWS SDK)의 디렉토리 구조에는 이러한 철학과 문화가 고스란히 녹아 있습니다. 아래에서는 각 기업의 실제 코드 디렉토리 구조를 살펴보고, 그것이 개발 문화, 조직 구조, 협업 방식, 아키텍처 철학과 어떻게 연결되는지 분석해보겠습니다.
페이스북(현 메타)의 개발 문화는 “Move Fast” 정신과 개방형 협업으로 유명합니다. 이를 뒷받침하는 아키텍처 철학 중 하나가 바로 모노리포(monorepo)입니다. 모노리포란 회사의 대부분 코드를 단일 저장소에 담는 방식으로, 메타는 실제로 거의 모든 코드를 하나의 거대한 리포지토리에 관리합니다. 이는 비유하자면 수많은 팀이 한 지붕 아래 모여 일하는 거대한 단일 건물과 같아서, 메타의 모든 개발자가 전체 코드를 검색하고 읽으며, 다른 팀의 코드까지도 필요하면 직접 수정할 수 있을 정도의 개방성과 투명성을 제공합니다. 이렇게 공간을 터놓음으로써 팀 간 경계를 느슨하게 하고, 콘웨이의 법칙(시스템 구조는 조직의 구조를 반영한다)을 적극적으로 활용하여 협업을 활성화한 것입니다.
메타의 모노리포 철학은 오픈소스 프로젝트 React의 디렉토리 구조에도 녹아 있습니다. React 깃허브 저장소를 보면 **packages/**라는 상위 디렉토리에 다수의 패키지들이 모여 있는 모노레포 형태입니다. 예를 들어 packages/react, packages/react-dom, packages/scheduler등 React의 하위 모듈들이 하나의 리포지토리 내에서 별도 폴더로 모듈화되어 존재합니다. npm 배포에 필요한 메타데이터(package.json등)도 모두 이 packages/폴더 아래에 위치하며, React와 관련된 여러 프로젝트를 한 곳에 관리하는 구조를 취하고 있습니다. 이러한 구조는 일관된 코드스타일 유지와 변경의 동시 반영을 용이하게 해주는데, 메타는 버전 불일치나 호환성 문제를 줄이기 위해 단일 버전 원칙을 활용합니다. 모노리포에서는 모든 패키지가 하나의 버전(최신 커밋 기준)으로 함께 빌드되기 때문에, 여러 패키지 간 버전 충돌이 원천적으로 제거되고 어느 커밋 시점에나 전체 코드베이스의 일관성이 보장됩니다. 이는 과거 메타 개발자들이 경험한, 멀티리포 환경에서 패키지 버전 충돌로 인한 “지옥”을 극복한 솔루션이기도 합니다.
또한 페이스북은 Haste라 불리는 자체 모듈 시스템을 고안했는데, 이는 거대한 코드베이스에서 파일의 위치 변경을 쉽게 해주는 도구입니다. Haste 시스템에서는 모든 파일 이름이 전역에서 유일하도록 강제되며, 파일을 경로 대신 모듈 이름으로 식별합니다. 덕분에 프로젝트 내에서 파일을 옮겨도 import 경로를 수정할 필요 없이 동일한 모듈 이름으로 참조가 가능해집니다. 이처럼 유연한 모듈 관리를 통해 페이스북 개발자들은 디렉토리 구조 개편이나 코드 리팩토링도 민첩하게 해낼 수 있고, 이는 빠른 실험과 개선을 장려하는 페이스북의 해커 문화와 맥을 같이합니다.
정리하면, 메타(Facebook)의 디렉토리 구조는 모노리포라는 거대한 공간 속에 모듈별로 방을 나눈 형태로 볼 수 있습니다. 모든 코드가 한 공간에 있지만 각 모듈은 자체 폴더로 구획되어 있고, 전체 건물에 대한 공유 접근권이 보장된 구조입니다. 이러한 공간 설계는 페이스북의 개방적이고 협업적인 개발 문화, 그리고 전체 코드를 한 덩어리로 다루면서도 부분별 모듈화를 추구하는 아키텍처 철학을 잘 보여줍니다.
마이크로소프트의 소프트웨어 개발은 전통적으로 체계적인 아키텍처 계층과 확장성에 중점을 두어 왔습니다. 이는 오픈소스로 공개된 Visual Studio Code(VS Code) 프로젝트의 디렉토리 구조에 잘 드러납니다. VS Code의 코드베이스를 살펴보면, src/vs/디렉토리에 에디터의 핵심 코어가 있고, 별도로 extensions/디렉토리에 각종 내장 확장 기능들이 모여있습니다. 즉, **코어(core)**와 익스텐션(extensions)영역을 분리하여, 코어는 최대한 경량의 레이어드 아키텍처로, 부가 기능들은 플러그인처럼 분리된 구조입니다. 이것은 마치
고층 건물에서 본체 건물과 별도의 부속 동(extensions)으로 기능별 공간을 분리한 듯한 모습입니다. VS Code의 src/vs/하위 구조는 더욱 세분화된 계층(layer)구조로 이루어져 있습니다. 마이크로소프트는 VS Code 코어를 Base → Platform → Editor → Workbench → Code → Server와 같은
여러 층으로 구분해 두었는데, 각각의 디렉토리가 소프트웨어의 특정 층위를 담당합니다. 예를 들어 base
레이어는 어디서나 쓰이는 기본 유틸리티와 UI 블록들을 제공하고, platform 레이어는 서비스 구조와 여러 층에 걸쳐 공용으로 쓰이는 서비스 정의를 담습니다. 그 위에 editor레이어에는 Monaco 에디터 코어(텍스트 편집 엔진)가, workbench레이어에는 편집기 외에 패널, 탐색기, 메뉴바 등 전체 IDE로서의 프레임워크가 자리합니다. 최상위 code는 실제 Electron 기반 데스크톱 앱 진입점으로서 모든 것을 묶어주고, server는 원격 개발을 위한 서버측 엔트리 포인트 역할을 합니다. 이러한 층별 분리설계는 각 레이어가 명확한 책임 영역
을 가지며, 아래층에 의존하지만 위층과는 최대한 느슨하게 결합되도록 합니다. 이는 높은 응집도와 낮은 결합도를 추구하는 마이크로소프트 아키텍처 철학이 반영된 것으로, 소프트웨어를 구축할 때도 건물의 층별 구조처럼 논리적인 계층 구조를 엄격히 적용한 것입니다.VS Code의 코어는 src/vs아래에서 Base, Platform, Editor, Workbench 등의 층별 디렉토리로 구분되어 있으며, 각 층은 하위에 공통(common), 브라우저(browser), 노드(node), Electron(electron-browser/main)등 타겟 환경별 폴더를 갖추고 있습니다. 예를 들어, vs/editor아래에는 common과 browser디렉토리가 나뉘어 있고,
common은 어느 환경에서나 쓰이는 논리, browser는 브라우저 DOM API에 의존하는 부분으로 분리됩니다. 이렇게 환경 별로 코드를 조직해 둠으로써 VS Code는 동일한 코드를 바탕으로 데스크톱(Electron)과 웹(Web) 버전 모두 제공하는 이식성을 확보했습니다. 또한 VS Code는 기능 확장을 익스텐션으로 분리하는데, 내장 기능조차도 extensions/ 폴더 아래 각 확장별 디렉토리에 구현되어 있습니다. 이 폴더 구조는 VS Code가 모듈식 확장성을 지향한다는 것을 보여주며, 새 기능은 독립적인 확장으로 추가하고, 코어와는 정해진 API로만 소통하도록 하는 플러그인 아키텍처 철학을 확인할 수 있습니다.
마이크로소프트의 협업 방식도 VS Code 프로젝트 구조와 운영에 반영되어 있습니다. VS Code는 깃허브에서 완전한 오픈 개발으로 진행되며, 마이크로소프트 팀과 커뮤니티가 함께 코드와 이슈를 다룹니다. 프로젝트 로드맵이나 월별 개발 플랜까지 저장소에 투명하게 공개되고, 전 세계 개발자들의 PR을 받아들이는 등 개방형 협업을 장려합니다. 잘 정리된 디렉토리 구조와 문서는 많은 외부 기여자들이 프로젝트에 참여하기 쉽게 하고, 이는 조직적이고 문서화된 개발문화를 중요시하는 마이크로소프트의 전통과 닮아 있습니다. 요약하면, VS Code의 디렉토리 구조는 체계적인 계층 구조와 명확한 모듈 경계를 가지고 있으며, 이것은 마이크로소프트의 설계 우선주의와 확장성 중시 철학, 그리고 커뮤니티와 협업하는 방식을 잘 보여주는 코드 공간의 설계라 할 수 있습니다.
아마존의 개발 조직은 “두 개의 피자 팀” 철학으로 유명합니다. 이는 한 팀이 두 판의 피자로 배불릴 정도(소수 정예)로 작게 유지되며, 각 팀이 독립적으로 하나의 서비스/제품을 끝까지 책임지는 구조를 말합니다. 이러한 조직 문화는 소프트웨어 구조에서도 마이크로서비스 아키텍처 및 멀티레포지토리 전략으로 나타납니다. 아마존 내부에서는 일반적으로 서비스마다 별도 코드 레포와 배포 파이프라인를 가지며, 팀 간 경계를 분명히하여 각자의 속도와 주기로 개발을 진행합니다. 비유하자면, 아마존의 코드베이스는 한 캠퍼스에 여러 동으로 나뉜 마을형 캠퍼스와 같아서, 각 빌딩(서비스)은 자기 팀이 소유하고 운용하며, 빌딩들 간에는 도로(API)로만 소통하는 형태입니다. 이 방식은 팀의 자율성과 빠른 혁신을 촉진하지만, 한편으로는 서비스들이 각기 다른 기술 스택이나 버전을 가질 수 있어 일관성 유지가 과제이기도 합니다.
아마존의 이러한 철학은 오픈소스 프로젝트 AWS SDK의 디렉토리 구조에서 잘 드러납니다. AWS SDK는 클라우드의 수많은 서비스를 다루는 라이브러리인데, 최신 **AWS SDK for JavaScript (v3)**를 살펴보면 서비스별로 모듈화된 구조를 갖습니다. AWS SDK v3는 300개가 넘는 개별 패키지로 쪼개어져 있으며, S3, EC2, DynamoDB 등 각 AWS 서비스마다 하나의 패키지를 제공합니다. 이러한 모든 패키지는 npm에서
@aws-sdk/client-서비스이름형태로 개별 배포되는데, 예를 들어 S3 클라이언트는 @aws-sdk/client-s3
패키지로, DynamoDB는 @aws-sdk/client-dynamodb패키지로 분리되어 있습니다.
덕분에 개발자는 자기 애플리케이션에 필요한 서비스 모듈만 골라 사용할 수 있고, 불필요한 코드가 포함되지 않아 **경량화(트리-쉐이킹)**에 유리합니다. 이러한 모듈식 디렉토리 구조는 아마존의 서비스 조직 구조와 정확히 맥을 같이합니다. 각 서비스 팀이 자기 서비스 SDK 모듈을 관리하고 발전시킬 수 있으며, 모듈 간에는 명확한 API로 통신하므로 한 모듈의 변경이 다른 모듈에 직접 영향을 주지 않습니다. 이것은
마이크로서비스의 코드 버전이라 볼 수 있으며, 팀의 자율성을 극대화한 아마존 문화가 반영된 것입니다.
흥미로운 점은 AWS SDK v3의 구현에서, 이렇게 수백 개로 나뉜 패키지들도 **내부적으로는 하나의 리포지토리(monorepo)**에 함께 관리된다는 것입니다. 아마존은 Lerna와 Yarn Workspaces 등의 도구를 활용해 다중 패키지들을 단일 코드베이스로 개발하고, 릴리즈 시에만 개별 패키지로 퍼블리시하는 방식을 택했습니다. 이는 기본적으로는 모놀리포의 개발 편의와 멀티패키지의 배포 이점을 모두 취하려는 전략입니다. 즉, 내부 개발 단계에서는 모든 SDK 패키지가 한 공간에서 호흡을 맞추지만, 외부 제공 형태는 서비스별로 독립적인 모듈이 되는 구조입니다. 이를 통해 아마존은 대규모 분산 서비스를 체계적으로 관리하면서도, 고객에게는 필요한 부품만 골라 쓸 수 있는 유연한 라이브러리를 제공하고 있습니다.
정리하면, 아마존의 디렉토리 구조는 서비스 경계에 따른 모듈화와 분산된 소유권의 철학이 담겨 있습니다. 코드의 공간 설계를 서비스별로 나누어 독립적인 건물들로 구성하고, 각 건물은 작은 팀이 자유롭게 개조·확장할 수 있도록 한 것이죠. 이는 아마존의 두 개의 피자 팀 문화, 마이크로서비스 아키텍처 지향, 그리고 고객이 필요한 것만 취할 수 있게 하는 유연성 등이 코드 구조에 투영된 사례라 할 수 있습니다/
“코드는 건축이다”라는 말처럼, 소프트웨어의 디렉토리 구조에는 코드base를 대하는 철학과 조직의 문화가 스며있습니다. 페이스북은 모노리포라는 거대한 열린 공간에 모듈을 배치함으로써 협업과 속도를 중시하는 해커 문화를 드러냈고, 마이크로소프트는 계층적 구조와 확장 포인트를 통해 체계적인 설계와 플랫폼 확장 철학을 구현했으며, 아마존은 서비스별 모듈화로 팀의 자율성과 독립성을 최우선시하는 문화를 표현했습니다. 각 기업의 디렉토리 구조를 하나의 건축 양식에 빗댄다면, 페이스북은 개방형 복합단지, 마이크로소프트는 견고한 구조의 고층빌딩, 아마존은 다채로운 건물이 모인 캠퍼스라고 할 수 있을 것입니다.
디렉토리 구조를 설계하는 일은 단순한 코드 파일 정리가 아니라, 어떤 협업 공간을 만들 것인지에 대한 고민입니다. 결국 좋은 소프트웨어 아키텍처란 해당 조직과 제품에 맞는 공간 설계를 하는 것이며, 여기에는 개발자들의 소통 방식, 팀의 경계와 역할, 시스템의 변화에 대한 철학이 모두 녹아듭니다. 이런 점에서 디렉토리 구조를 통해 코드를 바라보면, 코드베이스라는 공간을 어떻게 설계했는지에 따라 거기서 일하는 사람들의 방식도 결정됨을 알 수 있습니다. 건축물이 그 안의 삶을 담듯, 디렉토리 구조는 그 안의 코드와 협업의 삶을 담는 그릇인 것입니다.
참고한 자료: 메타의 모노리포와 협업 문화blog.3d-logic.comblog.3d-logic.com, React 오픈소스 구조medium.commedium.com, VS Code의 계층적 구조 및 확장 모델github.comgithub.com, VS Code 오픈소스 개발 방식github.com, AWS SDK의 서비스별 패키지화 구조aws.amazon.comaws.amazon.com, 아마존의 두 피자 팀과 마이크로서비스 원칙aws.amazon.com 등.