현업 개발자의 바이브코딩 문서 관리법

한 줄 핵심

바이브 코딩에서 문서는 많이 쌓는 것이 아니라 코드로 추론할 수 없는 정보와 에이전트의 작업 지름길만 남기고, 나머지는 린터·테스트·스킬로 시스템화해야 한다는 실전 운영법을 보여준다.

시간별 요약

0:10
프로젝트 점검과 문서화 시작 기존 프로젝트를 점검하면서 문서화를 정리하는 작업이 시작된다. 개인 PT와 운동 중량 추적 앱을 예시로 삼아, 오늘 목표가 기능 개발이 아니라 코드베이스 이해와 문서 체계 정비임을 분명히 한다.
2:03
문서에 남기면 안 되는 정보 문서는 코드와 중복되기 쉬우므로 함부로 늘리면 안 된다. 코드에서 이미 충분히 설명되는 내용은 문서에 남기지 말아야 하며, 중복 문서는 오히려 유지보수 비용만 키운다.
3:01
이해도 끌어올리기와 난이도 조절 바이브 코딩을 시작할 때는 먼저 코드베이스 이해도를 끌어올려야 한다. 작업 난이도와 필요한 컨텍스트 양을 보고 어떤 모델과 어떤 도구를 쓸지 조절하는 것이 핵심이다.
6:03
가벼운 작업은 Cursor로 빠르게 새 설계가 아니라 문서 정리 같은 작업은 고성능 모델이 아니라 빠른 도구로 충분하다. 고려할 컨텍스트가 적은 일은 Cursor 같은 환경에서 빠르게 확인하고 바로 정리하는 편이 효율적이다.
9:00
문서의 두 가지 존재 이유 문서에 남길 가치는 사실상 두 가지다. 코드로부터 절대 추론할 수 없는 정보와, 에이전트가 작업 범위와 위치를 빠르게 찾도록 돕는 내비게이팅 파일만 남겨야 한다.
11:02
남김·지움·고침 기준 세우기 문서를 남길지 지울지 고칠지 판단하는 기준을 명확히 세운다. 코드로 알 수 있는 정보는 삭제하고, 에이전트의 작업 지름길이 되는 문서만 예외적으로 유지해야 한다.
15:01
과도한 문서화 제거 유저 스토리처럼 코드 밖 맥락이 필요한 문서는 남길 수 있지만, 단계 명세나 스키마처럼 코드나 다른 도구로 대체 가능한 내용은 삭제하는 것이 맞다. 문서는 가능한 한 얇고 목적이 분명해야 한다.
24:20
룰보다 린터로 막기 프로그램적으로 검증 가능한 규칙은 문서나 룰 파일이 아니라 린터로 막는 편이 낫다. 이미 ES Lint로 잡히는 내용을 커스텀 룰로 또 적는 것은 불필요한 중복이다.
34:06
스프레드시트로 가치 검증 PT 추적용 스프레드시트를 먼저 만들어, 어떤 데이터가 있어야 제품 가치가 살아나는지 검증한다. 문서와 서비스가 아니라 실제 사용 가치와 차별화 포인트를 먼저 확인해야 한다.
46:13
세션 종료용 문서화 스킬 설계 대화 세션이 끝날 때마다 호출할 문서화 스킬을 설계해, 남길 만한 지식과 시스템화할 만한 규칙을 브리핑하게 한다. 다만 스킬은 자동 저장소가 아니라 검토 보조 도구여야 한다.
51:06
절대 만들지 말아야 할 문서 ERD처럼 코드가 이미 사실상 정의를 갖고 있는 문서는 거의 만들 필요가 없다. ORM 엔티티나 코드 구조로 충분히 표현되는 내용을 별도 문서로 들고 있으면 오히려 동기화 비용만 커진다.
1:57:08
문서보다 테스트와 게이트 문서화 스킬은 기록이 아니라 시스템적 방지책을 남기는 수단이어야 한다. 문서 대신 테스트나 검증 게이트로 막는 편이 더 안전하고, 구현 과정의 산출물은 나중에 폐기해야 한다.
2:43:12
언제 문서화를 시작할까 기능 초안이 어느 정도 잡히면 바로 문서화를 시작하는 것이 좋다. 너무 이른 문서는 기준을 잡기 어렵고, 너무 늦으면 이미 결정한 내용이 계속 흩어져서 설명 비용이 커진다.
2:53:03
기획·구현 문서는 기록일 뿐 PRD, 스펙, 플랜 같은 구현용 문서는 장기 저장용 문서가 아니라 그 시점의 기록이다. 오래된 중간 산출물은 오히려 잘못된 정보를 주입하므로, 코드와 맞지 않으면 과감히 폐기하는 편이 낫다.

실무 인사이트

문서 검토는 '코드로 추론 불가한 정보'와 '에이전트의 작업 지름길' 두 기준만 고정하면 훨씬 단순해진다.
프로그램적으로 막을 수 있는 규칙은 문서가 아니라 린터·테스트·검증 게이트로 옮겨야 유지보수 비용이 줄어든다.
세션 종료 시 문서화 스킬을 호출해 남길 내용만 선별하는 흐름을 만들면, 문서 비대화를 장기적으로 억제할 수 있다.