문서는 코드가 못 말하는 것만 담아라, 바이브코딩 문서 관리 실전법

01핵심 개요

• 문서에 남길 정보는 단 두 종류: 코드에서 도출 불가능한 정보, 에이전트용 네비게이션 지름길.
• Claude Opus(effort 高)로 코드베이스 전체 파악 후, 저난도 편집은 Cursor(그록·GPT 등)로 이관해 비용·속도 최적화.
• "confidence 85점 미만만 브리핑하라"는 프롬프트로 에이전트와의 불필요한 논의를 줄이는 실전 화법 제시.
• 세션 종료마다 수동 호출하는 "session docs" 스킬을 직접 설계해 문서 비대화를 방지.
• ERD·API 목록·DB 스키마 문서는 코드(ORM 엔티티 등)와 중복되므로 원칙적으로 삭제 대상으로 판정.

02핵심 주장 / 논점 구조

• 문서와 코드가 같은 내용을 담으면 반드시 어긋나는 순간이 오고, 그 어긋난 문서가 에이전트를 계속 잘못된 방향으로 유도한다.
• "코드로 표현 가능한 관례"는 문서/룰이 아니라 ESLint 같은 프로그램적 게이트로 강제해야 한다 — 룰 파일에 이미 린터가 막는 내용을 적어두는 것은 대표적인 안티패턴.
• 에이전트는 기본적으로 과잉 문서화 경향이 있다("이렇게 뇌절을 많이 해요"라는 표현으로 설명) — 사람이 매번 승인/거부하며 컨텍스트를 통제해야 한다.
• 문서의 오류는 코드의 오류(테스트·컴파일 에러로 검증 가능)와 달리 검증 수단이 없어 "조용히 개발 경험을 망친다"는 것이 핵심 리스크.
• 다른 직군과의 협업 목적으로 코드베이스 내 마크다운 문서를 쓰는 것은 오해다. PM 등 비개발 직군은 그 문서를 보지 않으므로, 문서 대신 해당 직군이 쓸 수 있는 조회용 에이전트(예: 슬랙 봇)를 만들어주는 게 우선이다.

03실습 사례: PT 트래킹 앱 문서 정리

• 대상 프로젝트는 진행자가 개인 PT 수업 중량 추적과 트레이너 공유를 위해 만든 실사용 앱(Supabase 백엔드, React Query, React Native/Expo 기반).
• 기존 문서 목록: 디자인 문서, 스테이지 문서, 진행상황(Progress), 실행계획(Execution Plan), 커서 룰(Cursor Rules), 요구사항(Requirements), ADR류 등 다수.
• 점검 기준 프롬프트: "① 코드로부터 절대 도출할 수 없는 정보인가 ② 에이전트가 작업 범위를 빠르게 찾는 데 실질적으로 참조되는 지름길인가"의 두 축으로 남김/지움/고침을 판정시킴.
• 결과: 유저 스토리는 유지(코드에 없는 "왜"를 담음), DB 스키마 문서는 삭제(코드가 곧 ERD), 구현 단계별 명세 문서는 삭제, React Query 사용 규칙을 담은 Cursor Rule은 ESLint 커스텀 룰 대체 가능성을 검토 후 처리.
• 스프레드시트로 관리하던 PT 성과 추적 데이터를 Claude Opus 4.6에 분석시켜, 현재 앱이 그 가치를 대체하고 있는지 갭 분석(22개 항목 미해결로 파악).

04전략적 의미

• "문서를 늘리는 게 아니라 코드와 어긋날 문서를 남기지 않는 것"이 문서화 정책의 핵심 목표로 재정의됨 — 지름길 문서라도 틀리면 없는 것보다 나쁘다.
• 문서의 역할이 "지식 저장소"에서 "의도·금지·미결·사람용 연결 안내"로 좁혀지는 방향 전환.
• 레거시 API 하위호환처럼 코드 주석으로 남기기 애매한 "곁다리 맥락"(예: 특정 은행 연동 시 3주 하위호환 유지 규칙)만 예외적으로 문서화 가치를 인정.
• 회사 규모가 커도 RAG 같은 별도 검색 인프라 도입 없이 문서 최소화 + 큰 컨텍스트 윈도우만으로 충분하다는 입장(개발 문서는 정형화되어 있어 RAG 필요성이 낮다는 주장).

05핵심 워크플로우

06활용 시나리오

• 개인/소규모 팀 바이브코딩 프로젝트에서 문서가 코드와 계속 어긋나 에이전트 성능이 떨어지는 상황의 리셋 작업으로 적용 가능.
• 스펙킷(Spec Kit) 등 자동 문서 생성 도구를 쓰는 경우, 생성된 문서가 무분별하게 쌓이는 것을 주기적으로 이 두 기준(코드 도출 불가 여부, 실질 참조 여부)으로 솎아내는 정기 점검 루틴으로 활용.
• PM·비개발 직군과의 협업 문서화 요구가 있을 때, 마크다운 문서 대신 코드베이스 조회 전용 에이전트(슬랙 봇 등)를 만들어 대체.
• 새 프로젝트 착수 시점부터 "session docs"류 세션 종료 후 점검 스킬을 미리 설계해 문서 비대화를 예방.

07현황 및 전망

• 진행자는 해당 세션 중 앱을 최종적으로 앱스토어 제출까지 진행(EAS 빌드, 애플 인증서 처리 등 실무 단계 포함).
• 문서 정리 후 "프로그램적 게이트"(테스트, 린트) 전수 점검을 별도로 수행해 실패 원인을 git blame으로 추적하는 방식도 시연.
• Cursor 자체 내장 기능(로컬 대화 세션 자동 분석, Create Skill 등)을 활용해 세션 회고 및 스킬 개선을 반복하는 흐름이 정착 단계.
• 라이브 Q&A에서 "RAG 도입이 회사 규모 때문에 필요한가"라는 질문에는 부정적 견해(개발 문서는 정형화되어 있어 불필요)를 제시하며, 실전에서는 문서 최소화 원칙이 코드 규모와 무관하게 통한다고 주장.

08용어 사전

• 바이브코딩(Vibe Coding): AI 에이전트에게 자연어로 의도를 전달해 코드를 작성·수정하게 하는 개발 방식.
• 세션 독스(session docs) 스킬: 진행자가 직접 설계한 Cursor/Claude용 커스텀 스킬로, 대화 세션 종료 시 호출해 문서화 대상과 방식을 브리핑하도록 만든 도구.
• effort 레벨: 모델의 추론 강도 설정. 이해도가 낮을 때는 높게, 익숙해질수록 낮춰서 비용을 절감.
• ADR(Architecture Decision Record): 아키텍처 의사결정과 그 배경을 기록하는 문서 유형.
• 프로그램적 게이트: 린터·테스트처럼 코드가 규칙을 지키는지 자동으로 검증하는 장치. 문서/룰보다 우선순위가 높다고 강조됨.
• ERD(Entity Relationship Diagram): 데이터베이스 테이블 관계도. ORM을 쓰면 엔티티 코드 자체가 ERD 역할을 하므로 별도 문서화가 불필요하다는 논지의 핵심 사례.