왜 이 두 파일이 첫날인가
바이브 코딩(코드를 직접 쓰지 않고 AI에게 시켜 소프트웨어를 만드는 방식)으로 뭔가를 처음 만들면 대개 순서가 이렇다. AI에게 시켜 화면을 만들고, 클로드나 챗GPT의 API를 붙여 기능을 넣고, 잘 도니까 GitHub(코드를 올려 보관하고 공유하는 곳)에 올린다. 사고는 마지막 단계에서 난다.
AI가 짜준 코드에는 API 키가 그대로 박혀 있는 경우가 많다. sk-ant-… 이나 sk-… 로 시작하는 그 긴 문자열이다. 화면에서는 아무 문제 없이 돌아가니 그대로 두게 된다. 그런데 GitHub 공개 저장소는 말 그대로 누구나 볼 수 있고, 새로 올라온 코드에서 키 형태의 문자열만 찾아 긁어가는 자동 스캐너가 상시 돌고 있다. 사람이 뒤지는 게 아니라 기계가 훑기 때문에 노출은 분 단위다.
남의 손에 들어간 키로 API를 호출하면 요금은 키 주인에게 청구된다. 클라우드 계정 키였다면 남의 서버를 띄우는 데까지 쓰인다. 그래서 이 두 파일은 '나중에 보안 챙길 때' 만드는 게 아니라 프로젝트를 시작하는 날 만드는 파일이다.
.env란 무엇인가 — 값을 코드 밖으로 빼는 파일
.env는 environment(환경)의 줄임말이다. 프로젝트 폴더 맨 위에 두는 평범한 글자 파일이고, 안에는 '이름=값' 형식으로 한 줄에 하나씩 적는다. 여기 담는 건 API 키, 데이터베이스 비밀번호, 외부 서비스 토큰처럼 코드에 박히면 안 되는 값이다.
코드는 값을 직접 갖지 않고 이름으로 꺼내 쓴다. 자바스크립트면 process.env.이름, 파이썬이면 os.environ의 이름으로 읽는다. 이렇게 두면 코드에는 값이 아니라 이름만 남는다. 아래가 실제 차이다.
// 나쁜 예 — 키가 코드에 그대로 박혀 있다
const key = "sk-ant-api03-9f2b7c...";
fetch(url, {
headers: { "x-api-key": key },
});
// 이 파일이 GitHub에 올라가면 키도 같이 공개된다
// 좋은 예 — 값은 .env에서 꺼내 쓴다
const key = process.env.ANTHROPIC_API_KEY;
fetch(url, {
headers: { "x-api-key": key },
});
// 코드에는 이름만 남고, 실제 값은 저장소에 올라가지 않는다# 이름=값, 한 줄에 하나씩. 따옴표는 보통 필요 없다
ANTHROPIC_API_KEY=sk-ant-api03-9f2b7c...
DATABASE_PASSWORD=b8Kd2mQx.gitignore란 무엇인가 — 올리지 말 파일 목록
깃(git)은 폴더 안 파일이 어떻게 바뀌었는지 이력을 기록하는 도구이고, GitHub은 그 기록을 인터넷에 올려두는 곳이다. 깃은 기본적으로 폴더 안의 모든 파일을 기록 대상으로 본다. 그래서 아무 조치도 하지 않으면 .env도 함께 올라간다.
.gitignore는 그 예외 목록이다. 프로젝트 폴더 맨 위에 두고, 올리지 말 파일과 폴더 이름을 한 줄에 하나씩 적는다. 여기 적힌 것은 깃이 아예 없는 셈 친다.
# 비밀이 담긴 파일 — 절대 올리지 않는다
.env
.env.local
.env.*.local
# 언제든 다시 받을 수 있는 것들 — 올릴 이유가 없다
node_modules/
.next/
dist/
build/
# 운영체제·편집기가 만드는 찌꺼기
.DS_Store
*.log.env.example — 남에게는 이름표만 준다
혼자 쓰면 .env 하나로 끝나지만, 다른 사람과 같이 하거나 다른 컴퓨터에서 이어 작업하면 문제가 생긴다. .env는 저장소에 안 올라가니 받는 쪽에는 그 파일이 아예 없고, 어떤 값이 필요한지도 알 수 없다.
그래서 .env.example을 함께 둔다. 값은 비우고 이름만 적어 둔 견본이다. 비밀이 아니니 이 파일은 저장소에 올린다. 받는 사람은 이걸 복사해 이름을 .env로 바꾸고 자기 값을 채우면 된다.
여기에 실제 값을 적어두면 .env를 막은 의미가 사라진다. 견본에는 항상 빈 값이나 형식만 남긴다.
# 값은 비워 둔다. 어떤 이름이 필요한지만 알려주는 견본이다
ANTHROPIC_API_KEY=
DATABASE_PASSWORD=이미 올렸다면 — 삭제가 아니라 교체다
가장 흔한 착각이 여기 있다. 키가 올라간 걸 뒤늦게 알고 .gitignore에 .env를 추가한 뒤 안심하는 경우다. 소용없다. .gitignore는 '아직 기록에 없는 파일을 앞으로도 기록하지 마라'는 뜻일 뿐, 이미 커밋된 파일은 계속 추적된다. 게다가 깃은 과거 이력을 통째로 들고 다니므로, 지금 파일을 지워도 예전 커밋을 열면 키가 그대로 보인다.
그래서 순서가 정해져 있다. 첫째, 그 키를 발급처(Anthropic·OpenAI·AWS 등) 콘솔에서 폐기하고 새 키를 발급받는다. 노출된 키는 이미 남의 손에 있다고 가정한다. 둘째, 추적에서 뺀다. 셋째, 새 키는 .env에만 넣는다.
# 1) 발급처 콘솔에서 그 키를 폐기하고 새 키를 발급받는다 — 가장 먼저
# 2) 추적 목록에서 뺀다 (내 컴퓨터의 파일은 그대로 남는다)
git rm --cached .env
# 3) .gitignore에 .env가 있는지 확인하고 커밋한다
git commit -m "chore: stop tracking .env"
# 과거 커밋에는 옛 키가 그대로 남아 있다 — 그래서 1번이 먼저다바이브 코딩에서 하지 말아야 할 것
입문자가 반복해서 밟는 지뢰는 종류가 많지 않다. 아래 여섯 가지만 피해도 대부분의 사고는 일어나지 않는다.
| 하지 말 것 | 왜 위험한가 | 대신 이렇게 |
|---|---|---|
| 코드에 키를 직접 적기 | 저장소에 올라가는 순간 그대로 공개 | .env에 두고 이름으로 꺼내 쓰기 |
| 일단 하드코딩하고 나중에 정리 | 그 사이 커밋되면 기록에 영구히 남음 | 처음부터 .env로 시작 |
| .env를 커밋 | 가장 흔한 유출 경로 | .gitignore에 먼저 등록 |
| 채팅창·이슈·스크린샷에 키 붙여넣기 | 대화 기록과 이미지에 그대로 남음 | 이름만 말하고 값은 파일에 직접 입력 |
| .env.example에 실제 값 넣기 | 견본이 곧 유출 경로가 됨 | 빈 값과 형식만 남기기 |
| 유출 후 파일만 삭제 | 기록에 남은 옛 키가 계속 유효 | 키 재발급이 먼저 |
바이브 코딩으로 어떻게 관리하나
AI에게 매번 말로 지시하는 대신, 규칙을 파일로 적어두면 매 대화에 자동으로 적용된다. 프로젝트 폴더 맨 위의 CLAUDE.md(여러 도구를 섞어 쓰면 AGENTS.md)에 아래 몇 줄을 넣어두면 된다.
## 비밀 값 취급
- API 키·비밀번호·토큰은 절대 코드에 직접 적지 마라. .env에 두고 이름으로 꺼내 써라.
- 새 비밀 값이 생기면 .env.example에 빈 이름을 추가하고, .gitignore에 .env가 있는지 확인하라.
- 커밋 전에 추적 목록에 .env나 키 문자열이 들어갔는지 확인하라.
- 나에게 키 값을 채팅으로 붙여넣으라고 요구하지 마라. 파일에는 내가 직접 넣는다.제대로 막혔는지 확인하는 법
규칙을 적어뒀어도 실제로 막혔는지는 눈으로 확인해야 한다. 명령 세 개면 끝난다. AI에게 '지금 저장소에 올라가면 안 될 파일이 추적되고 있는지 확인해줘'라고 말로 시켜도 같은 걸 해준다.
# 이번 커밋에 올라갈 목록 — 여기에 .env가 보이면 안 된다
git status --short
# .env가 정말 무시되고 있는지 확인 (규칙 줄이 출력되면 정상)
git check-ignore -v .env
# 이미 추적 중인 파일 중 env가 들어간 게 있는지
git ls-files | grep env배포까지 갔다면 — 값이 사는 곳은 두 군데
만든 걸 인터넷에 올려 남이 쓰게 하려면 배포 서비스를 거친다. 여기서 한 번 더 막히는 지점이 있다. .env는 저장소에 안 올라가니, 배포된 서버에는 그 파일이 없다는 것이다.
해결은 간단하다. Vercel·Railway 같은 서비스의 설정 화면에는 환경 변수(Environment Variables)를 입력하는 칸이 있다. .env에 적은 것과 같은 이름과 값을 거기에 넣으면 배포된 서버가 그 값을 읽는다. 로컬은 .env, 서버는 대시보드 — 값이 사는 곳이 두 군데라고 기억하면 된다. .env 파일 자체를 서버에 올리는 방식은 쓰지 않는다.
지금 바로 시작하기
다섯 단계면 끝난다. (1) 프로젝트 폴더 맨 위에 .gitignore를 만들고 .env를 한 줄 적는다. (2) .env 파일을 만들어 키를 옮긴다. (3) 코드에 박힌 키를 지우고 이름으로 꺼내 쓰게 바꾼다 — AI에게 '코드에 있는 키를 .env로 옮겨줘'라고 시키면 된다. (4) .env.example에 이름만 남긴다. (5) git status로 .env가 목록에 없는지 확인한 뒤 커밋한다.
파일 두 개, 십 분이면 끝나는 일이다. 그리고 이 십 분이 유출 사고와 청구서를 통째로 없애준다.