AI 바이브코딩 생산성 5배 올리는 법
5분 문서화 협업 시스템
TL;DR
문제: AI는 내 프로젝트에 뭐가 있는지 모른다. 매번 처음부터 다시 만든다
해결: "프로젝트 분석해서 문서 만들어" 5분이면 끝
효과: 3시간 작업이 30분으로, 충돌 없이 정확하게 통합
핵심: 문서는 AI의 기억. 문서화도 AI가 한다. 넌 그냥 "정리해"만 하면 된다
어제 새벽, 또 3시간을 날렸다
open-football 엔진을 전에 만든 게임에 통합하려고 했다.
GitHub에서 찾은 보물이니까, 당연히 쉽게 될 줄 알았다.
"open-football 매치 엔진 우리 프로젝트에 통합해."
Claude Code가 열심히 파일을 만들기 시작했다.
game_controller.gd, player.gd,MatchSimulationManager.gd…
그렇게 한참을 만들고, 밥먹고 와서 다시 재작업
“match_simulation_system.gd작업을 시작하겠습니다”
뭔가 이상했다.
"잠깐, 우리 이미 MatchSimulationManager 있는데? 뭐가 다른건대?"
확인해보니 더 가관이었다. PlayerManager도 있고, GameManager도 있고, 33개 Autoload 싱글톤이 이미 돌아가고 있는데, AI는 완전히 새로운 시스템을 처음부터 만들고 있었다.
마치 이사 온 집에 가구가 다 있는데, AI는 텅 빈 집인 줄 알고 가구를 또 사오는 것 같았다.
AI는 천재지만 장님이다
그때 깨달았다. AI는 내 프로젝트 폴더를 볼 수 없다는 걸.
아니 엄밀히 말하면 볼수는 있지만, 보지 않는다는 걸.
내가 "우리 프로젝트"라고 하면, AI는 뭘 상상할까? Unity일 수도 있고, 웹 프로젝트일 수도 있고, 아예 빈 폴더일 수도 있다. AI 입장에서는 추측 게임이다.
내 머릿속에는 분명했다. 33개 Autoload, 팀훈련 시스템, 6각형 능력치, scripts/core/에 깔끔하게 정리된 매니저들.
하지만 AI가 아는 건? 아무것도 없었다.
얘는 기본적으로 기억력이 없다. 마치 붕어처럼 한참 작업을 할때는 기억하지만, 금새 잊어버린다.
냉장고를 생각해봤다. 냉장고 문에 붙은 목록 없이 장보러 가는 거랑 비슷했다. 계란이 있는지 없는지 모르니까 일단 사온다. 집에 와보니 계란이 3판 있다.
어제도 이랬고, 오늘도 이랬다.
"문서 만들어" 한 마디의 마법
화가 나서 Claude에게 물었다.
"야, 너 우리 프로젝트에 뭐 있는지 알아?"
"아니요, 모릅니다."
그래, 모르겠지. 그럼 알려줘야지.
"현재 프로젝트 구조 분석해서 문서 만들어."
5분이 지났다.
# PROJECT_INFO.md 작성 완료 ## Autoload 시스템 (33개)
- GameCore.gd: 메인 게임 로직
- MatchSimulationManager.gd: 경기 시뮬레이션
- MandatoryTeamTrainingManager.gd: 팀 훈련 시스템 ...
## 폴더 구조
scripts/
├── core/ # 핵심 매니저들
├── ui/ # UI 컨트롤러
├── data/ # 데이터 클래스
└── utils/ # 유틸리티 함수
뭐야, 다 찾았잖아?
그제서야 이해했다. AI는 독심술을 못한다. 하지만 시키면 한다. 내가 30분 걸려서 할 일을 5분 만에 끝냈다. 파일 하나하나 열어서 뭐가 있는지 다 정리했다.
문서가 있고 나서 일어난 일
다시 시도해봤다.
"PROJECT_INFO.md 확인하고, open-football 통합해."
이번엔 달랐다.
"아, 기존 MatchSimulationManager.gd가 있네요. 여기에 open-football 엔진을 래퍼로 추가하겠습니다."
젠장, 처음부터 이렇게 하면 됐잖아.
전에는 3시간 걸렸다:
새로 만들고
충돌 나고
디버깅하고
결국 다 지우고
이번엔 30분이었다:
기존 시스템 확인하고
확장하고
테스트하고
끝
차이는 단 하나. 문서 5분 걸려서 만든 그거 하나.
문서화 4단계 법칙
이제 언제 문서화 시킬지 정확히 안다.
1. 새로운 정보 찾았을 때
나: "GitHub에서 open-football 찾았어"
나: "이거 정리해서 OPENSOURCE.md에 추가해"
AI: "네! 라이선스(MIT), 사용법, 통합 방법 정리했습니다"
2. 새 기능 만들 때
나: "경기 시스템 만들었어"
나: "이거 FEATURES.md에 추가해"
AI: "네! 파일 위치, 사용법, 연결된 시스템 기록했습니다"
3. 기능 업그레이드했을 때
나: "훈련 시스템 개선했어"
나: "CHANGELOG.md에 뭐 바뀌었는지 써"
AI: "네! v1→v2 변경사항 정리했습니다"
4. 에러 났을 때
나: "이 에러 해결했어"
나: "ERRORS.md에 해결법 추가해"
AI: "네! 에러 원인과 해결 방법 기록했습니다"
내 프로젝트의 문서 구조
일주일 만에 이렇게 됐다:
# README.md (메인 허브) ##
� 문서 위치
- �️ 기본 구조 → STRUCTURE.md
- � 아트/UI → ART.md
- � 스토리 → STORY.md
- � 에러 해결 → ERRORS.md
- � 오픈소스 → OPENSOURCE.md
- � 변경사항 → CHANGELOG.md
- ✅ 할 일 → TODO.md
각 문서는 역할이 명확하다:
STRUCTURE.md: 폴더, 파일, 기본 시스템
## Autoload 시스템
- GameCore: 게임의 심장
- PlayerManager: 선수 관리
- MatchSimulation: 경기 엔진
ART.md: 색깔, 폰트, UI 규칙
## 색상 팔레트
- 메인: #FFB6C1 (연한 핑크)
- 서브: #87CEEB (스카이 블루)
- 강조: #FFD700 (골드)
ERRORS.md: 자주 나는 에러와 해결법
## GPU 메모리 오류
- 증상: "VRAM exceeded"
- 원인: 모델 언로드 실패
- 해결: ollama stop 명령어 추가
매일의 루틴
매일 작업 끝나고:
나: "오늘 한 거 정리해서 문서 업데이트해"
AI: "3개 문서 업데이트 완료:
- STRUCTURE.md: 새 파일 5개 추가
- CHANGELOG.md: 오늘 변경사항
- TODO.md: 내일 할 일"
일주일에 한 번:
나: "문서들 정리해. 중복 제거하고 합쳐"
AI: "문서 37개 → 19개로 정리 완료"
새 오픈소스 찾을 때마다:
나: "korean-name-generator 찾았어. OPENSOURCE.md에 정리해"
AI: "추가 완료. MIT 라이선스, 사용법, 통합 코드 예시 포함"
진짜 깨달은 것
예전의 나
"어? 이 기능 어디 있더라?" → 파일 뒤지고, 검색하고, 30분 날리고
"이 에러 전에도 났는데..." → 구글링하고, 스택오버플로우 뒤지고, 1시간 날리고
"뭘 만들었는지 기억 안 남" → 코드 다시 읽고, 이해하려고 애쓰고
지금의 나
STRUCTURE.md 확인해" → 1초 만에 찾는다
ERRORS.md 확인해" → 해결법이 다 있다
CHANGELOG.md 확인해" → 모든 변경사항이 기록되어 있다
문서는 AI의 기억이다. 문서가 없으면 AI는 매번 깜빡이다. 있으면 완벽하게 기억한다.
그리고 가장 중요한 건, 내가 직접 안 써도 된다는 거다. 그냥 "정리해"라고만 하면 AI가 다 한다.
핵심 명령어 4개
이것만 기억하면 된다:
"분석해서 문서 만들어" - 처음 시작할 때
"이거 문서에 추가해" - 새로운 거 만들 때마다
"문서 정리해" - 일주일에 한 번
"중복 제거해" - 문서가 너무 많아졌을 때
실제 효과
문서 작성 시간: 0분 (AI가 함) 절약한 시간: 매일 3시간 충돌/에러: 90% 감소 생산성: 5배 증가
이 글을 읽는 동안에도 AI는 문서를 만들 수 있다.
지금 바로 터미널 켜고:
"현재 프로젝트 분석해서 PROJECT_INFO.md 만들어"
5분이면 끝난다
에필로그: 문서 = AI의 뇌
AI와 일하는 건 팀 프로젝트와 비슷하다.
새 팀원이 왔는데 아무 인수인계 없이 "어 그냥 해"라고 하면? 망한다.
하지만 깔끔한 문서가 있으면? "여기 다 있어. 확인하고 시작해."
AI도 똑같다. 문서가 있으면 천재가 되고, 없으면 바보가 된다.
왜냐고? 얘는 한 10분마다 새로운 팀원이 되기 때문이다.
그래서 앞으로 모든 프로젝트는 문서부터 시작한다.
그리고 도중에 문서를 업데이트 시킨다. 언제? 숨 쉬는 모든 순간에 새로운 기능, 정보, 버젼, 심지어 나의 한숨과 욕설까지 모든 걸 싹다 문서화 시킨다.
그리고 코드를 적을때 하나하나 문서를 보면서 코드를 적으라고 시킨다. 문서에 체크리스트 한줄한줄 만들어서 넣으라고 시키고, 끝날때마다 한줄한줄 체크를 시킨다. 귀찮아 보인다고?
"문서화는 AI가 한다. 넌 그냥 시켜라."
