바이브코딩에서 프로젝트를 왜 폴더 하나에 두나

무엇이 헷갈리나

사무 업무에선 폴더 안에 폴더를 겹겹이 만든다. '2026년 > 3분기 > 계약서 > 최종'처럼 깊이 파고드는 게 자연스럽다. 그래서 코딩을 처음 시작하면 프로젝트도 그렇게 폴더 안에 폴더로 정리하면 될 것 같다.

그런데 Claude Code 같은 AI 코딩 도구는 프로젝트 하나를 폴더 하나에 '평평하게' 두고, 그 폴더에서 작업을 시작하라고 한다. 왜 그럴까. 답은 하나다. 소프트웨어를 굴리는 세 가지 핵심 장치가 전부 '폴더'라는 같은 경계를 공유하기 때문이다.

먼저, 세 용어부터 — git·하네스·배포가 뭔가

git은 코드의 '버전 저장 도구'다. 지금 이 순간의 파일 상태를 통째로 찍어(커밋) 나중에 되돌리거나 비교할 수 있게 한다. 저장 단위 하나를 '리포(repository, 저장소)'라 부른다.

하네스(harness)는 AI가 잘 일하도록 프로젝트를 미리 세팅해 두는 것이다. 사람 신입에게 주는 온보딩 문서와 같다. 그 핵심이 CLAUDE.md·AGENTS.md라는 규칙 문서인데, AI가 그 폴더를 열면 자동으로 읽어 '이 프로젝트는 이런 거야, 이건 하지 마'를 매번 설명 안 해도 되게 한다.

배포(deploy)는 만든 코드를 인터넷에 올려 남이 볼 수 있게 하는 것이다. Vercel·Railway 같은 서비스가 대표적이다. 이 셋이 어떻게 폴더 하나로 묶이는지 아래에서 차례로 본다.

출발점: 파일시스템은 트리다

컴퓨터의 파일 구조는 나무(트리)를 뒤집어 놓은 모양이다. 위에서 아래로 가지가 뻗고, 폴더 하나는 그 나무의 '가지 하나 통째'를 뜻한다 — 그 폴더와 그 아래 모든 하위 폴더·파일이 한 덩어리다. 이걸 '닫힌 가지(subtree)'라고 한다.

이게 왜 중요하냐면, 폴더 하나가 '여기부터 여기까지가 한 묶음'이라는 경계를 공짜로 만들어 주기 때문이다. 뒤에 나오는 git·하네스·배포는 전부 '경계가 분명한 파일 묶음'을 필요로 하는데, 폴더가 그 경계를 이미 제공하고 있다. 그래서 바퀴를 새로 만들지 않고 폴더에 얹는다.

git: 폴더가 곧 리포다

git은 폴더 안에 숨은 .git 폴더를 하나 만들고, 그 .git의 부모 폴더를 '루트'로 잡는다. 그리고 루트 아래 전부를 추적 대상으로 본다. 즉 .git 하나 = 리포 하나 = 폴더 하나다.

커밋(스냅샷)은 '지금 이 폴더 아래 모든 파일의 상태'를 원자적으로, 즉 통째로 한 번에 찍는다. 경계가 없으면 '무엇을 찍을지'를 정의할 수 없다. 또 git 안에서 파일 위치는 전부 루트 기준 상대경로(src/app.js 같은)로 저장된다. 공통 루트, 즉 폴더가 없으면 이 상대경로 체계 자체가 성립하지 않는다. 그래서 리포는 폴더 하나가 설계상 필연이다.

하네스: 규칙은 폴더 루트에 앵커된다

AI 도구는 세션을 시작할 때 작업 폴더 루트의 CLAUDE.md·AGENTS.md를 자동으로 읽는다. 그래서 폴더만 제대로 열면 AI가 프로젝트를 '이해한 상태'로 시작한다 — 매번 스택·금지사항·검증 명령을 다시 설명할 필요가 없다.

규칙 로드는 덮어쓰기가 아니라 '누적'이다. 전역(~/.claude/CLAUDE.md) → 프로젝트 루트 → 하위 폴더 순으로 쌓인다. 아래로 갈수록 상위 규칙에 세부를 더한다. 그래서 폴더 구조가 곧 규칙의 적용 범위가 된다. 폴더가 규칙의 닻(anchor)인 셈이다. CLAUDE.md는 Claude 전용, AGENTS.md는 Codex·Gemini 등 다른 에이전트까지 공용 표준이라, 심볼릭 링크로 하나로 묶으면 어떤 AI를 쓰든 같은 규칙이 걸린다.

배포: git 커밋을 그대로 배포 산출물로 쓴다

Vercel 같은 배포 서비스는 git 리포 하나를 연결해 둔다. 그 리포에 push하면 웹훅(자동 신호)이 배포 서비스를 깨우고, 서비스는 그 커밋 시점의 리포를 통째로 내려받아 루트에서 빌드한 뒤 인터넷에 올린다.

여기서 배포는 바퀴를 새로 만들지 않는다. git 커밋이 이미 '코드의 특정 상태'를 완벽히 정의하고 있으니, 그 커밋을 그대로 배포 단위(산출물)로 재사용한다. 배포마다 커밋 해시(SHA)가 딱 붙고, 롤백은 옛 커밋을 다시 배포하는 것이다. push 한 번에 '버전 저장 + 규칙 적용 + 웹 반영'이 한꺼번에 도는 이유가 여기 있다.

다섯 축으로 정리

폴더 하나가 왜 그렇게 여러 역할을 겸하는지, 다섯 축으로 나란히 놓으면 한눈에 보인다. 모두 '경계 있는 파일 묶음'을 필요로 하고, 폴더가 그 경계를 준다는 점에서 하나로 이어진다.

권장 폴더 구조

그래서 실무 표준은 단순하다. 프로젝트는 폴더 안에 겹쳐 넣지 말고 나란히 두고, 각 프로젝트 루트에 .git과 CLAUDE.md를 두고, 그 루트에서 AI 작업을 시작한다. git 루트 = 규칙 문서 위치 = AI 시작 지점, 이 셋을 한 폴더에 정렬시키는 게 핵심이다.

반대로 프로젝트 폴더 안에 또 다른 독립 프로젝트를 중첩하면, 리포 안에 리포가 생겨 git 명령이 어느 리포 대상인지 꼬이고, AI를 잘못된 깊이에서 켜기 쉬워 규칙·검색 범위가 어긋난다.

workspace/
├── project-A/          ← 여기서 Claude 시작
│   ├── .git/           (버전관리 경계)
│   ├── CLAUDE.md       (하네스 규칙)
│   └── src/
├── project-B/          ← 여기서 Claude 시작
│   ├── .git/
│   ├── CLAUDE.md
│   └── src/
└── project-C/
    ├── .git/
    ├── CLAUDE.md
    └── src/

workspace/
└── project-A/
    ├── .git/
    ├── CLAUDE.md
    └── project-B/       ← 리포 안 리포 · cwd 혼선
        ├── .git/
        └── CLAUDE.md

그럼 폴더 안에 폴더는 절대 안 되나

오해는 없어야 한다. 한 프로젝트 '안에서' 폴더를 나누는 건 정상이고 권장된다. src/·docs/·tests/처럼 파일을 갈래로 정리하는 건 마음껏 해도 된다. 문제는 '독립 프로젝트(=경계)끼리' 겹쳐 넣는 것이다.

예외처럼 보이는 세 가지도 원칙을 깨지 않는다. monorepo는 리포 하나(폴더 하나) 안에 여러 패키지를 논리적으로만 나눈 것이라 리포는 여전히 하나다(배포는 Root Directory 설정으로 패키지별 지정). submodule은 리포 안에서 다른 리포를 '참조'만 하며 각자 독립 .git을 유지한다. worktree는 하나의 히스토리를 여러 폴더에 동시에 펼쳐 놓을 뿐 근원 .git은 하나다. 셋 다 '리포=폴더 하나' 원칙을 깨는 게 아니라 그 위에서 조합하는 방식이다.

한 줄 정리

모든 게 '경계 있는 파일 묶음'을 필요로 하고, 폴더가 그 경계를 가장 자연스럽게 준다. 그래서 git·하네스·배포가 바퀴를 새로 만들지 않고 폴더 하나에 다 올라탄다. 바이브코딩에서 '폴더 = 경계'를 이해하면, 도구가 왜 그렇게 동작하는지가 한 번에 풀린다.