AI로 코드 뽑다 프로젝트 망하는 당신을 위한 실전 아키텍처 생존법

혹시 이런 경험 있으신가요? 제 이야기를 듣고 고개를 끄덕일 분들이 많을 것 같습니다.

번뜩이는 앱 아이디어가 떠올랐습니다. 이걸 어떻게 만들어야 할지는 막막했지만, 일단 AI 챗봇을 켜고 아이디어를 설명했어요. 그랬더니 웬걸, 바로 실행 가능한 코드를 뚝딱 내놓는 겁니다. 코드를 돌려보니 정말 작동합니다. 마치 마법 같았죠. 한 달 전만 해도 꿈도 못 꿨던 코드가 제 화면에서 돌아가는 걸 보고 있자니, 저절로 감탄사가 나왔을 겁니다.

그래서 기능 하나를 더 추가했습니다. 그리고 또 하나를 더했죠. 그렇게 다섯 번째 기능쯤 추가했을 때였을 겁니다. 뭔가 삐걱거리기 시작합니다. 겨우 하나를 고치면 다른 두 개가 작동을 멈추고요. AI에게 다시 물어봐도, 정작 제가 무엇이 문제인지 설명조차 할 수 없습니다. 제 프로젝트인데도 더 이상 이해할 수 없게 된 거죠. 마치 불 꺼진 방에서 폭탄을 해체하는 기분이 들 겁니다.

바로 이 지점에서 대부분의 사람이 좌절합니다. 코딩 자체가 아니라, 이 '벽'에 부딪혀서 말이죠. 그리고 아무도 알려주지 않는 진실이 하나 있습니다. AI는 코드를 작성하는 장벽을 허물었을 뿐, 코드를 구조화하는 장벽을 없애주진 않았다는 겁니다. 이 두 가지는 전혀 다른 기술이며, 이제는 후자가 프로젝트를 계속 발전시킬 수 있을지, 아니면 결국 무너지는 걸 지켜봐야 할지를 결정합니다.

이 가이드는 바로 그 '벽'을 넘어서기 위한 생존 지침서입니다. 컴퓨터 공학 학위는 필요 없습니다. 단지 AI로 만든 프로젝트가 스파게티 코드로 변질되는 것을 막아줄 몇 가지 습관들을, 완전히 초보자의 눈높이에서 설명해 드릴 겁니다.

진짜 문제: 이해하는 속도보다 코드를 생성하는 속도가 빠르다

실질적인 방법론을 이야기하기 전에, 초보자들이 생각하는 것과 다른, 진짜 문제가 무엇인지 먼저 파악해야 합니다.

문제는 AI가 나쁜 코드를 작성해서 생기는 경우가 거의 없습니다. 진짜 문제는 AI가 프로젝트의 전체적인 작동 방식을 이해하기도 전에 실행 가능한 앱을 만들어 버린다는 것입니다. 비유하자면, 조종석의 계기판이 보이지 않는 비행기를 조종하는 것과 같죠. 자동 조종 장치가 작동하는 동안은 괜찮지만, 뭔가 조정해야 할 순간이 오면 어디를 손대야 할지 몰라 헤매게 됩니다. 왜냐하면, 애초에 아무것도 배운 적이 없기 때문입니다.

'아키텍처'라고 하면 거창하고 어려운 컴퓨터 공학 용어처럼 들릴 수 있습니다. 하지만 전혀 그렇지 않아요. 간단히 말해 아키텍처는 그저 여러분의 프로젝트가 어떤 '모양'을 하고 있는지를 뜻합니다. 어떤 조각들로 이루어져 있고, 각 조각이 어떤 일을 하며, 어떻게 서로 연결되어 있는지를 말이죠. 그리고 이 '구조'가 있어야 프로젝트를 이해할 수 있습니다. 이해할 수 있어야만 프로젝트가 커지는 과정에서 허우적대지 않고 계속해서 발전시켜 나갈 수 있습니다.

그래서 이 가이드의 목표는 딱 하나입니다. 프로젝트가 성장하는 동안에도, 스스로 이해할 수 있는 상태를 유지하는 것. 아래 모든 내용은 이 목표를 달성하기 위한 것입니다.

생존 기술 #1: 조각들을 분리하라

이것이 가장 중요하고 기본적인 습관이니, 가장 많은 주의를 기울이세요.

그냥 두면 AI는 종종 모든 것을 하나의 거대한 파일에 쑤셔 넣곤 합니다. 화면을 그리는 부분, 실제 작업을 수행하는 로직, 데이터베이스와 통신하는 부분이 모두 뒤섞여 있죠. 처음에는 잘 작동합니다. 하지만 모든 것이 한곳에 뭉쳐 있으면, 어떤 작은 변경이라도 모든 것을 망가뜨릴 위험이 생깁니다. 아무것도 다른 것과 분리되어 있지 않으니까요.

해결책은 세 가지 종류의 것들을 서로 분리하는 겁니다.

사용자가 보는 것 — 인터페이스, 버튼, 레이아웃 (주로 "UI" 또는 "프런트엔드"라고 부릅니다).
앱이 수행하는 작업 — 실제 로직, 규칙, 계산 (이것이 바로 "비즈니스 로직"입니다).
데이터가 어디에서 오는지 — 데이터베이스나 외부 서비스와 통신하는 부분 ("데이터 계층" 또는 "데이터 레이어"입니다).

이렇게 분리해두면, 화면이 어떻게 보이는지를 바꾸더라도 어떤 작업을 하는지에 손대지 않을 수 있고, 어떤 작업을 하는지를 바꾸더라도 데이터와 통신하는 방식을 망가뜨리지 않을 수 있습니다. 문제가 발생해도 다른 곳으로 퍼지지 않고 해당 영역에만 국한되는 거죠. 사실 제가 10년 넘게 현업에서 일하며 느낀 가장 큰 교훈 중 하나는, 이 책임 분리 원칙만 잘 지켜도 나중에 코드를 유지보수하거나 기능을 확장할 때 들어가는 시간을 획기적으로 줄일 수 있다는 겁니다. 특히 기존 레거시 시스템을 리팩터링할 때 이 원칙이 얼마나 중요한지 뼈저리게 느꼈죠.

AI에게 붙여넣을 프롬프트: "인터페이스, 비즈니스 로직, 데이터 접근 방식을 각각 별도의 파일로 분리해 주세요. 서로 섞지 마세요."

이 한 문장을 꾸준히 사용하는 것만으로도 이 가이드의 어떤 다른 조언보다 많은 프로젝트 붕괴를 막을 수 있습니다.

생존 기술 #2: 하나는 한 가지 일만 하라

머릿속에 새겨둘 만큼 간단한 규칙입니다. 하나의 파일이나 함수는 한 문장으로 설명할 수 있는 단 하나의 일만 해야 합니다.

만약 어떤 파일이 하는 일을 설명하면서 "이것 그리고 저것 그리고 또 저것도 합니다"라고 말해야 한다면, 그 파일은 너무 많은 일을 하고 있는 것이고, 버그가 숨어들고 변경이 꼬이는 온상이 될 겁니다.

작고, 단일 목적을 가진 조각들은 다루기 쉽습니다. 쉽게 찾고, 이해하고, 두려움 없이 변경할 수 있죠. 반면 모든 것을 다 하는 거대한 파일은 늪과 같습니다. 더 많은 것을 담을수록, 모든 수정 작업은 도박이 될 수 있습니다.

AI에게 붙여넣을 프롬프트: "각 파일과 함수는 단 하나의 명확한 책임을 가지도록 해주세요. 두 가지 이상의 일을 하는 부분은 분리해 주세요."

생존 기술 #3: 각 데이터 조각은 단 하나의 집을 가져야 한다

이것은 초보자 프로젝트가 무너지는 가장 흔한 방법이니, 특히 주의 깊게 살펴보세요.

앱이 성장함에 따라, 로그인한 사용자 정보나 장바구니에 담긴 아이템 같은 특정 정보가 여러 다른 곳에 복사되어 관리될 수 있습니다. 그러면 이 복사본들 간의 동기화가 깨지기 시작합니다. 앱의 어떤 부분은 장바구니에 세 개의 아이템이 있다고 생각하고, 다른 부분은 하나만 있다고 생각해서 앱이 아무도 이해할 수 없는 방식으로 동작하기 시작하며, 디버깅은 거의 불가능해집니다.

생존 규칙은 이렇습니다. 모든 데이터 조각은 정확히 한 곳에 존재해야 하며, 다른 모든 것은 그 한 곳에서 데이터를 읽어야 합니다. 즉, 단일 정보원(Single Source of Truth)을 유지해야 합니다. AI가 프로젝트 곳곳에 무심코 상태(state)의 복사본을 만들도록 내버려 두지 마세요. 한번은 사내 툴을 개발하다가 장바구니 데이터를 여러 컴포넌트에서 각자 관리하게 되면서, 분명히 상품을 담았는데 다른 페이지에서는 텅 비어 보이는 황당한 버그를 잡느라 며칠 밤을 새운 적도 있습니다. 당시엔 정말 미치는 줄 알았죠.

AI에게 붙여넣을 프롬프트: "이 데이터는 단 하나의 진실된 출처(Single Source of Truth)를 가져야 합니다. 여러 컴포넌트에 데이터를 중복시키지 말고, 모든 것이 한곳에서 읽어오도록 해주세요."

이것은 기술적으로는 아무것도 망가지지 않았는데, 아무것도 서로 동의하지 않는 종류의 버그, 즉 가장 골치 아픈 버그 범주를 예방해 줍니다.

생존 기술 #4: 생성 전에 '모양'을 먼저 결정하라

대부분의 초보자는 이렇게 개발합니다. 기능 하나를 생각하고, AI에게 만들어달라고 요청하고, 반복하죠. 그러면 AI는 매번 즉흥적으로 구조를 만들고, 결국 조각들은 서로 잘 맞지 않게 됩니다. 애초에 어떻게 맞춰야 할지 아무도 결정하지 않았으니까요.

모든 것을 바꿔놓을 중요한 전환점은 바로 이겁니다. 앱의 각 부분을 만들기 전에 그 이름을 먼저 정하세요.

코드를 생성하기 전에, 주요 구성 요소와 각 구성 요소의 책임을 간단히 적어보세요. 간단한 앱이라면 '로그인', '사용자 프로필', '메인 대시보드', '결제'가 될 수 있겠죠. 네 개의 조각, 각각 명확한 역할을 가지고 있습니다. 이 목록, 즉 미리 조각들과 그 책임을 알고 있는 것이 바로 쉬운 말로 하는 아키텍처입니다. 방금 여러분이 해낸 겁니다. 전혀 어렵지 않죠.

그리고 한 번에 한 조각씩 완전히 만들고 나서 다음 조각으로 넘어가세요. AI에게 전체 앱을 한 번에 생성해달라고 요청하지 마세요. 그러면 이해할 수 없는 뒤죽박죽 코드를 받게 될 겁니다. 로그인을 만들고, 작동하게 만들고, 이해하세요. 그 다음 다음 조각으로 넘어가세요.

AI에게 붙여넣을 프롬프트: "제 앱의 주요 컴포넌트와 각 역할은 다음과 같습니다: [여러분의 목록]. [X]부터 시작해서 한 번에 하나씩 만들어 봅시다."

생존 기술 #5: AI에게 설명을 요구하라

이 습관은 개발하는 과정을 학습하는 과정으로 바꿔줍니다. 그리고 이것이 서서히 초보자를 실제로 구조를 이해하는 사람으로 만들어 줄 겁니다.

AI가 주는 코드를 그냥 받아들이고 넘어가지 마세요. 이렇게 물어보세요.

"왜 이런 식으로 구조화했나요?"
"각 부분이 어떤 일을 하는지, 쉬운 말로 설명해 주세요."
"이 부분을 변경하면 다른 어떤 부분에 영향을 미칠까요?"

여러분은 AI를 코드를 뽑아내는 자판기가 아니라, 튜터(과외 선생님)로 활용하는 겁니다. AI의 모든 답변은 프로젝트가 어떻게 조립되는지에 대해 여러분에게 조금씩 더 많은 것을 가르쳐 줄 겁니다. 이것이야말로 여러분이 애초에 부족했던 지식이죠. 이 과정을 꾸준히 반복하면, 프로젝트를 거듭할수록 단순히 코드를 생성하는 사람이 아니라 코드를 이해하는 사람이 될 겁니다. 그 이해가 바로 이 게임의 핵심입니다.

AI에게 붙여넣을 프롬프트: "이 코드를 사용하기 전에, 이것이 어떻게 구조화되어 있고 그 이유는 무엇인지 간단하게 설명해 주세요. 그냥 실행하는 것이 아니라 이해하고 싶습니다."

생존 기술 #6: 지루하고 일관성 있게 유지하라

이 두 가지 습관은 짝을 이루어 작동하기 때문에 함께 묶었습니다.

영리함보다 지루함이 낫습니다. AI가 세련되고, 복잡하고, 인상적인 해결책을 제시할 때, 더 간단한 방법은 없는지 물어보세요. 아키텍처 비전문가인 우리에게, 화려한 버전은 승리가 아니라 빚(liability)과 같습니다. 이해할 수 없는 복잡성은 유지보수하거나 고칠 수 없는 복잡성이 되기 때문입니다. 간단하고 명확한 버전이야말로 다음 달에도 여전히 작업할 수 있는 코드입니다. 항상 간단한 것을 선호하세요. 화려하고 복잡한 '천재적인' 코드가 당장은 멋있어 보일지 몰라도, 결국 시간이 지나면 저를 포함한 팀원 모두를 괴롭히는 부메랑이 되더군요. 실무에서는 명료하고 예측 가능한 코드가 훨씬 강력합니다.

다양성보다 일관성이 낫습니다. 기능 A를 한 가지 방식으로 만들고 기능 B를 완전히 다른 방식으로 만든다면 (서로 다른 AI 세션에서는 쉽게 일어날 수 있는 일입니다), 여러분의 프로젝트는 아무런 규칙도 따르지 않고 모든 것이 혼란스러운 조각보가 될 겁니다. 새로운 기능은 기존 기능의 패턴과 일치시키세요.

AI에게 붙여넣을 프롬프트: "가장 영리한 방법보다는 작동하는 가장 간단한 버전을 제공해 주세요. 그리고 제 프로젝트에 이미 있는 구조와 패턴을 맞춰주세요."

너무 늦기 전에 경고등을 알아채는 법

자, 여기에 여러분의 연기 감지기가 있습니다. 아래 증상 중 하나라도 느끼기 시작하면, 더 이상 기능을 추가하는 것을 멈추고 먼저 구조를 정리해야 합니다.

무엇이 고장 날지 몰라 변경하는 것을 두려워하고 있습니다.
하나를 고쳤는데 다른 것이 계속해서 망가집니다.
더 이상 어디에 무엇이 있는지 찾을 수 없습니다.
파일들이 계속해서 커지고 더 많은 일을 하게 됩니다.
프로젝트를 보면 무슨 코드인지 도무지 이해할 수 없습니다.

이 중 어떤 것도 여러분이 실패했다는 의미는 아닙니다. 그저 여러분의 프로젝트가 구조를 뛰어넘어 성장했다는 의미이며, 이것은 전문가를 포함해 누구에게나 일어나는 일입니다. 차이점은 이제 여러분이 이 느낌이 무엇을 의미하는지, 그리고 무엇을 해야 할지 안다는 겁니다. 잠시 멈추고, 조각들을 분리하고, 더 많은 것을 구축하기 전에 이해도를 되찾으세요.

핵심 정리

AI를 활용해 실제 소프트웨어를 만드는 데 컴퓨터 공학 학위가 필요하지 않습니다. 그 장벽은 진정으로 사라졌고, 다시 돌아오지 않을 겁니다.

하지만 "코드를 생성할 수 있다"는 것과 "스스로 성장해나가는 것을 견딜 수 있는 무언가를 만들 수 있다"는 것은 다른 이야기이며, 그 사이의 간극이 바로 **구조(Structure)**입니다. AI가 여러분에게 대신 제공해 줄 수 없는 유일한 부분이죠. 왜냐하면, 그것은 여러분의 프로젝트에 대한 결정, 즉 여러분만이 내릴 수 있는 결정에 달려 있기 때문입니다. AI는 코드를 제공합니다. 여러분은 그 코드에 '모양'을 부여해야 합니다.

다행히도 그 '모양'을 잡는 것은 어렵지 않습니다. 몇 가지 습관만 지키면 됩니다. 조각들을 분리하고, 각자 하나의 일만 맡기고, 모든 데이터 조각은 단 하나의 집을 갖게 하고, 생성하기 전에 미리 계획하고, AI에게 설명을 요구하고, 지루할 정도로 일관성을 유지하는 겁니다. 이 습관들을 지키고, 개발하면서 무엇을 만들고 있는지 이해한다면, 여러분이 생각하는 것보다 훨씬 더 많은 것을 만들 수 있을 겁니다. 그것도 프로젝트가 무너지는 것을 보지 않으면서 말이죠.

간단하게 시작하세요. 그리고 계속해서 이해할 수 있는 상태를 유지하세요. 그것이 바로 생존입니다.

Disclaimer: 이 글은 AI의 도움을 받아 작성되었으며, 게시 전 제가 검토하고 편집했습니다.

원문: https://dev.to/james_anderson_h/building-with-ai-when-you-dont-know-architecture-a-survival-guide-1ma3 수집일: 2026-09-03 01:44:04