바이브 코딩 개발 환경 구축하기 — WSL2·GitHub·Cloudflare 연동 가이드

AI로 웹사이트를 만드는 데 성공했는데, 다음 날 노트북을 바꾸거나 기능을 수정하려니 어디서부터 시작해야 할지 막막한 경우가 있습니다. 파일은 남아 있어도 어떤 버전이 정상 동작했는지 모르고, 배포는 어디에서 이루어지는지 기억나지 않을 수도 있습니다.

이 가이드는 그런 상황을 줄이기 위한 기본 작업 흐름을 설명합니다. Windows에서 WSL2 Ubuntu로 개발하고, Git으로 변경 이력을 남기고, GitHub에 저장한 뒤, Cloudflare가 Git 변경을 감지해 빌드·배포하도록 연결하는 방식입니다.

이것은 ONSEMO에서 활용하는 개발 방식 중 하나이지, 모든 사람에게 유일한 정답은 아닙니다. 기존 프로젝트의 언어, 빌드 방식, 보안 요구사항에 따라 조정해야 합니다.

시작하기 전에: 도구별 역할

도구	하는 일	기억할 점
WSL2·Ubuntu	Windows에서 Linux 개발 환경 사용	Windows와 완전히 격리된 보안 공간은 아님
Git	파일 변경 이력을 로컬 저장소에 기록	정상 작동 시점을 커밋해야 비교·복구하기 쉬움
GitHub	Git 저장소를 원격 보관하고 협업·동기화	코드를 복제해도 실행 환경까지 자동 복구되지는 않음
Codex CLI	코드 수정과 검증을 도와주는 AI 개발 도구	변경 내용과 명령 실행 권한을 직접 확인해야 함
Cloudflare	Git 연동을 통해 웹서비스 빌드·배포	push 성공과 운영 배포 성공은 다른 단계

목표 흐름은 다음과 같습니다.

Windows PC
   └─ WSL2 Ubuntu: 코드 작성·로컬 검증
       └─ Git commit → GitHub push
           └─ Cloudflare Git 연동 빌드·배포
               └─ 실제 공개 URL에서 최종 확인

1. Windows에서 WSL2 Ubuntu 준비하기

Windows 11 또는 지원되는 Windows 10 버전에서 관리자 권한 PowerShell을 열고 설치합니다. 기존에 WSL이 설치되어 있다면 먼저 설치 상태를 확인하고, 기존 배포판을 삭제하거나 덮어쓰지 마세요.

wsl --install

안내에 따라 Windows를 재시작하고 Ubuntu를 처음 실행하면 Linux 사용자 이름과 비밀번호를 설정합니다. PowerShell에서 배포판과 WSL 버전을 확인할 수 있습니다.

wsl --list --verbose
wsl --status

이제 Ubuntu 터미널에서 기본 도구를 점검합니다. 아래 명령은 PowerShell이 아니라 Ubuntu에서 실행합니다.

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

명령을 찾을 수 없다면 필요한 도구를 설치해야 합니다. 예를 들어 Git이 없는 Ubuntu에서는 다음과 같이 설치할 수 있습니다.

sudo apt update
sudo apt install git ca-certificates

Node.js와 npm은 프로젝트에서 요구하는 버전에 맞게 설치하세요. 프로젝트의 .nvmrc 또는 package.json을 먼저 확인하는 편이 안전합니다.

개발 파일은 Linux 사용자 홈 아래에서 시작하면 관리하기 편합니다.

mkdir -p ~/projects
cd ~/projects

주의: WSL2를 설치했다고 Windows의 개인 파일이 자동으로 차단되지는 않습니다. /mnt/c 등 Windows 드라이브 접근 가능 여부는 설정과 실행 권한에 따라 달라집니다. Codex의 샌드박스 권한도 별도로 확인해야 합니다.

Microsoft 공식 문서: WSL 설치

2. Git과 GitHub로 코드 관리하기

Git은 변경 이력을 기록하는 도구이고, GitHub는 그 Git 저장소를 원격으로 보관하는 서비스입니다. 두 가지의 역할을 구분하면 오류가 발생했을 때 무엇을 확인해야 하는지 명확해집니다.

먼저 Git 커밋에 표시할 작성자 정보를 설정합니다. 아래 이름과 이메일은 예시이므로 자신의 정보를 사용하세요. 공개 저장소에 개인정보 노출을 줄이고 싶다면 GitHub의 비공개 이메일 기능을 검토할 수 있습니다.

git config --global user.name "YOUR_DISPLAY_NAME"
git config --global user.email "YOUR_COMMIT_EMAIL"

GitHub에서 새 저장소를 만들고, 저장소 화면의 Code → SSH 또는 HTTPS에서 복제 주소를 확인합니다. SSH를 사용하려면 먼저 공개키를 GitHub 계정에 등록하고 인증을 준비해야 합니다. 기존 SSH 키가 있다면 임의로 덮어쓰지 마세요.

# SSH 인증을 이미 설정한 경우의 예시
ssh -T git@github.com
git clone git@github.com:YOUR_ACCOUNT/YOUR_REPO.git
cd YOUR_REPO

첫 연결에서 서버 지문을 확인하라는 안내가 나오면 GitHub 공식 문서에 제시된 지문과 대조하세요. 확인하지 않고 무조건 승인해서는 안 됩니다. HTTPS 방식이라면 복제 주소와 인증 방법이 달라집니다.

GitHub 공식 문서: 저장소 복제

GitHub 공식 문서: SSH 연결 확인

커밋으로 정상 상태 남기기

새 기능을 만들거나 기존 기능을 바꾸기 전후에 아래 상태를 확인합니다.

git status
git branch --show-current
git log --oneline -n 5

수정한 파일을 검토한 다음 이번 작업과 관련된 파일만 선택적으로 추가하고 커밋합니다.

git diff
git add README.md
git commit -m "docs: update project guide"
git push

여기서 README.md는 예시입니다. 실제 변경한 파일명을 지정해야 하며, 예시 파일을 수정하지 않았다면 커밋할 변경사항이 없을 수 있습니다. 다른 사람이 작업한 파일이나 인증정보를 실수로 함께 올리지 않도록 확인하세요.

3. AI가 수정한 뒤 잘 되던 기능이 멈췄다면?

바이브 코딩에서는 문서에 작업 원칙을 적어 두어도 AI가 수정한 코드 때문에 이전 기능이 예상과 다르게 동작할 수 있습니다. 이때 중요한 것은 'AI에게 다시 고쳐 달라'고 반복하기 전에 마지막으로 정상 동작하던 커밋과 현재 상태를 비교하는 것입니다.

# 최근 커밋 확인
git log --oneline -n 10

# 마지막 정상 동작 커밋의 해시를 찾은 뒤 변경 비교
git diff GOOD_COMMIT_HASH HEAD -- path/to/file

어느 파일에서 변경이 시작됐는지 확인한 다음 원인을 좁혀 가세요.

실전 팁: Git 변경 이력을 직접 분석하기 어렵다면 Codex에 이렇게 요청해 보세요. “마지막으로 정상 동작한 커밋과 현재 코드를 비교해 줘. 어느 커밋부터 어떤 파일과 코드가 바뀌었는지 찾아서 설명하고, 원인 후보를 좁혀 줘. 아직 코드를 수정하거나 되돌리지는 마.” Codex는 Git 기록과 변경 내역을 확인해 추적을 도와줄 수 있습니다. 다만 변경된 코드가 실제 오류의 원인인지는 테스트로 확인해야 합니다.

git restore, git reset --hard처럼 작업 내용을 잃을 수 있는 명령은 변경사항을 백업하고 영향을 이해하기 전에는 사용하지 않는 편이 안전합니다.

반드시 기억할 점은 정상 상태가 커밋되어 있어야 그 시점의 코드를 정확하게 비교하기 쉽다는 것입니다. Git이 자동으로 모든 작업 순간을 보관하는 것은 아닙니다.

이 경험을 개발 관점에서 풀어낸 글은 AI로 만든 프로그램, 노트북이 없어도 계속 개발할 수 있을까?에서 읽을 수 있습니다.

4. Codex CLI와 프로젝트 규칙 연결하기

Node.js와 npm이 준비되어 있고 현재 지원되는 실행 환경이라면 Codex CLI를 설치할 수 있습니다. 설치와 로그인 안내는 시간이 지나며 바뀔 수 있으므로 공식 문서를 우선 확인하세요.

npm install -g @openai/codex
codex --version

Codex를 실행할 때는 작업하려는 프로젝트 디렉터리에서 시작합니다. 먼저 AGENTS.md 같은 프로젝트 규칙과 현재 Git 변경사항을 읽게 하고, 변경 범위를 작게 지정하면 검토하기가 쉬워집니다.

cd ~/projects/YOUR_REPO
codex

AI가 생성한 코드는 자동으로 검증된 결과물이 아닙니다. Codex가 어떤 파일을 바꿨는지 확인하고, 로컬 빌드와 테스트를 수행한 뒤 Git에 반영하세요. 권한이나 네트워크 접근을 무조건 허용하지 말고 필요한 범위를 검토해야 합니다.

OpenAI 공식 Codex 문서

5. Cloudflare에 Git 자동 배포 연결하기

이 단계는 이미 로컬에서 정상 빌드되는 웹 프로젝트를 전제로 합니다. HTML 파일만 있는 정적 사이트와 빌드가 필요한 Node.js 앱은 Cloudflare 설정이 서로 다릅니다. Cloudflare Workers 또는 Pages 중 현재 프로젝트에 맞는 방식을 선택해야 합니다.

Cloudflare 대시보드에서 Workers & Pages의 해당 프로젝트를 열고, GitHub 저장소와 Production 브랜치를 연결합니다. 기존 프로젝트를 연동할 때는 연결된 저장소·브랜치·빌드 설정을 먼저 확인하세요. 메뉴 위치와 명칭은 서비스 업데이트에 따라 달라질 수 있습니다.

Workers Builds를 사용하는 경우 점검할 항목은 다음과 같습니다.

GitHub 연결 권한이 해당 저장소에 부여되어 있는가?
Production 브랜치가 실제 배포할 브랜치(예: main)인가?
저장소의 빌드 명령과 출력 디렉터리가 실제 프로젝트와 일치하는가?
Workers 프로젝트라면 wrangler.jsonc 또는 다른 지원 설정 파일이 실제 Worker 및 정적 자산 경로를 가리키는가?
환경 변수와 바인딩이 Cloudflare에 별도로 안전하게 설정되어 있는가?

연동이 완료되면 로컬에서 확인한 변경을 GitHub에 push하고, Cloudflare의 Builds 또는 Deployments에서 해당 커밋이 성공적으로 배포됐는지 확인합니다. 이 가이드에서는 로컬에서 직접 배포 명령을 실행하지 않습니다. Git 연동 빌드 시스템이 내부적으로 배포 도구를 사용하는 것과 로컬 PC에서 수동 배포하는 것은 구분해야 합니다.

Cloudflare 공식 문서: Workers Git 연동

Cloudflare 공식 문서: Workers Static Assets

6. GitHub push가 성공했는데 사이트는 그대로라면?

Git push 성공은 원격 저장소에 소스코드가 올라갔다는 의미이지, 운영 사이트의 배포가 끝났다는 뜻은 아닙니다. 실제로 두 결과가 다르게 보일 때는 다음 순서로 확인하세요.

확인 단계	확인할 항목	다음 행동
1. GitHub	커밋이 올바른 저장소와 브랜치에 있는가?	Commit과 브랜치 확인
2. Cloudflare	같은 커밋의 빌드가 시작됐는가?	Git 연동·브랜치 설정 확인
3. 빌드 로그	빌드와 배포가 성공했는가?	오류 로그의 최초 실패 지점 확인
4. Worker URL	생성된 새 버전이 응답하는가?	운영 도메인 결과와 비교
5. 사용자 도메인	도메인이 올바른 Worker를 가리키는가?	커스텀 도메인·라우트 확인
6. 캐시	이전 응답이 캐시되어 있는가?	응답 헤더와 캐시 설정 확인

'사이트가 예전처럼 보인다'는 사실만으로 캐시 문제라고 단정하면 안 됩니다. Git 연결, 배포 대상, 도메인 라우트, 캐시를 나누어 확인해야 합니다. 원인이 확인되기 전에 DNS나 배포 설정을 무작정 바꾸는 것도 피하세요.

7. 다른 컴퓨터에서 작업을 다시 시작하기

기존 컴퓨터가 없어도 GitHub에 기록된 소스는 새 개발 환경으로 가져올 수 있습니다.

mkdir -p ~/projects
cd ~/projects
git clone git@github.com:YOUR_ACCOUNT/YOUR_REPO.git
cd YOUR_REPO

하지만 소스코드 외에 Node.js 버전, 패키지 의존성, 환경 변수, 외부 서비스 인증, 로컬 개발 도구도 필요할 수 있습니다. 프로젝트 README와 설정 파일을 확인한 뒤 해당 프로젝트에 맞는 설치·빌드·테스트 명령을 실행하세요.

비밀키나 .env 파일을 GitHub에 넣어 문제를 해결하려 하지 마세요. 인증정보는 권한이 부여된 안전한 저장 경로에서 새 환경으로 설정해야 합니다.

8. 발행 전 점검 체크리스트

WSL2와 Ubuntu를 설치하고 실행 버전을 확인했다.
개발 파일과 개인 파일의 경계를 정하고 접근 권한을 점검했다.
GitHub 저장소를 복제하고 현재 브랜치와 변경사항을 확인했다.
정상 동작 상태를 Git 커밋으로 남겼다.
로컬 빌드·테스트가 통과했고 변경된 파일을 검토했다.
Cloudflare의 저장소·브랜치·빌드 설정이 올바른지 확인했다.
Git push 후 해당 커밋의 Production 배포 성공 여부를 확인했다.
Worker URL과 실제 공개 도메인에서 결과를 확인했다.
인증정보와 개인 파일이 공개 저장소에 포함되지 않았음을 확인했다.

마무리: 개발을 이어갈 수 있는 환경이 중요하다

바이브 코딩에서 AI의 도움으로 코드를 빠르게 만드는 일은 출발점입니다. 중요한 것은 변경이 반복되어도 정상 상태를 찾을 수 있고, 다른 컴퓨터에서도 작업을 이어갈 수 있으며, 운영 사이트에 올라간 결과를 직접 확인할 수 있는 환경입니다.

이번 가이드는 그 전체 흐름을 한 번에 살펴보는 첫 안내서입니다. SSH 인증, WSL2 접근 권한, Cloudflare 배포 오류를 깊이 있게 해결하는 방법은 각각 검증된 후속 가이드로 분리할 예정입니다.

'왜 이런 환경을 만들게 됐을까?'가 궁금하다면 ONSEMO 첫 번째 개발 이야기를 함께 읽어 보세요.