Vibe Coding 방법론 · 제4강

주석 3요소와 코드 보호

AI가 작성하는 주석은 대부분 기능을 그대로 설명하는 것뿐입니다. 3개월 후에 코드를 다시 보면 왜 그렇게 구현했는지 기억하기 어렵습니다. 이번 강의에서는 주석에 구조를 부여하고 "코드 삭제"에 대한 규칙을 정립합니다. 페이지에 두 개의 인터랙티브 데모가 있습니다.

문제가 무엇인가

코드는 "무엇을 했는지"만 표현할 수 있습니다. 왜 존재하는지, 왜 이렇게 구현했는지, 호출 시 무엇을 주의해야 하는지 — 이 정보들은 주석에 기록해야만 시간을 넘어 보존됩니다. "주석을 잘 써라"라는 말은 AI가 실행할 수 없습니다. 고정된 구조와 예시를 제공해야 합니다.

3요소 구조

배경

이 함수가 어떤 비즈니스 문제를 해결하기 위한 것인지, 어떤 상황에서 호출되는지. 배경이 없으면 코드를 읽는 사람은 구현만 볼 수 있고, 왜 존재하는지는 알 수 없습니다.

설계 의도

왜 이렇게 구현했는지, 이 방식을 선택한 이유, 그리고 어떤 대안을 포기했는지. git log에서는 찾을 수 없으며, 주석이 유일한 기록 매체입니다.

핵심 제약

호출자가 알아야 할 것: 부작용, 의존 관계, 경계 조건 등 명확하지 않은 주의 사항. 이것이 없으면 다음 호출자가 함정에 빠지게 됩니다.

인터랙티브 데모 1 · 같은 함수, 두 가지 주석 스타일

같은 merge_chat_history 함수에 대한 두 가지 주석 스타일을 클릭하여 전환하고, 각각이 남기는 정보량을 비교해 보세요.

chat/history.py
          배경설계 의도핵심 제약
        
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    두 개의 채팅 기록 목록을 병합하여 병합된 결과를 반환합니다.
    """
    ...
def merge_chat_history(existing: list, incoming: list) -> list:
    """
    배경: 프론트엔드는 세션 복원 시마다 로컬에 캐시된 이전 메시지를 전송하지만,
    서버도 영속화된 기록을 보관합니다. 네트워크 중단으로 인해 두 기록이 분기될 수 있습니다.
    설계 의도: 서버 기록을 권위 있는 소스로 삼고, 로컬에만 있는 메시지만 추가합니다.
    전체 교체를 피하여 서버에 이미 있는 AI 응답 메타데이터를 덮어쓰지 않도록 합니다.
    제약: incoming에서 role=system인 메시지는 모두 버리고 결과에 병합하지 않습니다.
    """
    ...

이 주석은 함수명을 그대로 설명하고 있습니다. 코드를 한 번 보는 것과 같은 정보입니다. 3개월 후 "왜 서버를 권위 있는 소스로 삼는가" "왜 system 메시지를 버리는가"를 알고 싶어도 단서가 전혀 없습니다.

인터랙티브 데모 2 · 삭제할까 말까 — 당신이 판단하세요

세 가지 실제 시나리오에서 AI가 어떻게 해야 하는지 판단해 보세요. 선택지를 클릭하면 즉시 판정과 함께 해당 규칙 근거를 제시합니다.

시나리오 1 · AI가 리팩토링 중에 구형 데이터 형식과 호환하는 코드를 발견했습니다. "쓸모없어 보인다"고 판단하고 그냥 삭제하려고 합니다.

시나리오 2 · 리팩토링 후 구현 방식이 변경되어 기존의 "설계 의도" 주석이 코드와 맞지 않게 되었습니다.

시나리오 3 · AI는 fetch가 axios보다 가볍다고 생각하여 프로젝트의 axios를 fetch로 교체하고 package.json을 수정하려 합니다.

현재 정답: 0 / 3

두 가지 보호 규칙

주석 보호

리팩토링 시 "주석이 너무 길다", "코드가 자기설명적이다", "정리하는 김에"를 이유로 배경과 설계 의도 주석을 삭제하는 것을 금지합니다. 구현 변경으로 주석이 부정확해진 경우 반드시 내용을 동기화하여 업데이트해야 합니다. 판단 기준은 하나뿐입니다: 이 주석 없이도 미래의 인수자가 왜 그렇게 했는지 이해할 수 있는가?

코드 삭제 선언

기존 기능 코드를 삭제하기 전에 반드시 사용자에게 이유를 명시적으로 알려야 하며, "정리하는 김에", "쓸모없어 보인다"를 이유로 조용히 삭제하는 것을 금지합니다. 코드를 제거해야 한다고 판단되면 먼저 // TODO: 삭제 권장 - 이유: xxx로 표시하고 허가를 받은 후 삭제합니다.

연계 규범 · 오류 처리

빈 catch 블록 금지. 모든 try/catch와 오류 분기는 실질적인 처리를 포함해야 합니다: 로그 기록 + 사용자에게 보이는 오류 메시지, 또는 합리적인 폴백 로직. console.log(e)만, pass, // ignore는 모두 조용한 오류 삼킴에 해당하며 절대 허용되지 않습니다.

이번 강의 핵심 포인트

주석의 사명은 코드가 표현할 수 없는 의사결정 정보를 보존하는 것입니다. 3요소 구조는 AI가 작성할 수 있는 형식을 제공하고, 보호 규칙은 삭제를 방지합니다. 두 가지가 함께 시간을 넘어 지식을 전달합니다.

출처: 이번 강의 내용은 오픈소스 저장소 itshen/xs_vibe_rules의 rule-opensource.mdc 제7장 "코드 구성 및 규범"에서 발췌했습니다.

주석 3요소와 코드 보호

배경

설계 의도

핵심 제약

기능 설명형 주석

3요소 주석

주석 보호

코드 삭제 선언