VSCode 여러 프로젝트, 폴더별로 따로 관리하기

VSCode 워크스페이스 관리법, 여러 프로젝트를 동시에 진행하다 보니 각기 다른 설정이나 확장 기능을 적용하고 싶은데 기본 설정으로는 이 모든 것을 한 번에 관리하기 어려워 막막한 상황입니다. 프론트엔드 프로젝트에서는 Prettier를 쓰고 백엔드에서는 Black을 써야 하는데, 창마다 설정을 바꾸는 데 시간을 낭비하게 되죠. 이 문제는 VSCode가 기본적으로 사용자 설정(User Settings)을 전역 적용하기 때문에 발생하며, 프로젝트의 특성에 맞는 격리된 환경을 구축하지 못해서 생깁니다. 이 글에서는 프로젝트 폴더별로 독립된 설정을 적용하고, 확장 기능을 효율적으로 제어하여 개발 생산성을 극대화하는 VSCode 워크스페이스 관리법을 구체적인 단계와 실제 코드 예시로 상세히 설명합니다.

함께 보면 좋은 글: 맥북 M4 성능 2026 최적화, 느려짐 방지

왜 프로젝트별 환경 분리가 필수적인가

개발을 하다 보면 하나의 에디터에서 레거시 PHP 프로젝트와 최신 React 프로젝트를 동시에 다뤄야 하는 경우가 빈번합니다. 이때 가장 큰 문제는 확장 프로그램과 코드 포맷팅 규칙의 충돌입니다. 예를 들어, A 프로젝트는 탭 크기를 2로 쓰지만 B 프로젝트는 4를 요구할 수 있습니다. 이를 통합해서 관리하면 코드 저장 시 자동으로 들쭉날쭉한 포맷팅이 적용되어 Git 커밋 내역이 지저분해집니다. Microsoft 공식 문서에 따르면 VSCode의 설정 계층은 기본값(Default), 사용자 설정(User), 원격(Remote), 워크스페이스(Workspace), 폴더(Folder) 순으로 우선순위를 가지며, 하위 레벨의 설정이 상위 레벨을 덮어씁니다. 이 원리를 이용해야만 충돌 없는 개발 환경을 만들 수 있습니다.

단순히 설정 파일을 여러 개 만드는 것만으로는 부족합니다. 실제로 제가 맥북 M2에서 대규모 모노레포(Monorepo)를 작업할 때, 워크스페이스 설정 없이 전역 확장 프로그램만 로드했을 때는 메모리 사용량이 4GB를 넘어서 에디터가 버벅거리는 경험을 했습니다. 불필요한 확장 기능이 모든 프로젝트에 로드되기 때문입니다. 따라서 프로젝트의 성격에 따라 필요한 도구만 켜고 끄는 것이 VSCode 워크스페이스 관리법의 핵심입니다. 이를 통해 에디터의 부하를 줄이고, 각 프로젝트에 최적화된 개발 경험을 제공받을 수 있습니다.

특히, 여러 언어와 프레임워크를 사용하는 풀스택 개발자나 여러 고객사의 프로젝트를 동시에 관리하는 프리랜서에게는 이러한 환경 분리가 더욱 중요합니다. 예를 들어, 한 프로젝트는 Node.js와 Express를 사용하고 다른 프로젝트는 Python과 Django를 사용한다고 가정해봅시다. 각 프로젝트는 특정 버전의 Node.js나 Python을 요구하며, 이에 맞는 개발 도구(Linter, Formatter, Debugger)도 달라집니다. 이러한 요구사항을 VSCode의 전역 설정으로 모두 관리하려고 하면 설정이 복잡해지고, 실수로 다른 프로젝트에 잘못된 설정을 적용하여 빌드 오류나 런타임 오류를 유발할 가능성이 높아집니다. 따라서 프로젝트별로 격리된 개발 환경을 구축하는 것은 개발자의 정신 건강과 코드 품질을 지키는 데 필수적입니다.

Photo by Anete Lusina on Pexels

멀티 루트 워크스페이스 생성 및 설정

VSCode의 가장 강력한 기능 중 하나는 멀티 루트 워크스페이스입니다. 이 기능을 사용하면 서로 다른 위치에 있는 폴더를 하나의 VSCode 창(Workspace)으로 논리적으로 묶을 수 있습니다. 예를 들어, 'Frontend' 폴더와 'Backend' 폴더가 디스크 상으로는 분리되어 있지만, 하나의 워크스페이스에서 동시에 작업할 수 있습니다. 이렇게 하면 두 프로젝트 간의 파일 이동이나 검색이 훨씬 수월해집니다. VSCode 1.90 이상 버전에서는 이 기능이 매우 안정적이며, 대규모 프로젝트에서도 성능 저하 없이 작동합니다.

워크스페이스를 생성하는 방법은 매우 간단합니다. 메뉴에서 파일(File) > 폴더 작업을 위해 저장(Save Workspace As...)을 선택하면 됩니다. 이 과정에서 .code-workspace 확장자를 가진 JSON 파일이 생성됩니다. 이 파일이 바로 해당 워크스페이스의 모든 설정 정보를 담고 있는 컨테이너입니다. 이 파일을 Git에 커밋해 두면 팀원들이 동일한 워크스페이스 구조를 그대로 복원하여 사용할 수 있어 협업 효율이 극대화됩니다.

멀티 루트 워크스페이스는 단순히 여러 폴더를 한 창에 열어두는 것 이상의 의미를 가집니다. 이는 각 폴더에 대한 독립적인 설정, 확장 프로그램 제어, 심지어는 원격 개발 환경 설정까지 가능하게 하여, 복잡한 모노레포 구조나 마이크로서비스 아키텍처를 관리하는 데 있어 개발 생산성을 비약적으로 향상시킵니다. 예를 들어, 한 워크스페이스에 프론트엔드, 백엔드, 공유 라이브러리 폴더를 포함시키고, 각 폴더별로 다른 Git 브랜치를 동시에 열어두고 작업하는 것도 가능합니다. 이는 컨텍스트 스위칭 오버헤드를 줄여주어 개발 흐름을 유지하는 데 큰 도움을 줍니다.

{
  "folders": [
    {
      "name": "Frontend App", // 폴더 이름을 지정하여 VSCode 탐색기에서 더 명확하게 표시
      "path": "../frontend-app"
    },
    {
      "name": "Backend API",
      "path": "../backend-api"
    },
    {
      "name": "Shared Libraries",
      "path": "../shared-libs"
    }
  ],
  "settings": {
    "editor.formatOnSave": true,
    "editor.tabSize": 2,
    "files.exclude": {
      "**/.git": true,
      "**/.DS_Store": true,
      "**/node_modules": true // 모든 프로젝트에 공통적으로 숨길 파일/폴더 지정
    },
    "workbench.editor.enablePreview": false // 미리 보기 탭 비활성화 (선택 사항)
  }
}

폴더별 세부 설정 파일 관리하기

멀티 루트 워크스페이스가 전체적인 그릇이라면, 폴더별 설정은 각 방의 인테리어를 결정하는 것과 같습니다. 워크스페이스 전체에 공통으로 적용되는 설정과는 별개로, 특정 폴더에서만 작동해야 하는 규칙이 있을 수 있습니다. 예를 들어, 백엔드 API 폴더에서는 Python의 Pylint와 Black을 사용하지만, 프론트엔드 폴더에서는 ESLint와 Prettier를 사용해야 합니다. 이때 각 폴더 루트에 .vscode/settings.json 파일을 생성하면 워크스페이스 설정보다 더 우선순위가 높은 폴더 전용 설정을 적용할 수 있습니다.

이 방식의 큰 장점은 설정의 '상속'과 '재정의'가 자연스럽게 이루어진다는 점입니다. 사용자 설정에서 기본 에디터 폰트를 지정하고, 워크스페이스 설정에서 탭 크기를 2로 지정한 뒤, 특정 폴더 설정에서만 탭 크기를 4로 덮어쓸 수 있습니다. 저는 개인적으로 Python 프로젝트를 진행할 때, 전체 설정은 두 칸 들여쓰기를 쓰지만 데이터 분석 폴더(analysis)에서만 4칸 들여쓰기를 강제하도록 설정하여 혼란을 막습니다. 이렇게 세분화된 관리가 가능한 것이 VSCode 워크스페이스 관리법의 진정한 힘입니다.

실제로 제가 운영하는 오픈소스 프로젝트에서는 .vscode 폴더를 통해 기여자들이 일관된 개발 환경을 갖도록 유도하고 있습니다. 새로운 기여자가 리포지토리를 클론만 하면 별도의 설정 없이도 프로젝트 규칙에 맞는 포맷터와 Linter가 적용되는 경험을 제공합니다. 이는 온보딩 시간을 획기적으로 단축시키는 요인이 됩니다. 더 나아가, .vscode/extensions.json 파일을 활용하여 프로젝트에 필요한 확장 프로그램 목록을 명시하고, VSCode가 해당 확장 프로그램을 설치하도록 추천하게 할 수도 있습니다. 이는 팀원 간의 개발 환경 불일치를 최소화하는 데 매우 효과적입니다.

각 폴더별 설정 파일은 해당 폴더의 루트에 .vscode라는 하위 디렉토리를 만들고 그 안에 settings.json 파일을 생성하는 방식으로 관리합니다. 이 파일에 작성된 설정은 해당 폴더 및 그 하위 폴더에만 적용되며, 워크스페이스 레벨 설정보다 높은 우선순위를 가집니다. 예를 들어, 백엔드 API 프로젝트에서는 Python 린팅과 포맷팅을 활성화하고, 프론트엔드 프로젝트에서는 JavaScript/TypeScript 린팅과 포맷팅을 활성화하는 식입니다. 이처럼 계층적인 설정을 통해 각 프로젝트의 고유한 요구사항을 충족시키면서도 전체적인 개발 경험을 일관되게 유지할 수 있습니다. 이는 프로젝트의 복잡성이 증가할수록 그 가치를 더욱 발휘합니다.

// backend-api/.vscode/settings.json
{
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "python.formatting.provider": "black",
  "editor.tabSize": 4,
  "files.trimTrailingWhitespace": true,
  "python.analysis.typeCheckingMode": "basic" // Python 타입 체킹 모드 설정
}

// frontend-app/.vscode/settings.json
{
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.formatOnSave": true,
  "eslint.enable": true,
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "editor.tabSize": 2
}

확장 프로그램 프로젝트별 제어하기

설정뿐만 아니라 확장 프로그램(Extensions)도 프로젝트별로 켜고 끌 수 있습니다. 모든 확장 프로그램이 항상 필요한 것은 아닙니다. 예를 들어, Docker 관련 확장은 백엔드 폴더에서만 필요하고, React/Redux 관련 확장은 프론트엔드 폴더에서만 필요합니다. 불필요한 확장 프로그램이 활성화되면 VSCode의 시작 시간이 길어지고, 메모리 점유율이 높아집니다. 실제로 제 Windows 11 개발용 PC에서 50개 이상의 확장 프로그램을 전부 활성화했을 때는 파일 탐색기가 열릴 때마다 1~2초의 딜레이가 발생했지만, 워크스페이스별로 비활성화한 후에는 즉시 반응하는 속도를 확인했습니다.

확장 프로그램을 제어하려면 확장 프로그램 뷰에서 마우스 오른쪽 버튼을 클릭한 뒤 'Disable (Workspace)'를 선택하면 됩니다. 이렇게 하면 해당 워크스페이스에서만 확장 프로그램이 비활성화됩니다. 반대로, 특정 워크스페이스에서만 확장 프로그램을 활성화하고 싶다면 'Enable (Workspace)'를 사용하면 됩니다. 또한, .code-workspace 파일 내부에 extensions.unwantedRecommendations 설정을 추가하여, 특정 워크스페이스에서 추천하지 않을 확장 목록을 관리할 수도 있습니다.

확장 프로그램의 프로젝트별 제어는 VSCode의 성능 최적화에 매우 중요합니다. 모든 확장 프로그램이 모든 프로젝트에 필요한 것은 아니므로, 각 프로젝트의 특성에 맞춰 필요한 확장 프로그램만 활성화하는 것이 좋습니다. 예를 들어, Ruby on Rails 프로젝트를 작업할 때는 Ruby 관련 확장 프로그램만 활성화하고, Vue.js 프로젝트를 작업할 때는 Vue 관련 확장 프로그램만 활성화하는 방식입니다. 이는 VSCode의 시작 시간을 단축시키고, 메모리 사용량을 줄여 전반적인 개발 환경의 반응성을 향상시킵니다. 또한, 특정 프로젝트에만 필요한 확장 프로그램이 다른 프로젝트에 영향을 미치는 것을 방지하여 예상치 못한 충돌이나 오류 발생 가능성을 줄여줍니다.

확장 프로그램 제어는 VSCode의 확장 프로그램 뷰에서 직접 수행할 수 있습니다. 특정 확장 프로그램을 선택한 후, 마우스 오른쪽 버튼을 클릭하면 'Enable (Workspace)' 또는 'Disable (Workspace)' 옵션이 나타납니다. 이를 선택하면 해당 워크스페이스에서만 확장 프로그램이 활성화되거나 비활성화됩니다. 또한, .vscode/extensions.json 파일을 통해 프로젝트별로 필요한 확장 프로그램을 명시적으로 지정할 수 있습니다. 이 파일에 recommendations 배열을 사용하여 필요한 확장 프로그램의 ID를 나열하면, VSCode는 해당 워크스페이스를 열 때 자동으로 해당 확장 프로그램을 설치하도록 제안합니다. 이는 팀원들이 동일한 개발 환경을 쉽게 구축하도록 돕는 강력한 기능입니다.

VSCode 워크스페이스 관리법 도구 비교 및 추천

지금까지 설명한 기본 기능 외에도 VSCode 워크스페이스 관리법을 극대화할 수 있는 여러 접근 방식이 있습니다. 여기서는 가장 대표적인 세 가지 방식을 비교 분석합니다. 첫 번째는 VSCode 기본 기능만을 활용하는 단순 방식, 두 번째는 앞서 설명한 멀티 루트 워크스페이스 파일을 활용하는 방식, 세 번째는 'Project Manager'와 같은 서드파티 확장 프로그램을 사용하여 자동화하는 방식입니다. 각 방식은 장단점이 명확하므로 본인의 프로젝트 규모와 복잡도에 맞춰 선택해야 합니다.

프로젝트가 단순히 하나의 폴더로 구성되어 있다면 기본 기능으로 충분합니다. 하지만 프론트엔드와 백엔드, 그리고 공유 라이브러리를 함께 개발해야 하는 복합적인 환경이라면 멀티 루트 워크스페이스가 필수적입니다. 그리고 10개 이상의 프로젝트를 오가며 작업해야 하는 프리랜서나 에이전시 개발자라면 Project Manager 확장 프로그램을 사용하여 프로젝트 목록을 태그별로 관리하고 단축키로 즉시 호출하는 것이 효율적입니다. 저는 개인적으로 세 가지 방식을 상황에 따라 혼합해서 사용합니다.

각 방식의 장단점을 자세히 살펴보겠습니다. 기본 단일 창 방식은 가장 간단하지만, 프로젝트별 설정 분리가 어렵다는 단점이 있습니다. 모든 설정이 전역으로 적용되므로, 프로젝트마다 설정을 수동으로 변경해야 하는 번거로움이 발생합니다. 멀티 루트 워크스페이스 방식은 VSCode의 내장 기능으로, 여러 폴더를 하나의 워크스페이스로 묶어 관리할 수 있습니다. 이는 프로젝트별 설정 파일(.vscode/settings.json)과 워크스페이스 설정 파일(.code-workspace)을 통해 각 폴더의 설정을 독립적으로 관리할 수 있게 해줍니다. 하지만 프로젝트 수가 매우 많아지면 워크스페이스 파일을 관리하는 것 자체가 부담스러워질 수 있습니다.

마지막으로, Project Manager 확장 프로그램은 수십 개 이상의 프로젝트를 자주 전환해야 하는 개발자에게 매우 유용합니다. 이 확장 프로그램은 즐겨찾기 프로젝트를 등록하고, 태그를 붙여 분류하며, 단축키를 통해 원하는 프로젝트를 즉시 열 수 있는 기능을 제공합니다. 또한, 각 프로젝트별로 저장된 워크스페이스 설정을 자동으로 로드하는 기능도 지원하여, 멀티 루트 워크스페이스의 장점을 더욱 편리하게 활용할 수 있도록 돕습니다. 저는 개인적으로 5개 이상의 프로젝트를 동시에 관리할 때는 Project Manager를 적극 활용하여 생산성을 높이고 있습니다.

프로젝트 관리 자동화를 위한 팁

VSCode 워크스페이스 관리의 궁극적인 목표는 개발 생산성을 극대화하는 것입니다. 이를 위해 몇 가지 자동화 팁을 활용하면 더욱 효율적인 개발 환경을 구축할 수 있습니다. 첫째, 쉘 스크립트나 빌드 도구를 활용하여 워크스페이스 설정을 자동으로 생성하거나 업데이트하는 방법입니다. 예를 들어, 새로운 프로젝트를 시작할 때 CLI 명령어를 통해 .vscode 폴더와 필요한 settings.json 파일을 자동으로 생성하고, .code-workspace 파일에 해당 프로젝트를 추가하는 스크립트를 작성할 수 있습니다.

둘째, Git Hooks를 활용하여 커밋 전에 특정 설정을 강제하거나, 푸시 전에 코드 포맷팅을 자동으로 수행하도록 설정할 수 있습니다. 예를 들어, pre-commit 훅을 사용하여 모든 커밋 전에 Prettier나 Black과 같은 포맷터가 코드를 자동으로 정리하도록 설정하면, 코드 리뷰 과정에서 포맷팅 관련 논쟁을 줄이고 일관된 코드 스타일을 유지할 수 있습니다. 이는 팀 전체의 코드 품질을 향상시키는 데 크게 기여합니다.

셋째, VSCode의 Task 기능을 활용하여 반복적인 작업을 자동화하는 것입니다. 예를 들어, 특정 프로젝트를 빌드하거나, 개발 서버를 시작하거나, 테스트를 실행하는 등의 작업을 VSCode Task로 정의해두면, 단축키 하나로 이러한 작업