프로젝트마다 다른 VSCode 워크스페이스 관리법 딱 정리

VSCode 워크스페이스 프로젝트 별 설정 관리법, 여러 프로젝트를 동시에 열어두고 작업하다가 파이썬 버전이 꼬이거나 테마가 섞여서 작업 집중력이 깨지는 상황에 정확히 필요한 해결책입니다. 여러 프로젝트를 번갈아 가며 작업할 때 전역 설정 하나만으로는 각 프로젝트가 요구하는 고유한 개발 환경을 온전히 분리하기 어렵기 때문입니다. 특히 최근 풀스택 개발이나 마이크로서비스 아키텍처가 일상화되면서, 하나의 에디터 창에서 레거시 자바 프로젝트와 최신 Node.js 프로젝트를 동시에 다뤄야 하는 경우가 빈번해졌습니다. 이때 인터프리터 경로나 린터(Linter) 규칙이 섞이면 디버깅 난이도가 급상승하고, 잘못된 환경에서 코드가 배포되는 치명적인 사고로 이어지기도 합니다. 이 글에서는 워크스페이스 파일을 생성하고 프로젝트별로 인터프리터와 확장 도구를 독립적으로 관리하여 개발 환경 충돌을 원천적으로 차단하는 VSCode 워크스페이스 프로젝트 별 설정 관리법을 단계별로 정리합니다.

함께 보면 좋은 글: 맥 스크린샷 앱 무료 대안 — 설정과 활용법 정리

전역 설정과 워크스페이스 설정의 동작 원리

VSCode의 설정 시스템은 계층 구조로 되어 있어 하위 설정이 상위 설정을 덮어쓰는 방식입니다. 기본적으로 settings.json 파일에 저장되는 사용자 설정(User Settings)은 모든 프로젝트에 공통으로 적용되지만, 워크스페이스 설정(Workspace Settings)은 특정 프로젝트나 폴더에서만 우선 적용됩니다. 이 구조를 이해하지 못하고 전역 설정만 수정하면, 프로젝트 A를 수정할 때 프로젝트 B의 환경까지 바뀌어버리는 불상사가 발생합니다. 예를 들어, 전역 설정에서 '파일 저장 시 자동 포맷팅'을 켜두면, 일부 프로젝트에서는 원치 않는 코드 스타일 변경이 강제될 수 있습니다.

이를 방지하기 위해 VSCode는 설정의 적용 범위를 다섯 단계(Default, User, Remote, Workspace, Folder)로 나눕니다. 가장 많이 혼동되는 부분이 'Workspace'와 'Folder' 설정의 차이입니다. 워크스페이스 설정은 .code-workspace 파일에 정의되며 여러 폴더를 포함하는 큰 단위의 프로젝트에 적용되는 반면, 폴더 설정은 프로젝트 내부의 .vscode/settings.json에 저장되어 해당 폴더에만 국한됩니다. 우선순위는 폴더 > 워크스페이스 > 사용자 > 기본값 순이므로, 프로젝트 전체의 공통 분위기는 워크스페이스에서, 특정 하위 모듈의 민감한 설정은 폴더 단위에서 제어하는 정교한 전략이 가능합니다.

예를 들어, macOS 환경에서 사용자 설정 파일은 기본적으로 ~/Library/Application Support/Code/User/settings.json 경로에 저장됩니다. 여기에 정의된 글꼴 크기나 테마는 기본값이지만, 워크스페이스 설정이 존재하면 해당 값이 우선시됩니다. Microsoft 공식 문서에 따르면 설정 우선순위는 워크스페이스 폴더 > 워크스페이스 > 사용자 > 기본값 순으로 적용되므로, 프로젝트별로 고유한 값을 지정하려면 워크스페이스 단계에서 설정을 정의해야 합니다. 만약 A 프로젝트에서는 글꼴을 14px, B 프로젝트에서는 16px을 쓰고 싶다면, 사용자 설정을 14px으로 두고 B 프로젝트 워크스페이스 설정에서만 16px으로 오버라이드(Override)하면 됩니다.

제가 운영 중인 백엔드 레거시 프로젝트는 Python 3.8을 사용하지만, 새로 시작하는 실험적인 프로젝트는 Python 3.11을 요구하는 경우가 많습니다. 전역 인터프리터를 3.8로 맞춰두면 새 프로젝트에서 계속 버전 호환성 경고가 뜨고, 반대로 3.11로 맞추면 레거시 코드가 실행되지 않습니다. 이때 워크스페이스별로 python.defaultInterpreterPath를 다르게 지정하면 창마다 완벽하게 격리된 환경을 제공받을 수 있습니다. 뿐만 아니라, 레거시 프로젝트에서는 엄격한 Flake8 린터를 적용하고, 프로토타이핑 프로젝트에서는 린터를 끄는 등 유연한 개발 문화를 지원하는 것이 가능해집니다.

Photo by Cláudio Emanuel on Pexels

VSCode 워크스페이스 파일 생성 및 저장 과정

설정을 분리하려면 먼저 프로젝트를 위한 워크스페이스 파일을 생성해야 합니다. 이 파일은 단순히 폴더를 열 때 생성되는 것이 아니라, 사용자가 명시적으로 저장해야 하는 프로젝트 단위의 설정 묶음입니다. 워크스페이스를 저장하면 .code-workspace 확장자를 가진 파일이 생성되며, 이 파일 안에는 해당 프로젝트에 포함될 폴더 경로와 프로젝트 적용 설정이 JSON 형태로 저장됩니다. 이 파일은 프로젝트의 루트 디렉토리에 저장하여 팀원들과 공유할 수도 있고, 로컬 개발 환경 폴더에 따로 보관하여 개인적인 설정 관리 용도로만 사용할 수도 있습니다.

이 과정을 통해 생성된 워크스페이스 파일은 이제부터 VSCode의 진입점 역할을 합니다. 다음부터는 폴더를 직접 열지 말고, 이 .code-workspace 파일을 더블 클릭하여 VSCode를 실행해야만 미리 정의해둔 격리된 환경이 활성화됩니다. 단순히 폴더를 열면 워크스페이스 설정이 로드되지 않으므로, 작업 시작 전 항상 올바른 워크스페이스가 로드되었는지 탭 제목을 확인하는 습관을 들이는 것이 중요합니다.

파이썬 버전과 인터프리터 프로젝트별 분리 설정

다양한 파이썬 프로젝트를 전환하며 겪는 가장 큰 고통은 인터프리터 버전 충돌입니다. 가상 환경(Virtual Environment)을 사용하더라도, VSCode가 매번 자동으로 정확한 venv나 conda 환경을 찾아주지 않는다면, 수동으로 선택해야 하는 번거로움이 발생합니다. 워크스페이스 설정 파일에 인터프리터 경로를 명시하면 이 문제를 근본적으로 해결할 수 있습니다. 이를 통해 프로젝트를 열자마자 정확한 가상 환경이 활성화되어, pip install로 설치된 라이브러리를 즉시 가져와 사용할 수 있습니다.

설정 방법은 앞서 생성한