바이브 코딩 문서화 완전 정리

AI는 코드가 무엇을 하는지는 잘 적지만 왜 그렇게 됐는지는 적지 못합니다. 그 이유는 코드에도 커밋 메시지에도 없고, 대개 회의나 장애 대응 중에 오간 대화 속에만 남아 있기 때문입니다. 문서화에서 AI가 확실히 이기는 영역은 형식 변환과 초안 작성이고, 지는 영역은 의도와 맥락입니다. 이 경계를 흐린 채 자동 생성에 기대면 문장은 전부 사실인데 정작 아무도 찾던 답을 얻지 못하는 문서가 대량으로 만들어집니다. 문서량이 늘어난 만큼 신뢰도는 떨어지는 상태가 가장 나쁜 결과입니다.

문서 초안은 AI로 빠르게 작성이 기본 리듬을 잡아 줍니다. 기계가 초안, 사람이 검수라는 순서입니다. API 문서 OpenAPI 스펙 자동화와 시퀀스 다이어그램을 텍스트로 설명하면 AI가 Mermaid 코드로 변환해준다는 그 리듬이 가장 안전하게 먹히는 사례입니다. 입력이 이미 코드이거나 사람이 직접 쓴 설명이라 지어낼 여지가 적습니다. 반대로 기술 결정 이력(ADR)을 AI 도움으로 작성하라는 판단 근거를 사람이 먼저 말해줘야 비로소 성립하는 쪽이니, 앞의 둘과는 다른 태도로 읽어야 합니다.

실제로 다치는 곳은 런북입니다. 복구 절차를 요청하면 형식이 완벽하고 명령어까지 채워진 문서가 나오는데, 그 명령이 우리 클러스터에서 실제로 통하는지는 아무도 확인하지 않은 상태입니다. 문제는 새벽 세 시에 그 문서를 처음 열어보는 사람이 그것을 검증된 절차로 믿는다는 점입니다. 실행 계열 문서는 초안을 받은 뒤 스테이징에서 한 번 그대로 따라 해보기 전까지 공유 위치에 올리지 않는다는 규칙을 팀 차원에서 정해두는 편이 안전합니다.