바이브코딩 하는법, AI가 매번 처음부터 다시 묻지 않게 만드는 문서 3장

오즈입니다.

AI한테 시켜서 프로그램을 만들고는 계신데, 어제 잘 되던 게 오늘 세션에서는 엉뚱하게 고쳐지고 계신가요?

아니면 "그거 저번에 이미 정했잖아"를 하루에 몇 번씩 다시 설명하고 계신가요?

혹은 만들다 만 프로젝트가 폴더에 서너 개 쌓여 있는데, 다시 열기가 무서우신가요?

그렇다면 이 글을 끝까지 보셔야 합니다.

제가 지난 몇 달 동안 AI한테 시켜서 자동화 도구를 열 개 넘게 만들었습니다.

그중 여섯 개에서 시키지도 않았는데 똑같은 문서 세 장이 저절로 생겨났습니다.

그 세 장이 뭐고, 각각 뭘 적고, 왜 그게 생길 수밖에 없었는지 전부 정리했습니다.

먼저 결론부터 말씀드릴게요.

바이브코딩이 무너지는 지점은 코드 실력이 아니라 인수인계입니다.

AI는 어제 우리가 뭘 정했는지 모릅니다. 세션이 바뀔 때마다 신입사원이 새로 출근하는 셈입니다.

이 글에서 계속 등장할 한 사람

이야기가 붕 뜨지 않게, 사람 하나를 정해놓고 세 편 내내 이분으로 설명하겠습니다.

직원 세 명짜리 인테리어 시공 업체 사장님입니다.

• 코딩은 배운 적 없고, 전부 AI한테 시켜서 만드는 중

• 현장이 동시에 네다섯 개, 자재 견적서가 주에 열 건쯤

• 지금은 카톡방 + 엑셀 + 휴대폰 사진첩으로 굴러감

• 손댈 수 있는 시간은 저녁 한 시간, 주말 세 시간

현장 사진과 자재 견적을 한곳에서 보는 관리 도구를 직접 만들어 보기로 했습니다. 이분을 데리고 세 편을 갑니다.

이 시리즈가 계속 쓸 세 가지

AI한테 일을 시켜서 뭔가를 만들 때, 우리가 챙겨야 하는 건 딱 세 가지입니다.

1. 넘길 것 — 세션이 끊겨도 다음 AI에게 넘어가는 것
2. 가를 것 — 어디까지 코드가 하고 어디부터 AI가 판단하나
3. 막을 것 — AI가 틀렸을 때 프로그램이 안 죽게 하는 장치

오늘은 첫 번째, 넘길 것입니다.

왜 어제 잘 되던 게 오늘 망가지나요

AI는 대화가 길어질수록 앞에서 한 말을 잊습니다. 이건 우리가 설명을 못 해서가 아니라 구조가 그렇습니다.

앤트로픽이 클로드 코드 공식 문서에 이걸 대놓고 적어놨습니다. 【문서 근거 · 2026-07-25 확인】

"대부분의 모범 사례는 하나의 제약에서 나온다. 클로드의 컨텍스트 창은 빠르게 차고, 차오를수록 성능이 떨어진다."
— 앤트로픽 「Best practices for Claude Code」

같은 문서에 이런 말도 있습니다.

"컨텍스트 창이 차오르면 클로드는 앞선 지시를 '잊기' 시작하거나 실수가 늘어난다."

파일 하나 읽고 명령어 몇 번 돌리면 수만 토큰이 순식간에 들어간다고도 적혀 있고요.

그러니까 어제 잘 되던 게 오늘 망가지는 건 AI가 나빠져서가 아닙니다.

어제의 대화가 오늘 세션에는 아예 존재하지 않기 때문입니다.

그리고 여기서 무서운 게 하나 더 있습니다. 우리는 이 손해를 못 느낍니다.

METR라는 연구기관이 2025년에 실험을 하나 했습니다.

경력 개발자 16명에게 자기가 몇 년씩 만져온 오픈소스 저장소에서 실제 이슈 246건을 처리하게 했습니다. 절반은 AI 도구를 쓰게 하고, 절반은 못 쓰게 했고요.

결과는 AI를 쓸 때 19% 더 느렸습니다.

그런데 정작 참가자들은 끝나고 나서 "AI 덕에 20% 빨라진 것 같다"고 답했습니다. 【문서 근거 · 2026-07-25 확인】

느낌과 실제가 정반대로 갈린 겁니다.

참고로 이 실험은 2025년 상반기 도구 기준이고, 연구진 스스로 "모든 개발 상황에 일반화되는 결과는 아니다"라고 못 박아 두긴 했습니다. 그래도 "체감으로는 절대 못 잡는다"는 교훈은 남습니다.

그래서 느낌 말고 물건이 필요합니다. 문서입니다.

다섯 시간짜리 손해를 40분으로 막는 계산

숫자로 놓고 보면 이 얘기가 훨씬 간단해집니다.

인테리어 사장님이 관리 도구를 만들면서 저녁마다 AI 세션을 켠다고 해보죠.

세션을 새로 열 때마다 AI가 "이 프로젝트 구조가 어떻게 되죠?" 상태에서 시작합니다. 코드를 뒤지고, 사장님이 다시 설명하고, 저번에 정한 규칙을 또 알려주고.

여기에 매번 5분이 듭니다.

• 하루 2~3세션 × 한 달 20일 = 약 50번

• 50번 × 5분 = 월 4시간 10분

저녁 한 시간씩 쓰는 분한테 월 4시간은 작업일 나흘입니다.

만들다 만 프로젝트가 쌓이는 이유가 여기 있습니다. 실제로 진도가 안 나가거든요.

문서 세 장을 만드는 데 드는 시간은 처음 40분, 이후 하루 3분입니다.

어느 쪽이 남는 장사인지는 계산기 없이도 나옵니다.

그래서 어떤 문서 세 장인가요

질문 세 개에 각각 종이 한 장씩입니다. 섞으면 안 됩니다.

세 장은 답하는 질문이 서로 다릅니다. 하나로 합치면 길어지고, 길어지면 AI가 무시합니다(이건 뒤에서 다시 말씀드릴게요).

1장 — PLAN.md : "이걸 왜 만드나"

만들기 전에 쓰는 문서입니다. 한 번 쓰고 거의 안 고칩니다.

• 이 도구가 없으면 지금 뭐가 불편한가

• 다 만들면 뭐가 되어 있어야 하는가

• 안 할 것 (이게 제일 중요합니다)

"안 할 것"을 안 적으면 AI가 자꾸 살을 붙입니다.

사장님이 "현장 사진 정리"만 원했는데 회원 로그인, 권한 관리, 알림 설정이 붙어서 돌아옵니다. 나쁜 뜻이 아닙니다. 안 된다고 말한 적이 없으니 좋으라고 붙이는 겁니다.

안 할 것: 로그인 없음(내 노트북에서만 씀). 알림 없음. 모바일 앱 안 만듦(브라우저로 봄).

이 세 줄이 나중에 몇 시간을 아껴줍니다.

2장 — HANDOFF.md : "지금 어디까지 했나"

세 장 중 유일하게 매일 고치는 문서입니다. 다음 세션에게 넘기는 인수인계서라고 보시면 됩니다.

• 어디까지 됐고 어디서 멈췄나

• 지금 막혀 있는 것 (증상 그대로, 해석 말고)

• 다음에 할 일 하나

• 손대면 안 되는 곳

증상을 그대로 적으라는 게 핵심입니다.

"DB 연결이 이상함" 말고 "사진 업로드하면 목록에는 뜨는데 새로고침하면 사라짐"이라고 적으세요.

해석을 적으면 다음 세션의 AI가 그 해석을 사실로 믿고 엉뚱한 데를 팝니다.

3장 — 개발노트.md : "코드가 어디에 있나"

이건 코드 지도입니다.

제가 만든 도구 중에 2,100줄짜리 파일 하나로 된 프로그램이 있습니다. 거기 붙여둔 개발노트 첫 줄이 이렇습니다.

목적: 다음 세션이 2,100줄 전체를 다시 읽지 않고 필요한 함수만 콕 집어 읽어 토큰을 아끼기 위한 지도.

내용은 이런 식입니다.

• 로그인 관련 → Do-Login, Wait-Ready

• 글 읽기/입력 → Read-Post, Enter-Text

• 발행 → Publish-Now

그리고 같은 문서에 이 한 줄을 반드시 넣으셔야 합니다.

줄 번호는 편집하면 바뀌므로, 정확한 위치는 그때그때 검색으로 확인할 것.

"475번째 줄에 있음"이라고 적힌 문서는 이틀 뒤에 거짓말이 됩니다.

그리고 AI는 그 거짓말을 의심 없이 믿습니다.

위치는 이름으로 적고, 찾는 방법을 알려주세요. 이름은 안 바뀝니다.

여기서 제일 많이 하는 실수

문서가 길어지면 AI가 읽고도 무시합니다. 이건 제 감이 아니라 만든 쪽이 직접 적어둔 얘기입니다.

앤트로픽 공식 문서에 이렇게 나옵니다. 【문서 근거 · 2026-07-25 확인】

"간결하게 유지하라. 각 줄마다 물어보라. *'이 줄을 지우면 클로드가 실수를 하게 되나?'* 아니면 지워라. 비대해진 CLAUDE.md는 클로드가 정작 중요한 지시를 무시하게 만든다."

같은 문서가 흔한 실패 패턴으로 "과하게 적은 문서"를 꼽습니다. 그러면서 "클로드가 그 지시 없이도 이미 잘하고 있다면 지우라"고 합니다.

지침을 더 넣는 게 아니라 빼라는 겁니다.

판별법이 하나 있습니다.

같은 걸 세 번 이상 지적했는데도 AI가 계속 틀린다면, 지침이 부족한 게 아니라 문서가 길어서 그 줄이 묻힌 겁니다.

이럴 땐 문장을 추가하지 마시고 다른 줄을 지우세요.

그럼 하루 3분은 뭘 하는 시간인가요

작업 끝낼 때 이 한 문장만 치시면 됩니다.

오늘 한 것 기준으로 HANDOFF.md 맨 위를 고쳐줘. 어디까지 됐는지, 지금 막힌 게 뭔지, 다음에 뭘 할지.

AI가 씁니다. 사장님은 읽고 틀린 것만 고치시면 됩니다.

문서를 사람이 쓰는 게 아니라, AI가 쓰고 사람이 검수하는 겁니다.

이걸 사람이 쓰려고 하면 사흘 만에 안 하게 됩니다. 제가 그래 봤습니다.

그리고 새 세션을 열 땐 반대로 하세요.

HANDOFF.md 읽고 지금 상태 요약해줘. 그다음 "다음에 할 일" 하나만 하자.

이러면 아까 그 5분이 30초가 됩니다.

오즈가 직접 확인한 것

【직접 확인 · 2026-07-25】 제가 만든 자동화 도구 저장소 여섯 곳에서 이 문서 패턴이 실제로 반복되는 걸 확인했습니다.

이름은 제각각이었습니다. PLAN.md, HANDOFF.md, 개발노트.md, 개발자_핸드오프.md, docs/design.

정해놓고 만든 게 아닙니다. 필요해서 각각 생겼는데 결국 같은 세 종류로 수렴한 겁니다.

그래서 이게 제 취향이 아니라 구조상 필요한 물건이라고 판단했습니다.

【직접 확인 · 2026-07-25】 2,100줄짜리 단일 파일 프로그램에 붙인 개발노트가 실제로 작동합니다. 함수 이름으로 위치를 적고 줄 번호는 안 적는 방식입니다.

【아직 못 봄】 "문서 있을 때 vs 없을 때" 진행 속도를 나란히 재본 적은 없습니다.

위의 4시간 10분은 제 경험에서 나온 추정이지 측정값이 아닙니다. 같은 프로젝트를 두 번 만들어 볼 수는 없으니까요.

다만 이걸 재는 방법이 하나 있어서, 다음 편에서 그 얘기를 하겠습니다.

오늘 할 일 3가지

1. 지금 만들다 만 프로젝트 폴더 하나를 열고, `PLAN.md`에 "안 할 것" 세 줄만 적기 — 5분

2. AI한테 개발노트.md를 시키기. 프롬프트는 이겁니다 — 10분

이 프로젝트의 코드 지도를 만들어줘. 기능별로 어느 파일 어느 함수인지. 줄 번호는 적지 말고 이름으로 적어줘.

1. 오늘 작업 끝낼 때 HANDOFF.md 한 번 갱신하고 창 닫기 — 3분

3번이 제일 시시해 보이고 제일 효과가 큽니다. 내일 아침의 나한테 주는 선물입니다.

자주 묻는 질문

Q. 문서 세 장을 그냥 하나로 합치면 안 되나요?
A. 안 하시는 걸 권합니다. 고치는 주기가 완전히 다릅니다. PLAN은 거의 안 고치고 HANDOFF는 매일 고칩니다. 합쳐두면 매일 고치다가 안 고쳐도 될 부분까지 흔들리고, 무엇보다 길어집니다. 길어지면 무시됩니다.

Q. 클로드 코드 말고 다른 도구를 쓰는데도 해당되나요?
A. 됩니다. 컨텍스트가 길어지면 성능이 떨어지는 건 특정 제품 문제가 아니라 지금 언어모델 공통 성질입니다. 다만 파일을 자동으로 읽어주는 기능은 도구마다 달라서, 없으면 세션 시작할 때 직접 문서를 붙여넣으시면 됩니다.

Q. 코드를 하나도 못 읽는데 개발노트를 검수할 수 있나요?
A. 내용의 정확성은 못 보셔도 형식은 보실 수 있습니다. 줄 번호가 적혀 있으면 빼라고 하시고, 두 쪽이 넘으면 줄이라고 하시고, 기능 이름이 사장님이 쓰는 말이 아니면 바꾸라고 하세요. 그것만 해도 절반은 됩니다.

Q. 문서를 만들어도 AI가 안 읽는 것 같은데요?
A. 두 가지를 확인하세요. 첫째, 자동으로 읽히는 위치에 있는지. 둘째, 문서가 너무 길지 않은지. 앤트로픽 문서가 지적하는 대표적인 실패가 정확히 이 두 번째입니다.

Q. 만들다 만 프로젝트를 다시 살릴 수 있을까요?
A. 코드부터 열지 마시고 AI한테 이렇게 시켜보세요. "이 폴더 훑어보고 뭘 만들려던 건지, 어디까지 됐는지, 다음에 뭘 하면 되는지 HANDOFF.md로 정리해줘." 살릴지 말지는 그 문서를 읽고 정하시면 됩니다. 이게 제일 싼 판단 방법입니다.

정리하면 이렇습니다. 바이브코딩에서 진짜 병목은 코드가 아니라 인수인계고, 인수인계는 세 장이면 됩니다. 왜 만드는지(PLAN), 어디까지 했는지(HANDOFF), 코드가 어디 있는지(개발노트).

이어지는 글도 함께 보세요. 같은 인테리어 사장님으로 끝까지 이어집니다.

• 2편 · 가를 것 — AI한테 다 시키면 안 되는 일이 있습니다. 매번 답이 달라지면 안 되는 일이 그렇습니다. 그 선을 어디에 긋는지 → 클로드코드 사용법: AI한테 시키면 안 되는 일을 가르는 선 하나

• 3편 · 막을 것 — 선을 잘 그어놔도 AI 쪽은 언젠가 실패합니다. 그때 프로그램 전체가 멈추지 않게 하는 법 → AI 코딩 프로그램 만들 때: AI가 멈춰도 프로그램은 안 멈추게 하는 3가지

만들다 만 프로젝트가 있으시면 어떤 도구인지 댓글로 남겨주세요. 어떤 문서부터 만들면 좋을지 같이 보겠습니다.

출처

• 앤트로픽, 「Best practices for Claude Code」 — 컨텍스트 창과 성능 저하, CLAUDE.md 작성 원칙, 흔한 실패 패턴

https://code.claude.com/docs/en/best-practices

• METR, 「Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity」 (2025-07-10) — 개발자 16명, 과제 246건, 19% 지연, 참가자 자체 평가는 20% 단축

https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/

최초 작성 2026-07-25 · 최종 수정 2026-07-25