13장. 개발 환경 준비하기

처음 개발을 시작할 때 가장 먼저 만나는 벽은 문법이 아니라 설치입니다. 이상하게도 코딩은 아직 시작도 안 했는데, 벌써 뭔가 어려워 보입니다. 화면에는 영어가 가득하고, 터미널은 낯설고, 설치 파일은 하나가 아니라 여러 개입니다. 이때 가장 많이 드는 생각은 대개 비슷합니다.

"내가 벌써 잘못하고 있는 건 아닐까?"

하지만 걱정하지 않아도 됩니다. 개발 환경 준비는 실력을 증명하는 시험이 아니라, 작업할 책상을 정리하는 일에 가깝습니다. 책상이 흔들리면 공부가 싫어지듯, 개발 환경이 어설프면 코딩이 무섭게 느껴집니다. 그래서 이 장의 목표는 단순합니다. 실습에 필요한 기본 도구를 무리 없이 준비하고, 컴퓨터가 '이제 개발할 준비가 됐다'고 말하는 상태까지 가는 것입니다.

개발 환경은 무엇을 뜻할까

개발 환경은 코드를 쓰고, 실행하고, 수정하고, 결과를 확인하는 데 필요한 도구들의 묶음입니다. 요리를 비유로 들면, 레시피만 있다고 식사가 만들어지지 않듯이, 개발도 아이디어만으로는 진행되지 않습니다. 칼, 도마, 불, 냄비가 필요하듯 우리에게도 기본 장비가 필요합니다.

이번 장에서 준비할 것은 크게 여섯 가지입니다.

• 웹 브라우저

• 코드 에디터

• 터미널

• Node.js와 npm

• Git

• GitHub 계정

이 여섯 가지가 준비되면, 다음 장부터는 프로젝트를 만들고 파일 구조를 살펴보며 실제 개발 흐름으로 자연스럽게 들어갈 수 있습니다.

왜 처음 설정이 그렇게 중요할까

초보자가 개발을 포기하는 이유 중에는 "코드가 어려워서"보다 "시작도 전에 막혀서"가 꽤 많습니다. 특히 설치 단계에서 자꾸 오류가 나면, 사람은 금방 이렇게 오해합니다.

"나는 원래 이쪽이 안 맞는가 보다."

사실은 반대인 경우가 많습니다. 설치는 원래 자잘하게 막히는 구간입니다. 프로그램 설치 뒤에 터미널을 다시 열어야 할 수도 있고, 명령어 경로가 아직 적용되지 않았을 수도 있고, 운영체제마다 설치 방식이 조금씩 다를 수도 있습니다. 그러니 설치 중 한 번 막혔다고 해서 실력이 부족한 것이 아닙니다. 그냥 컴퓨터가 아직 새 도구를 낯설어하는 중일 뿐입니다.

그래서 중요한 것은 완벽한 이해보다 안정적인 순서입니다. 이 장에서는 복잡한 이론보다 "무엇을 먼저 깔고, 무엇으로 확인하고, 어디서 자주 막히는지"에 집중하겠습니다.

먼저 준비할 도구들 한눈에 보기

브라우저는 우리가 만든 웹 서비스를 확인하는 창입니다. 단순히 보기만 하는 도구가 아니라, 오류를 확인하고 화면을 검사하는 도구이기도 합니다. 크롬이나 엣지처럼 비교적 널리 쓰이는 브라우저 하나를 최신 버전으로 준비해두면 충분합니다.

코드 에디터는 코드를 적는 작업 공간입니다. 이 책에서는 VS Code를 기준으로 설명합니다. VS Code는 설치가 쉽고, 확장 기능이 많고, 터미널과 디버깅 기능을 함께 쓰기 좋아서 입문자에게 특히 편합니다.²

터미널은 텍스트 명령으로 컴퓨터에게 일을 시키는 창입니다. 처음 보면 검은 화면처럼 보여도, 실제로는 복사해서 붙여 넣고 엔터를 누르는 일부터 시작하면 됩니다. 터미널은 거대한 해커 장비가 아니라, 개발자가 쓰는 리모컨이라고 생각하면 됩니다.¹

Node.js는 자바스크립트를 브라우저 밖에서도 실행하게 해주는 실행 환경입니다. 앞으로 만들 Next.js 프로젝트도 이 위에서 돌아갑니다. 그리고 npm은 Node.js와 함께 쓰는 패키지 관리자입니다. 쉽게 말해, 개발에 필요한 재료를 설치해주는 도구입니다.¹

Git은 작업 기록을 안전하게 남기는 도구입니다. 지금은 "내 작업을 저장하고 되돌릴 수 있게 해주는 안전장치" 정도로 이해하면 충분합니다. 자세한 이야기는 뒤 장에서 하겠지만, 설치는 지금 해두는 편이 좋습니다. 특히 Windows에서 나중에 Claude Code를 네이티브로 사용할 계획이라면 Git for Windows가 필요합니다.³

GitHub는 Git으로 관리한 코드를 인터넷에 올려두는 공간입니다. 아직은 협업보다 백업 창고에 가깝게 생각해도 됩니다.

추천 설치 순서

한 번에 이것저것 깔다 보면 어디서 꼬였는지 알기 어려워집니다. 그래서 다음 순서를 권합니다.

• 브라우저 확인 또는 업데이트

• VS Code 설치

• 터미널 열기 연습

• Git 설치

• Node.js 설치

• 버전 확인 명령어 실행

• GitHub 계정 만들기 또는 로그인

이 순서의 장점은 간단합니다. 눈에 보이는 도구부터 준비하고, 그다음 개발 도구로 들어가며, 마지막에 실제로 동작하는지 확인하게 됩니다. 초보자에게는 이 흐름이 훨씬 덜 무섭습니다.

브라우저와 VS Code부터 준비하자

가장 먼저 할 일은 브라우저를 하나 정하고 최신 상태인지 확인하는 것입니다. 크롬, 엣지, 파이어폭스 중 무엇이든 괜찮지만, 책의 실습 화면과 가장 비슷하게 따라가고 싶다면 크롬이나 엣지를 추천합니다. 중요한 것은 브랜드가 아니라 업데이트 상태입니다. 브라우저가 오래되면 화면이나 개발자 도구가 예상과 다르게 보일 수 있습니다.

그다음에는 VS Code를 설치합니다. 설치가 끝나면 바로 복잡한 확장 기능부터 찾지 말고, 먼저 프로그램이 잘 켜지는지 확인하세요. 폴더를 하나 열고, 왼쪽에 파일 목록이 보이는지, 아래쪽에 터미널을 열 수 있는지 보는 것만으로도 충분합니다. VS Code는 통합 터미널을 제공해서, 편집기와 터미널을 오가며 작업하기가 쉽습니다.²

처음에는 꾸미는 데 시간을 쓰지 마세요. 글꼴, 테마, 아이콘, 애니메이션보다 중요한 것은 딱 하나입니다. 파일을 열고 저장할 수 있는가입니다. 개발 초반에는 예쁜 작업실보다 흔들리지 않는 작업실이 더 중요합니다.

터미널은 무서운 창이 아니라 확인 창이다

터미널을 처음 열면 괜히 긴장됩니다. 하지만 실제로는 개발을 시작하기 전에 도구가 잘 설치되었는지 확인하는 데 가장 많이 씁니다. 터미널은 텍스트 기반 창이고, 운영체제마다 여는 방법이 조금씩 다릅니다.¹

• Windows: PowerShell을 열면 됩니다.

• macOS: Terminal 앱을 열면 됩니다.

• Linux: Terminal 앱을 열면 됩니다.

처음에는 명령어를 외울 필요가 없습니다. 이 장에서 기억할 것은 세 가지뿐입니다.

node --version
npm --version
git --version

이 세 줄은 "설치가 됐는지 확인하는 버튼"이라고 생각하면 됩니다. 버전 번호가 보이면 성공이고, command not found나 비슷한 메시지가 보이면 아직 설치가 덜 되었거나 터미널을 다시 열어야 할 가능성이 큽니다.

Git 설치하기

Git은 나중에 배우는 도구처럼 보이지만, 실제로는 초반부터 깔아두는 편이 마음이 편합니다. 실수했을 때 되돌릴 수 있다는 사실만으로도 개발이 훨씬 덜 무섭기 때문입니다.

운영체제별로 가장 간단한 방법만 잡아보면 이렇습니다.¹

Windows

winget install --id Git.Git -e --source winget

설치가 끝나면 PowerShell을 완전히 닫았다가 다시 열고 아래 명령으로 확인합니다.

git --version

macOS

Homebrew를 이미 사용하고 있다면 다음처럼 설치할 수 있습니다.

brew install git

설치 후 확인합니다.

git --version

Linux

Ubuntu 계열이라면 보통 다음 명령으로 시작하면 됩니다.

sudo apt update && sudo apt install git

설치 후 확인합니다.

git --version

Git이 설치되면 일단 여기까지만으로 충분합니다. 사용자 이름과 이메일 설정, 브랜치, 커밋 같은 이야기는 뒤 장에서 차근차근 다룰 것입니다. 지금은 "내 컴퓨터에 Git이라는 안전벨트를 달았다"는 감각만 있으면 됩니다.

Node.js와 npm 설치하기

이제 실습의 심장 역할을 할 Node.js를 설치할 차례입니다. Node.js는 앞으로 우리가 실행할 웹 프로젝트의 바닥 엔진입니다. npm은 그 엔진에 필요한 부품을 가져다주는 도구입니다.

여기서 중요한 원칙은 하나입니다. 가능하면 최신 실험 버전보다 LTS 버전을 쓰는 것입니다. LTS는 오래 지원되는 안정 버전이라는 뜻입니다. 초보자에게는 새롭고 빠른 버전보다 덜 흔들리는 버전이 훨씬 좋습니다.¹

Windows에서는 fnm 사용을 추천한다

Windows에서는 fnm 같은 버전 관리 도구를 쓰면 편합니다. 버전 관리 도구는 Node.js를 설치하고 바꾸는 일을 쉽게 해주는 보조 도구라고 생각하면 됩니다.¹

winget install Schniz.fnm
fnm use --install-if-missing 24
node --version
npm --version

버전 번호가 잘 나오면 성공입니다. 만약 fnm 명령이 인식되지 않으면, 대부분은 터미널을 다시 열면 해결됩니다.

macOS와 Linux에서는 nvm이 편하다

macOS나 Linux에서는 nvm을 많이 사용합니다.¹

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

설치가 끝나면 터미널을 완전히 닫고 다시 열어 주세요. 그다음 아래처럼 진행합니다.

nvm install --lts
node --version
npm --version

여기서 많은 초보자가 한 번 멈춥니다. "왜 설치는 끝났는데 명령어가 안 되지?" 이유는 단순합니다. 설치 프로그램이 새 설정을 적용했지만, 지금 열려 있는 터미널은 그 사실을 아직 모르는 상태이기 때문입니다. 새 터미널을 열면 인식되는 경우가 많습니다.²

VS Code에서 터미널까지 이어 붙이기

이제 설치한 도구들이 서로 자연스럽게 연결되는지 확인해볼 차례입니다. VS Code를 열고 빈 폴더 하나를 연 뒤, 메뉴에서 터미널을 열어 보세요. VS Code는 통합 터미널을 제공하므로, 에디터 안에서 바로 명령어를 실행할 수 있습니다.²

이 감각이 중요합니다. 앞으로의 작업은 대부분 이런 흐름으로 진행됩니다.

파일을 연다. 코드를 쓴다. 저장한다. 아래 터미널에서 실행한다. 브라우저에서 확인한다.

한 번 익숙해지면 생각보다 단순합니다. 개발이 갑자기 거대한 기술처럼 보이는 이유는 도구가 많아서이지, 매 순간의 행동이 복잡해서는 아닙니다.

GitHub 계정도 미리 준비해두자

GitHub 계정은 아직 깊게 다루지 않아도 되지만, 지금 만들어두면 다음 장들이 부드럽게 이어집니다. 이미 계정이 있다면 로그인만 확인하면 되고, 없다면 새로 만들면 됩니다.

여기서 중요한 팁이 하나 있습니다. 앞으로 Git 설정에 쓸 이메일과 GitHub 계정 이메일은 가능하면 같게 맞춰두세요. 나중에 커밋 기록이 GitHub 계정과 잘 연결되는 데 도움이 됩니다.¹

아직 SSH 키 연결까지는 하지 않아도 괜찮습니다. 그것은 Git과 GitHub를 본격적으로 다루는 장에서 안전하게 따라가면 됩니다.

첫 번째 성공 경험 만들기

도구를 설치했다면, 이제 정말 중요한 확인을 해봅시다. 작은 파일 하나를 만들고 직접 실행해보는 것입니다. 설치가 끝났다는 사실보다, 내 손으로 실행됐다는 경험이 더 큰 자신감을 줍니다.

먼저 새 폴더를 하나 만듭니다.

mkdir vibe-test
cd vibe-test

이제 VS Code로 이 폴더를 열어봅니다.

code .

만약 code .가 작동하지 않아도 괜찮습니다. 그럴 때는 VS Code를 직접 열고 Open Folder로 방금 만든 폴더를 선택하면 됩니다.

그다음 app.js 파일을 만들고 아래 한 줄을 적습니다.

console.log("Hello, vibe coding!");

저장한 뒤 터미널에서 실행합니다.

node app.js

화면에 Hello, vibe coding!가 보이면 성공입니다. 아주 작은 출력 같지만, 사실 이 한 줄에는 중요한 의미가 들어 있습니다. 에디터가 열렸고, 파일이 저장됐고, Node.js가 실행됐고, 터미널이 결과를 보여준 것입니다. VS Code에서 파일을 열고 통합 터미널로 Node.js 프로그램을 실행하는 기본 흐름은 이후 웹 개발에서도 그대로 이어집니다.²

자주 막히는 지점은 정해져 있다

설치가 꼬였을 때는 대개 비슷한 패턴입니다. 그러니 막혔을 때도 너무 놀라지 마세요. 아래 항목을 차례로 확인하면 대부분 해결됩니다.

• 설치 후 명령어가 인식되지 않으면 터미널을 완전히 닫고 다시 연다.

• 그래도 안 되면 컴퓨터를 한 번 재시작한다.

• node --version, npm --version, git --version 중 무엇이 안 되는지 하나씩 따로 확인한다.

• VS Code가 열리지만 code .가 안 되면, 일단 프로그램 안에서 폴더를 직접 연다.

• 설치 과정에서 버전 번호보다 "정상 실행 여부"를 우선한다.

특히 초보자는 여러 문제를 한꺼번에 고치려다 더 헷갈리기 쉽습니다. 그럴 때는 증상을 나누어 보는 것이 좋습니다. Git만 안 되는지, Node만 안 되는지, VS Code만 안 되는지 따로 보면 의외로 금방 풀립니다.

그래도 로컬 설정이 너무 어렵다면

정말 이상하게 내 컴퓨터에서만 계속 막히는 날도 있습니다. 그런 날에는 괜히 자존심을 걸지 않아도 됩니다. 개발은 우회로를 찾는 능력도 중요합니다.

그럴 때 쓸 수 있는 대안 중 하나가 GitHub Codespaces 같은 클라우드 개발 환경입니다. 브라우저 안에서 미리 준비된 개발 환경을 열 수 있어서, 로컬 설치가 꼬였을 때 임시 탈출구로 좋습니다. 기본 컨테이너에 Node.js, npm, git 같은 도구가 이미 들어 있는 경우가 많아 시작 장벽을 낮춰 줍니다.⁴

물론 이 책은 기본적으로 로컬 환경을 기준으로 진행합니다. 하지만 기억해두세요. 목표는 고집스럽게 설치 화면과 싸우는 것이 아니라, 서비스를 만드는 것입니다. 길이 막히면 잠깐 옆길로 가도 괜찮습니다.

오늘 여기까지 되면 충분하다

이번 장이 끝났을 때 아래 상태라면 아주 잘 따라온 것입니다.

• 브라우저가 최신 상태다.

• VS Code가 설치되어 있고 폴더를 열 수 있다.

• 터미널을 열 수 있다.

• git --version이 동작한다.

• node --version과 npm --version이 동작한다.

• app.js 파일을 만들어 node app.js로 실행해봤다.

• GitHub 계정을 만들었거나 로그인할 수 있다.

이 정도면 이제 개발을 시작할 바닥 공사는 끝났습니다. 아직 서비스를 만든 것은 아니지만, 서비스가 태어날 작업실은 완성된 셈입니다.

다음 장에서는 이 바닥 위에 실제 프로젝트를 만들고, 폴더와 파일들이 어떤 의미를 가지는지 살펴보겠습니다. 이제부터는 진짜로 손이 바빠지기 시작합니다.

참고

¹Local Web Development Setup Guide

²Node.js tutorial in Visual Studio Code

³Advanced setup - Claude Code Docs

⁴Setting up a Node.js project for GitHub Codespaces