문서의 목적은 커뮤니케이션이다. 바이브 코딩은 그 대화에 참여하는 주체를 늘린다.

정도현 - 로보코 수석 컨설턴트

TL;DR

  • 바이브 코딩에도 기존 문서화 원칙이 적용된다. 에이전트에게 작성과 정리를 맡기면 적은 수고로 모범 사례의 혜택을 누릴 수 있다.
  • 계속 갱신할 기준 문서와 목적을 달성하면 역할을 마치는 일회성 문서를 구분하라. 모든 문서를 현행화할 필요는 없다.
  • 문서는 짧은 마크다운으로 나누고 폴더별 인덱스와 규칙, 스킬로 연결하라. 필요한 작업에서 찾아 읽을 수 있어야 한다.
  • 자주 빠르게 확인할 내용은 열거형으로, 맥락을 이해하고 깊이 검토할 내용은 서술형으로 작성하라.
  • 문서는 사람과 사람, 사람과 AI, AI와 AI가 의도와 판단 기준을 공유하는 수단이다. 사람은 목적을 정하고 결과를 판단하는 데 집중하라.

여러 차례 밝혔듯이 바이브 코딩에도 기존 소프트웨어 개발의 원칙이 그대로 적용된다. 문제를 정의하고 설계한다. 구현하고 검증한다. 결과를 검토하고 개선한다. 사람이 하든 에이전트가 하든 이 과정은 필요하다. 달라지는 것은 각 단계를 수행하는 주체와 비용이다.

앞서 작성한 「바이브 코딩에 대한 진실 혹은 거짓」에서도 같은 이야기를 했다. 테스트와 설계, CI/CD 같은 모범 사례는 바이브 코딩에서도 통용된다. 「바이브 코딩과 엔지니어링 성숙도 향상, 어느쪽이 먼저일까?」에서는 한 걸음 더 나아갔다. 에이전트는 이미 갖춘 개발 체계를 활용할 뿐 아니라, 그 체계를 갖추는 일도 도울 수 있다.

문서화도 동일한 원칙을 따른다. 좋은 문서가 주는 혜택은 이전과 같다. 다만 그 혜택을 얻기 위해 사람이 들여야 하는 수고가 크게 줄어든다. 코드에서 사용법을 추출하고, 변경 사항을 반영하고, 문서를 분류하는 작업은 에이전트에게 맡길 수 있다. 사람이 일일이 작성하던 때보다 훨씬 적은 시간과 노력으로 문서를 갖출 수 있다.

이제 문서 관리에서 먼저 물어야 할 것은 두 가지다. 이 문서는 언제까지 유효한가. 그리고 누가 어떤 목적으로 읽는가.

1. 에이전트에게 문서는 다음 작업의 출발점이다

사람이 개발할 때도 문서는 중요하다. 코드만으로는 왜 이런 선택을 했는지 알기 어렵다. 일정 때문에 포기한 대안도 있다. 고객과 합의한 예외도 있다. 구현은 현재의 동작을 보여준다. 문서는 그 동작을 선택한 이유와 지켜야 할 조건을 전달한다.

바이브 코딩에서는 이 역할이 더 중요해진다. 사람은 지난 회의와 작업을 어느 정도 기억한다. 에이전트는 새 세션을 시작할 때 이전 대화를 모두 이어받는다고 보장할 수 없다. 대화가 길어져 요약되면 중요한 조건이 빠질 수도 있다. 다른 에이전트에게 일을 넘기면 같은 설명이 다시 필요하다.

예를 들어 결제 요청이 실패했을 때 자동으로 재시도하지 않기로 했다고 하자. 중복 결제를 막기 위해 외부 결제사의 처리 상태부터 확인해야 하기 때문이다. 이 맥락이 대화에만 남아 있다면 다음 에이전트는 재시도 로직을 개선 사항으로 제안할 수 있다. 코드만 보면 복구 기능이 빠진 것으로 보이기 때문이다.

문서에 이 제약과 이유를 남겨두면 다음 작업의 출발점이 달라진다. 에이전트는 같은 논의를 반복할 필요가 없다. 검토하는 사람도 구현이 합의한 조건을 지켰는지 판단할 수 있다.

여러 에이전트가 나눠서 개발할 때도 마찬가지다. 서로 다른 가정으로 작업하면 각자의 구현은 맞아도 전체 시스템은 어긋난다. 공유한 API 계약과 완료 기준은 이 차이를 줄인다. 문서는 사람과 AI 사이의 설명서이자, AI와 AI 사이의 협업 기준이 된다.

2. 모든 문서를 계속 고칠 필요는 없다

개발 문서는 라이프사이클 관점에서 두 종류로 나눌 수 있다. 현재의 기준을 전달하기 위해 계속 유지보수하는 문서가 있다. 특정 시점의 커뮤니케이션을 마치면 역할을 다하는 일회성 문서도 있다.

설치 가이드와 API 명세, 현재 아키텍처 설명, 운영 절차는 첫 번째에 속한다. 독자는 이 문서를 지금 적용할 수 있는 기준으로 읽는다. 실행 명령이 바뀌면 설치 가이드도 바뀌어야 한다. 장애 대응 절차가 달라지면 운영 문서도 함께 고쳐야 한다. 관련 코드를 바꾸는 작업의 완료 조건에 문서 갱신을 넣어두면 좋다.

특정 버그의 조사 메모, 한 번의 배포를 위한 작업 계획, 리뷰 요청용 설명, 다음 세션에 넘기는 인계 문서는 두 번째에 속한다. 해당 작업이 진행되는 동안에는 보완할 수 있다. 그러나 작업이 끝난 뒤에도 계속 현재 상태에 맞춰 고칠 이유는 없다. 그 시점의 상황을 전달했다면 목적을 달성한 것이다.

일회성이라는 말이 곧바로 삭제하라는 뜻은 아니다. 회의록이나 결정 기록은 나중에 당시의 판단을 확인하는 자료가 될 수 있다. 이런 기록은 과거의 맥락을 보존해야 한다. 결정이 바뀌면 기존 기록을 오늘의 결론으로 덮어쓰지 말고, 새 결정과 연결하면 된다. 기록의 보존과 내용의 현행화는 서로 다른 일이다.

이 구분이 없으면 모든 문서가 유지보수 대상이 된다. 기능 하나를 바꿀 때마다 과거의 계획서와 조사 메모까지 고친다. 사람은 시간을 쓰고 에이전트는 토큰을 쓴다. 그러다 보면 문서를 만들수록 일이 늘어난다는 결론에 도달한다. 결국 설명이 필요한 순간에도 문서 작성을 피하게 된다.

문서를 만들 때 용도와 유효 범위를 함께 적어라. 현재 기준 문서인지, 특정 작업을 위한 기록인지 밝혀라. 일회성 문서에는 날짜와 대상 작업, 완료 여부를 남겨라. 작업이 끝나면 현재 작업의 인덱스에서 빼고 보관 경로로 연결하라. 다음 에이전트가 과거의 계획을 현재의 지시로 읽지 않게 해야 한다.

일회성 문서에서 오래 쓸 지식이 나올 수도 있다. 버그 조사 중 발견한 제약은 운영 가이드에 반영한다. 리뷰에서 합의한 규칙은 개발 지침에 옮긴다. 필요한 지식만 현재 기준으로 옮기고 조사 메모는 기록으로 남긴다. 이렇게 하면 커뮤니케이션에 필요한 문서를 부담 없이 만들 수 있다.

3. 문서는 작업 중에 찾아 읽을 수 있어야 한다

문서를 저장했다고 에이전트가 알아서 활용하는 것은 아니다. 어떤 작업에서 무엇을 읽어야 하는지 연결해야 한다. 앞서 쓴 「바이브 코딩의 토큰 관리 전략」에서도 필요한 문서를 선별해서 읽는 구조를 강조했다. Anthropic 역시 파일 경로 같은 가벼운 참조를 유지하고, 필요한 순간에 내용을 불러오는 접근을 설명한다.1

에이전트가 참조할 개발 문서는 마크다운을 기본으로 삼는 편이 좋다. 제목과 문단, 링크로 구조를 드러낼 수 있다. 검색과 부분 수정이 쉽다. 코드와 같은 저장소에 두면 변경 이력도 함께 관리할 수 있다.

한 문서는 가능하면 300줄 이하로 유지하라. 이는 모든 도구에 통용되는 기술적 제한이 아니라 실무 기준이다. 줄 수가 같아도 토큰 수는 다르다. 숫자를 맞추기 위해 문장을 한 줄에 몰아넣는 것은 의미가 없다. 하나의 문서가 하나의 주제를 다루게 하고, 길어지면 주제별로 나누라는 뜻이다. 리뷰에 필요한 논리까지 끊어서는 안 된다.

폴더도 용도에 따라 나누어라. 예를 들어 docs/guides/에는 현재 사용하는 안내를 둔다. docs/tasks/에는 진행 중인 작업 문서를 둔다. 끝난 작업 기록은 docs/archive/에 보관한다. 각 폴더의 README.md에는 짧은 설명과 주요 문서 링크를 넣는다. 사람도 폴더를 열면 어디서 읽기 시작해야 할지 알 수 있어야 한다.

에이전트를 위한 진입점도 필요하다. 사용하는 도구에 맞춰 AGENTS.md나 CLAUDE.md에 공통 규칙과 문서 경로를 적어라. 단순히 링크만 나열하지 말고 언제 읽을지도 밝혀라. 결제 기능을 수정할 때는 결제 계약과 중복 처리 정책을 먼저 확인하도록 적는 식이다. 두 파일을 함께 쓴다면 공통 규칙의 기준을 하나로 정해 내용이 어긋나지 않게 하라.

반복되는 작업은 스킬로 연결하면 좋다. 배포 스킬은 운영 절차와 배포 점검 문서를 읽도록 구성한다. API 변경 스킬은 계약 문서를 확인하고 변경 후 명세까지 갱신하도록 구성한다. 문서가 실제 작업 순서 안에서 소비되는 것이다.

참조할 문서가 수백 개를 넘어가면 인덱스를 따라가는 것만으로도 버거울 수 있다. 이때는 LLM Wiki를 도입하는 방법도 있다. Karpathy가 제안한 LLM Wiki는 원본 자료와 별도로, LLM이 서로 연결된 마크다운 위키를 만들고 갱신하는 방식이다.2 프로젝트에 적용하면 흩어진 자료의 개념과 관계를 정리하는 데 활용할 수 있다. 요약에서 원문으로 돌아갈 수 있도록 출처도 남겨야 한다. 문서 개수 자체보다는 같은 맥락을 반복해서 찾고 조합하는 부담이 도입 기준이다.

이 구조를 사람이 파일 하나씩 손으로 정리할 필요는 없다. 에이전트에게 기존 문서를 용도별로 분류하고, 긴 문서를 나누고, 폴더마다 인덱스를 만들라고 지시하면 된다. 이후의 갱신도 작업 규칙에 포함할 수 있다. 사람은 무엇을 현재의 기준으로 삼을지 판단하고 결과를 확인하면 된다. 반복 정리에 드는 수고는 줄이되, 잘못된 내용을 기준으로 굳히지는 않아야 한다.

4. 자주 확인하는 문서는 열거형으로 작성하라

문서를 어떻게 보관하고 연결할지 정했다면, 이제 내용을 어떻게 전달할지 정해야 한다. 크게 열거형과 서술형이 있다. 마크다운은 두 형식을 모두 담을 수 있다. 문서의 수명과 표현 형식도 별개의 선택이다.

별다른 지시를 하지 않으면 에이전트는 항목과 표를 적극적으로 사용하는 경우가 많다. 열거형은 짧은 시간에 전체를 훑기 좋다. 필요한 항목을 찾기 쉽고 누락 여부도 확인하기 쉽다.

배포 체크리스트와 명령어 모음, 환경 변수 설명, API 필드 명세가 좋은 예다. 이런 문서는 자주 열어 특정 정보를 빠르게 확인한다. 배포 직전에 필요한 것은 실행 순서와 성공 조건이다. 이미 합의한 절차를 수행할 때마다 긴 배경 설명을 다시 읽을 필요는 없다.

반면 판단의 근거까지 검토해야 한다면 항목만으로는 부족할 수 있다. 설계안에 성능 개선, 비용 절감, 확장성 확보가 적혀 있다고 하자. 훑어보기는 쉽다. 그러나 무엇이 얼마나 느린지 알 수 없다. 어떤 비용을 줄이는지도 불분명하다. 확장성을 얻기 위해 무엇을 포기하는지도 보이지 않는다.

독자는 그럴듯한 항목을 읽고 내용을 이해했다고 느낄 수 있다. 하지만 실제 판단에 필요한 맥락은 작성자의 머릿속에 남아 있다. 리뷰가 시작되면 항목마다 설명을 요청해야 한다. 같은 문서를 여러 번 읽어도 생략된 근거는 나타나지 않는다.

항목 사이의 관계가 드러나지 않으면 나중에 판단 과정을 떠올리기도 어렵다. 무엇을 하기로 했는지는 기억해도 왜 그랬는지는 놓치기 쉽다. 열거형은 빠른 확인에 강하다. 깊은 검토에서는 배경과 근거를 설명하는 문장이 함께 필요하다.

5. 깊이 검토할 문서는 서술형으로 작성하라

서술형은 문제와 조건, 대안과 결론을 문장으로 연결한다. 독자는 그 흐름을 따라가며 자신의 생각을 정리한다. 작성자는 결론으로 넘어가기 전에 빠진 설명을 채워야 한다.

앞서 쓴 「인지부채 - 바이브 코딩 시대의 새로운 부채 관리법」에서도 두 형식을 비교했다. 세션 저장소를 Redis로 이전하는 같은 결정을 열거형과 서술형 ADR로 각각 보여줬다. 열거형 예시는 선택과 근거를 짧게 나열했다. 서술형 예시는 병목의 배경과 대안을 제외한 이유, 선택한 설계의 실패 조건까지 연결했다. 그 차이 덕분에 독자는 결정의 근거를 따져 물을 수 있었다. 두 형식의 구체적인 비교는 해당 글의 ‘셋째, 서술형 문서’ 부분을 참고하라.

아마존은 이런 문서를 선호하는 기업으로 잘 알려져 있다. Andy Jassy는 2024년 주주서한에서 본문 최대 여섯 쪽의 서술형 문서를 사용한다고 설명했다. 작성자는 더 수고해야 하지만, 독자는 핵심 문제를 이해하고 적절한 질문을 하기 쉬워진다는 이유다.3

앞의 설계안을 서술형으로 바꾸면 차이가 드러난다. 가상의 주문 시스템을 생각해보자. 주문 요청이 들어오면 외부 서비스의 응답을 기다린다. 외부 서비스가 느려지면 주문 접수도 함께 지연된다. 그래서 접수와 후속 처리를 분리하려 한다. 다만 처리 완료까지 시간차가 생긴다. 사용자에게 진행 상태를 보여줘야 한다. 중복 요청도 별도로 막아야 한다.

이제 리뷰어는 어디를 검토해야 할지 알 수 있다. 사용자가 그 시간차를 받아들일 수 있는지 판단한다. 외부 서비스 호출만 개선하는 대안은 없는지 묻는다. 운영 복잡성이 늘어나는 대가도 따져본다. 문장이 이어지면서 검토할 가정과 인과관계가 드러나기 때문이다.

서술형은 읽는 데 시간이 더 걸릴 수 있다. 그러나 문서의 글자 수만으로 커뮤니케이션 비용을 계산해서는 안 된다. 짧은 목록을 이해하기 위해 회의를 열고 작성자에게 설명을 듣는 시간도 비용이다. 필요한 맥락을 문서에 담으면 독자는 한 번의 읽기 안에서 판단을 이어갈 수 있다.

이렇게 원인과 결과를 연결해 읽으면 나중에 결정의 이유를 떠올리는 데도 도움이 된다. 서술형이면 언제나 더 오래 기억한다는 뜻은 아니다. 기억을 돕는 것은 분량 자체가 아니라 의미 있는 연결이다. 같은 말을 길게 반복하는 문서는 서술형의 장점을 살리지 못한다.

사람에게는 이런 글을 쓰는 일이 부담이었다. 에이전트를 쓰면 그 부담이 크게 줄어든다. 같은 자료를 주고 배경과 대안, 선택의 이유를 이어서 설명하라고 지시하면 된다. 작성 지시의 수고는 열거형과 크게 다르지 않다. 다만 글이 길어지면 생성 시간과 토큰은 늘 수 있다. 근거가 없는 부분을 그럴듯한 문장으로 채우지 않았는지도 확인해야 한다.

아키텍처 제안서와 기술 도입 검토서, 제품 요구사항의 배경 설명, 장애 원인 분석 문서에 이 형식을 권한다. 이해관계자의 판단과 합의가 필요한 문서라면 서술형을 기본으로 삼아라. 문제와 제약, 검토한 대안, 선택한 이유, 남은 쟁점을 연결해서 적어라. 짧은 요약이나 비교표를 보조로 붙여도 좋다.

TL;DR은 열거형과 서술형 모두에서 유용하다. 열거형에서는 핵심 항목을 먼저 보여줘 필요한 정보를 찾는 시간을 줄인다. 서술형에서는 문제와 결론을 미리 짚어줘 독자가 논지의 흐름을 따라가기 쉽게 한다. 독자는 요약을 보고 지금 읽어야 할 문서인지 판단할 수 있다. 이미 읽은 문서의 핵심을 다시 떠올릴 때도 도움이 된다.

서술형 문서 앞에 열거형 요약을 붙여도 본래 목적에 어긋나지 않는다. 요약은 읽기의 출발점을 제공하고, 본문은 판단에 필요한 맥락과 근거를 전달한다. 이 글 앞의 TL;DR도 같은 역할을 한다. 다만 리뷰가 목적이라면 요약만으로 검토를 마쳐서는 안 된다. 요약으로 방향을 잡고 본문에서 가정과 근거를 확인하라.

같은 배포 작업에서도 두 형식을 함께 쓸 수 있다. 배포 전략을 바꾸는 제안서는 서술형으로 작성한다. 합의한 전략을 실행하는 체크리스트는 열거형으로 작성한다. 제안서는 당시 판단의 기록으로 남긴다. 체크리스트는 현재 절차에 맞춰 갱신한다. 문서의 수명과 읽는 목적을 각각 정하면 관리 방식도 자연스럽게 정해진다.

결론

개발에서 문서화가 중요하다는 말은 새롭지 않다. 바이브 코딩에서는 그 중요성이 더 커진다. 사람은 개발을 시작하며 목적과 제약, 완료 기준을 정한다. 개발이 끝나면 결과와 검증 근거를 읽고 의도대로 만들어졌는지 판단한다. 문서는 사람이 주도하는 첫 단계이자 마지막 단계의 중심에 놓인다.

나는 구현과 테스트, 배포와 반복 정비까지 점점 더 많은 실행을 에이전트가 맡게 될 것이라 본다. 궁극적으로 문서를 통해 의도를 정하고 결과를 판단하는 일 이외의 실행은 에이전트의 영역으로 옮겨갈 것이다. 그렇다고 사람의 책임까지 사라지는 것은 아니다. 무엇을 만들고 어떤 결과를 받아들일지는 여전히 사람이 결정한다.

모든 문서를 영구히 관리하려 하지 마라. 필요한 커뮤니케이션을 위해 일회성 문서도 적극적으로 만들어라. 계속 사용할 지식은 현재 기준으로 옮겨라. 자주 확인할 내용은 열거형으로, 깊이 검토할 내용은 서술형으로 작성하라. 그리고 필요한 순간에 찾아 읽을 수 있도록 연결하라.

문서의 목적은 결국 커뮤니케이션이다. 소프트웨어 개발은 사람과 사람이 이해를 맞추는 일이다. 이제 그 관계에 사람과 AI, AI와 AI가 더해졌다. 구현을 더 많이 맡길수록 서로 같은 뜻으로 일하게 만드는 일이 더 중요해진다.

  1. Anthropic, Effective context engineering for AI agents. ↩︎

  2. Andrej Karpathy, LLM Wiki. ↩︎

  3. Amazon, Andy Jassy’s 2024 Letter to Shareholders, “Narratives” 부분. ↩︎