사전 준비

이 단계는 한 번만 하면 됩니다. 이미 깔려 있는 항목은 건너뛰면 됩니다.

처음 보는 명령이 절반 이상이라면 비개발자용 시작의 “어떤 분을 염두에 두고 썼나” 단락을 한 번 보고 와 주세요. 매뉴얼이 가정하는 학습 수준이 거기 박혀 있습니다.

운영체제별 차이

항목	macOS	Windows	Linux
사용하는 터미널	`Terminal.app` 또는 iTerm2	WSL2 위의 Ubuntu 권장. PowerShell도 가능하지만 안내가 길어집니다.	배포판이 제공하는 셸
검증 상태	검증됨	WSL2 먼저 깐 다음 그 안에서 모든 명령 실행	검증됨

Windows에서는 WSL2 설치 안내를 먼저 끝낸 다음 이쪽으로 돌아오세요. 이 매뉴얼의 모든 명령은 WSL2 위 Ubuntu 셸 안에서 실행한다고 가정합니다.

1) Node.js 20 이상

macOS와 Linux는 nvm 권장

터미널을 열고 한 줄씩 실행합니다.

# nvm (Node Version Manager) 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 새 터미널을 열거나, 다음 두 줄을 붙여 넣어 nvm을 지금 바로 활성화
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Node 20 설치 후 사용
nvm install 20
nvm use 20

설치 검증

node --version    # v20.x.x 가 출력되어야 정상
npm --version     # 10.x.x 비슷한 숫자가 출력되면 정상

둘 중 하나라도 아무것도 출력되지 않는다면 06-troubleshooting.md의 “Node가 설치되지 않습니다” 항목으로 갑니다.

새 터미널에서 node --version 이 다시 안 떠 있다면 nvm 활성화 두 줄이 셸 시작 파일에 안 들어간 상태입니다. macOS와 Linux 기본 셸 별로 자리가 다릅니다. zsh 라면 ~/.zshrc, bash 라면 ~/.bashrc. 그 파일을 열고 nvm 설치 출력 끝부분에 보였던 export NVM_DIR=... 두 줄이 들어가 있는지 확인하세요. 없으면 손으로 붙여 넣고 새 터미널을 엽니다.

2) git

macOS

xcode-select --install

이 명령은 git만 따로 깔지 않고 Apple의 Command Line Tools 묶음을 설치합니다. 작은 다이얼로그 창이 떠서 동의를 받고 진행합니다. git이 이미 깔려 있으면 안내 메시지만 한 줄 띄우고 끝납니다. 보통 5분 안쪽이면 끝납니다.

Linux — Ubuntu와 Debian

sudo apt update && sudo apt install -y git

WSL2 위 Ubuntu에서도 같은 명령을 그대로 씁니다. WSL2의 Ubuntu는 일반 Ubuntu와 패키지 시스템이 동일합니다.

설치 검증

git --version    # git version 2.x.x

git에 본인 정보 한 번 등록

git config --global user.name "Your Name"
git config --global user.email "your@example.com"

이 이름과 이메일이 앞으로 만드는 커밋의 작성자로 박힙니다. 회사 메일과 분리하고 싶다면 나중에 저장소별로 따로 설정하면 되니, 지금은 그냥 사용 가능한 정보를 넣어 두면 됩니다.

3) Chrome과 개발자 모드

Chrome은 이미 설치돼 있다고 가정합니다. 한 가지만 켜 두면 됩니다.

주소창에 chrome://extensions 를 입력합니다.
우측 상단의 개발자 모드 토글을 켭니다.
토글이 켜진 상태여야 확장 폴더나 zip을 직접 로드해 테스트할 수 있습니다.

개발자 모드 토글은 페이지 우측 상단에 있습니다. 토글이 파란색이 되면 켜진 상태이고, 그 순간 좌측 상단에 “압축해제된 확장 프로그램을 로드합니다” 같은 버튼 세 개가 새로 나타납니다. 그 버튼이 안 보이면 토글이 아직 꺼진 상태이거나, 페이지를 새로고침하지 않은 경우입니다.

Chrome 버전이 114 이상이어야 sidepanel이 동작합니다. chrome://version 을 주소창에 입력해 확인하세요. 옛 버전이라면 Chrome 자동 업데이트를 한 번 돌려 둡니다.

4) Claude Code

공식 설치 안내는 docs.claude.com/ko/docs/claude-code/quickstart 에 있습니다. 설치 후 claude 를 한 번 실행해 로그인하거나 API 키를 등록합니다.

claude --version

버전 번호가 출력되면 준비 완료입니다. Claude Code 대신 OpenAI Codex CLI를 써도 됩니다. 그 경우 진입점은 저장소 루트의 AGENTS.md 이고 같은 흐름이 그대로 적용됩니다. 처음이라면 Claude Code를 권합니다.

5) 선택 사항 — 코드 에디터

코드가 만들어지는 모습을 보고 싶다면 VS Code 가 무난합니다. AI가 코드를 다 써 주기 때문에 에디터가 꼭 필요하지는 않습니다. 다만 방금 무슨 일이 일어났는지 들여다보고 싶을 때는 있는 편이 편합니다.

다섯 항목이 모두 자리를 잡았다면 02-clone-and-install.md로 갑니다.