설계 비교, 결과 검증, 목표 구체화, 문서 관리, 모르는 건 질문

오늘은 바이브 코딩을 하면서 중요하게 느꼈던 것들을 적습니다. 이미 알고 계신 분들도 많겠지만, 처음 입문하시는 분들께 조금이나마 도움이 되었으면 합니다.

처음에는 말 몇 마디로 게임이 만들어지고 기능이 붙는 것만으로도 신기합니다. 그런데 작업을 이어가다 보면 생각했던 것과 다른 결과가 나오거나, 잘 돌아가던 기능이 수정 후에 깨지는 상황을 만납니다. 이때부터는 무엇을 시킬지, 무엇을 기준으로 확인할지가 중요해집니다.

참고한 발표에서는 사람이 요구사항과 설계를 검토하고, 에이전트가 구현한 결과물을 수락 테스트로 확인하는 관점을 다룹니다. 수락 테스트는 어렵게 생각할 필요 없이, 처음 요청한 조건대로 만들어졌는지 확인하는 과정입니다. 무엇을 만들고, 왜 그렇게 만들며, 어떤 상태를 완성으로 볼 것인지는 사람이 판단해야 합니다. 작업하면서 신경 쓰는 부분도 이와 연결됩니다.

1. 프로젝트의 뼈대를 하나의 세션에서만 결정하지 않기

프로젝트를 구상할 때 최대 네 개의 새 세션에서 각각 뼈대를 만들게 합니다. 만든 스킬에는 ‘매치업’이라는 이름을 붙였습니다. 같은 목표와 조건을 주고 각자 설계하게 한 다음, 서로의 결과를 비교하게 하는 방식입니다.

어떤 설계에는 필요한 기능이 빠져 있고, 어떤 설계에는 지금 만들 필요도 없는 구조가 잔뜩 들어가기도 합니다. 이걸 비교하면서 부족한 부분을 찾고, 불필요한 설계를 잘라냅니다.

처음 나온 설계가 그럴듯하면 그대로 구현을 시작하기 쉽습니다. 그런데 그 설계가 정말 지금 프로젝트에 맞는지, 더 단순하게 만들 수는 없는지 한 번쯤 다른 관점에서 확인할 필요가 있습니다.

물론 작은 기능 하나를 만들 때까지 매번 네 개의 세션을 열 필요는 없습니다. 나중에 바꾸기 어려운 구조를 정하거나, 어느 방향이 좋을지 판단하기 어려울 때 활용하는 정도로 생각하시면 됩니다. 그리고 최종적으로 어떤 설계를 선택했는지뿐 아니라, 왜 그 설계를 선택했는지도 짧게 남겨두는 게 좋습니다.

2. 코드를 작성한 세션의 테스트만으로 끝내지 않기

코드를 작성한 모델에게 테스트까지 맡기면, 구현할 때 가정했던 범위 안에서만 확인하는 경우가 있습니다. 잘못 이해한 요구사항을 바탕으로 코드를 만들고, 그 이해에 맞춰 테스트를 만들면 둘 다 맞아 보일 수 있습니다. 테스트는 통과했는데 원했던 동작은 아닌 상황이 생기는 겁니다.

그래서 구현한 뒤 다른 세션에서 엣지케이스와 실제 사용 상황을 검토하게 합니다. 엣지케이스는 평소에는 잘 나오지 않지만 문제가 생기기 쉬운 경계 상황입니다.

게임으로 예를 들면 이런 것들입니다.

  • 보상 버튼을 빠르게 여러 번 눌러도 보상이 한 번만 지급되는가?
  • 저장한 뒤 게임을 완전히 종료하고 다시 실행해도 진행 상황이 유지되는가?
  • 에디터에서 되던 기능이 실제 기기에 설치한 빌드에서도 동작하는가?

구현 중에도 기본적인 테스트는 계속해야 합니다. 그 위에 다른 관점의 검증을 한 번 더 두자는 뜻입니다. 검증할 세션에는 원래 요구사항과 변경 내용을 함께 주고, 어떤 조건에서 실패하는지 찾아보게 합니다. 문제를 찾았다면 재현 방법과 기대했던 결과, 실제 결과까지 확인하도록 하는 편이 좋습니다.

세션을 나눴다는 사실만으로 검증이 끝나는 것은 아닙니다. 다른 세션도 같은 가정을 할 수 있습니다. 머릿속으로 상황을 시뮬레이션한 것과 실제 실행해서 확인한 것도 구분해야 합니다. “문제없을 것 같습니다”와 “이 조건으로 실행했고, 이렇게 동작했습니다”는 다른 이야기입니다.

3. 내가 무엇을 만들고 싶은지부터 구체화하기

바이브 코딩이라는 말과 조금 모순적으로 들릴 수도 있습니다. 그런데 이 부분이 가장 먼저라고 생각합니다. 주변에서도 본인이 정확히 무엇을 원하는지 정리하지 않은 상태로 일단 만들어달라고 하는 경우를 자주 봤습니다. 그렇게 나온 결과가 마음에 들지 않으면 다시 고치고, 고치다 보면 처음 생각했던 것과 다른 프로젝트가 되기도 합니다.

예를 들어 “재미있는 방치형 게임을 만들어줘”만으로는 판단할 수 있는 범위가 너무 넓습니다. 플레이어가 직접 하는 행동은 무엇인지, 한 판을 얼마나 플레이하게 할 것인지, 어떤 기기에서 실행할 것인지, 이번에 어디까지 만들 것인지 정도는 정할 필요가 있습니다. 완성됐다고 판단할 기준도 함께 정하면 좋습니다.

처음부터 모든 것을 알 필요는 없습니다. 잘 모르겠다면 바로 구현을 시키기 전에, AI에게 빠진 조건을 질문하게 하고 계획부터 정리해도 됩니다. 중간에 생각이 바뀌는 것도 자연스러운 일입니다. 다만 바뀌었다면 무엇이 달라졌는지 다시 정리해야 이후 작업도 같은 방향으로 갈 수 있습니다. 내가 원하는 결과를 구체적으로 설명할수록, 결과물을 확인할 기준도 분명해집니다.

4. README와 작업 지침, 주석도 계속 확인하고 갱신하기

이 부분은 처음에 “프로젝트가 완성되기 전에는 주석이나 문서를 작성하지 않게 한다”고 표현했던 내용인데, 설명을 보충하고 싶습니다. 그렇게만 쓰면 앞에서 목표와 요구사항을 명확하게 하자는 이야기와 상충해 보입니다. README.md나 AGENTS.md 같은 문서를 쓰지 말자는 뜻으로 받아들여질 수도 있습니다.

강조하고 싶은 것은, 문서가 이후 작업의 기준이 되는 만큼 잘못된 내용이 남아 있지 않도록 지속적으로 확인해야 한다는 점입니다. 요구사항, 작업 규칙, 설계를 선택한 이유, 확인 기준은 초기에 기록해두는 편이 좋습니다. 다만 그 기록을 한 번 만들었다고 끝난 것으로 생각하면 안 됩니다.

아직 계획 중인 기능이 구현된 것처럼 적혀 있거나, 실제로 확인하지 않은 동작이 검증 완료로 적혀 있으면 다음 작업의 잘못된 전제가 될 수 있습니다. 코드는 바뀌었는데 예전 주석이나 문서가 그대로 남는 경우도 마찬가지입니다.

그래서 문서에는 적어도 다음 상태를 구분해두면 좋겠습니다.

  • 앞으로 만들기로 한 것
  • 코드에 구현된 것
  • 실제로 실행해서 확인한 것

그리고 기능이나 설계가 바뀔 때 관련 문서와 주석도 함께 확인하는 겁니다. AI에게 정리를 맡기더라도, 기록된 내용과 실제 변경 사항이 맞는지는 확인해야 합니다.

참고 자료에서도 ‘왜 그렇게 만들었는지’에 대한 기록을 중요하게 다룹니다. 코드에 숫자나 제한 조건은 남아 있어도, 그 조건을 정한 이유까지 드러나지는 않을 수 있습니다. 예를 들어 적의 최대 등장 수를 제한했다면, 성능 때문에 정한 것인지 게임 난이도 때문에 정한 것인지 이유가 필요합니다. 그 기록이 없으면 나중에 정리하는 과정에서 의도적으로 둔 제한을 불필요한 것으로 판단할 수도 있습니다.

3번이 목표와 기준을 정하는 일이라면, 4번은 그 기준과 기록이 현재 프로젝트에 맞게 유지되도록 관리하는 일입니다. 문서가 중요한 만큼 계속 봐야 한다는 이야기입니다.

5. 확실하지 않은 개발 지식을 요구사항으로 못 박지 않기

조금 직설적으로 말하면, AI에게 아는 척하지 않는 게 좋다고 생각합니다. 어디서 들어본 개발 용어나 패턴을 정확히 이해하지 못한 상태에서 “반드시 이 방식으로 만들어야 한다”고 요구하는 경우가 있습니다. 그러면 확인되지 않은 생각이 프로젝트의 고정된 조건으로 들어가게 됩니다.

원하는 동작과 제약은 분명히 말하면 됩니다. 예를 들어 “화면이 바뀌어도 진행 상황이 유지돼야 한다”, “기존 저장 데이터를 잃으면 안 된다” 같은 내용입니다. 구현 방법이 확실하지 않다면 질문으로 전달하면 됩니다.

이 방법이 적절할 것 같은데, 우리 프로젝트에도 맞는지 검토해줘. 더 단순한 방법이 있으면 이유와 함께 비교해줘.

이렇게 말하면 그 생각도 검토 대상에 들어갑니다. 개발 지식을 공부하지 말자는 뜻은 아닙니다. 알고 있는 사실과 아직 확인하지 않은 추측을 구분해서 전달하자는 뜻입니다. 물론 AI가 제시한 방법 역시 설명만으로 확정하지 말고, 프로젝트 조건과 실제 동작으로 확인해야 합니다.

AI에게 구현을 맡기는 범위가 넓어질수록, 결정한 요구사항과 그 이유를 설명할 수 있어야 한다고 생각합니다. 결과물을 받아들일 때도 “AI가 다 됐다고 했다”에서 끝내기보다, 어떤 조건을 확인했고 아직 확인하지 못한 부분은 무엇인지 알고 있어야 합니다.

특히 결제나 계정 권한, 데이터 삭제처럼 잘못됐을 때 되돌리기 어려운 기능은 구현 내용까지 더 면밀하게 살펴볼 필요가 있습니다. 처음부터 모든 과정을 거창하게 갖추실 필요는 없습니다. 지금 만드는 기능 하나에서 원하는 결과를 적고, 다른 관점으로 확인하고, 바뀐 내용을 기록하는 것부터 시작하셔도 좋겠습니다.

저도 계속 시행착오를 겪고 있습니다. 지금까지 작업하면서 중요하게 느낀 부분들을 공유해봤습니다. 다른 분들은 어떤 방식으로 작업하고 확인하시는지도 궁금합니다.