클로드 바이브코딩 기초반/바이브코딩 가이드

4부 내 서비스를 완성한다

16장 · CLAUDE.md와 계속 쓸 수 있는 구조

새 대화의 Claude는 매일 새로 출근하는 신입입니다. 폴더에 신입 매뉴얼 한 장, CLAUDE.md를 둡니다.

새 대화마다 같은 말을 반복하고 있지 않나요

"폰에서도 보기 좋게 해줘" — 요청할 때마다 또. "계산 방식은 건드리지 마" — 어제 말했는데 오늘 또. "설명은 쉬운 한국어로" — 새 대화를 열면 또. 새 대화의 Claude는 지난 대화의 규칙을 모르고 시작합니다. 2부에서 Skill로 반복 지시를 줄였듯, 프로젝트 규칙은 파일 한 장에 적어 둡니다.

새 대화의 Claude는 매일 새로 출근하는 신입. 폴더에 신입 매뉴얼 한 장, CLAUDE.md를 둡니다. Claude Code는 대화를 시작할 때마다 이 파일을 먼저 읽고 일합니다. 2부 프로젝트 '지침'의 Claude Code 버전입니다.

CLAUDE.md — 어디에 두고 어떻게 작동하나

서로 부딪치는 규칙은 지웁니다. 둘 중 아무거나 따를 수 있습니다. 공식 가이드는 "이 줄을 빼면 Claude가 실수할까?"를 기준으로 한 줄 한 줄 따져 보라고 합니다. 아니면 지웁니다. 길어질수록 정작 중요한 규칙이 묻힙니다.

집 전체에 적용할 규칙은 ~/.claude/CLAUDE.md(내 계정 폴더)에, 이 프로젝트만의 규칙은 프로젝트 폴더의 CLAUDE.md에 둡니다. 둘 다 읽힙니다. 처음엔 프로젝트 폴더 한 장이면 됩니다.

만드는 법 두 가지

이 가이드는 ②로 갑니다. 내 서비스 규칙을 내가 불러 주는 게 핵심이라서. 나중에 규칙을 더할 때도 "이거 CLAUDE.md에 추가해줘" 한마디면 됩니다.

내 서비스 CLAUDE.md에 적을 것 — 여섯 줄

항목 예시 (견적 계산기)
서비스 한 줄 단가·수량·원가율·할인율 → 부가세 포함 견적과 남는 돈
꼭 지킬 것 폰 화면 우선 · 설명은 쉬운 한국어
건드리지 말 것 계산 규칙은 내 확인 없이 바꾸지 않는다
이번 버전에서 안 하는 것 로그인 · 결제 · 여러 사람 데이터 저장(DB) · API 키
작업 순서 계획 먼저 → 내 확인 → 수정 → 확인 후 GitHub에 올리기
되풀이된 실수 (같은 실수가 2번 나오면 여기에 한 줄씩)

비밀 숫자·고객 정보는 적지 않습니다. 이 파일도 GitHub에 함께 올라갑니다.

Claude에게 이렇게 보내세요
이 서비스 폴더에 CLAUDE.md를 만들어줘.
@기획.md 를 참고하고, 30줄 이내로 짧게.
넣을 규칙
- 서비스 한 줄 설명
- 휴대폰 화면 우선, 설명은 쉬운 한국어
- 계산 규칙은 내 확인 없이 바꾸지 않기
- 로그인·결제·DB·API 키는 이번 버전에서 제외
- 고치기 전에 계획 먼저, 확인 후 GitHub에 올리기
다 만들면 내용을 보여줘.

규칙은 내 업종에 맞게 바꿉니다. 정답은 없고, 내 서비스 규칙이 정답입니다.

새 대화로 확인

만들어진 CLAUDE.md를 열어 규칙을 읽습니다. 틀린 줄은 말로 고칩니다. "세 번째 규칙을 ○○로 바꿔줘." 그리고 새 대화를 엽니다. 지난 대화를 모르는 신입이 출근한 상태입니다. 규칙 얘기 없이 "결과 아래에 안내 문구 하나 추가해줘"라고만 보냅니다. 폰 화면·계산 규칙을 알아서 지키면 매뉴얼을 읽고 일한 것입니다.

재발 방지 습관 — 같은 실수가 두 번 나오면 한 줄

공식 문서도 "Claude가 같은 실수를 두 번째 할 때" CLAUDE.md에 적으라고 안내합니다. 말로 두 번 고칠 일을 파일 한 줄로 끝냅니다.

Claude에게 이렇게 보내세요
방금 네가 부가세를 할인 전 금액에 붙였어.
이 실수가 다시 안 나오게
CLAUDE.md에 규칙 한 줄로 추가해줘.
추가할 문장을 먼저 보여주고,
내가 좋다고 하면 저장해줘.

규칙은 "할인 → 부가세 순서로 계산한다"처럼 확인할 수 있게 구체적으로. 대화 중에 #으로 시작하는 한 줄을 보내면 바로 CLAUDE.md에 적어 주는 단축 방법도 있습니다(터미널·확장 기준, 2026-09). 한 번 넣은 규칙이 계속 안 지켜지면 파일이 너무 길거나 문장이 애매한 것이니, 그 줄만 "IMPORTANT"를 붙이거나 다른 줄을 줄입니다.

새 대화를 여는 타이밍 — 한 창 한 주제

대화는 한 작업씩, 규칙은 파일에. 그래서 새 대화가 두렵지 않습니다. 대화가 너무 길어지면 Claude Code가 알아서 앞부분을 요약하기도 하고, /compact로 직접 요약을 시킬 수도 있습니다. 관계없는 작업 사이에는 /clear가 깔끔합니다.

유지보수 쉬운 폴더 — 네 가지면 됩니다

파일 역할 누가 고치나
서비스 파일 (index.html 등) 실제 화면과 계산 Claude — 내가 요청
기획.md 무엇을, 왜 만들었나 나 — 방향이 바뀔 때
CLAUDE.md 일할 때 지킬 규칙 나·Claude — 같은 실수 2번이면
고칠목록.md 쓰다 불편한 점 · 다음 단계 욕심 나 — 불편할 때마다 한 줄

GitHub 저장소 = 변경 기록 보관함, Vercel = 공개 창구. 폴더는 하나로 유지합니다.

Claude에게 이렇게 보내세요
이 폴더를 처음 보는 사람이라고 생각하고 점검해줘.
1) 필요 없는 파일이나 헷갈리는 이름이 있는지
2) 기획.md·CLAUDE.md가 지금 서비스와 맞는지
3) 고칠목록.md가 없으면 만들어서
   14장에서 "다음 단계"로 미룬 기능을 적어줘
파일을 지우거나 옮기기 전에는
계획을 먼저 보여주고 내 확인을 받아줘.

지우기·옮기기는 plan 모드 또는 '계획 먼저'로. 마지막 버튼은 사람이.

이 장의 결과물