AI 개발 설계란 AI가 코드를 생성하는 환경과 규칙을 사전에 구조화하는 것이다. 바이브 코딩을 쓰는 사람은 많아졌지만 결과물의 차이는 크게 벌어진다. 같은 AI 도구를 써도 어떤 사람은 안정적인 결과를 얻고, 어떤 사람은 임시 패치와 롤백을 반복한다. 차이는 AI를 다루는 감각이 아니라, 그 감각을 구조로 바꿨는가에 있다.
이 글에서는 AI 개발 설계의 핵심 개념 5가지를 설명한다. 설계 리뷰가 왜 중요해졌는지, 문서를 어떻게 나누어야 하는지, 기능을 어떻게 조립해야 하는지, AI가 흔들릴 때 어떻게 대응하는지, 그리고 언제 리팩토링해야 하는지까지. 각각이 독립된 개념처럼 보이지만 결국 하나의 방향을 가리킨다.
AI 개발 설계란 무엇인가 — 코드 리뷰에서 설계 리뷰로
AI가 코드를 직접 생성하기 전까지, 개발팀의 품질 관리는 코드 리뷰에 집중되어 있었다. 변수명이 적절한지, 함수가 너무 길지 않은지를 동료가 한 줄씩 확인하는 문화였다. 그런데 바이브 코딩이 확산되면서 이 구도가 바뀌었다.
AI가 만들어내는 코드는 이미 문법적으로 깔끔하고 평균 이상의 완성도를 갖는다. 코드 자체를 검토하는 것보다, 그 코드가 올바른 문제를 풀고 있는지를 먼저 검토하는 것이 훨씬 중요해졌다.
예를 들어 로그인 기능을 만든다고 하자. AI가 만들어온 코드가 잘 동작한다고 해도, “이 서비스는 소셜 로그인만 허용하고 자체 비밀번호 저장은 하지 않는다”는 방향이 처음부터 잘못 설정되어 있었다면 코드 전체가 무의미해진다. 코드의 품질이 아니라 방향의 적절성이 결과를 결정한다.
이것이 AI 개발 설계가 중요해진 이유다. 코드를 짜기 전에, 무엇을 어떤 방향으로 풀 것인지를 먼저 설계하고 검토하는 것이 바이브 코딩 시대 개발자의 핵심 역량이 된다.
AI 개발 설계의 4단계 문서 구조
AI와 함께 개발할 때 가장 큰 문제 중 하나는 세션이 바뀌면 모든 맥락이 사라진다는 것이다. 어제 어떤 방향으로 개발하기로 했는지, 어떤 제약이 있었는지를 AI는 기억하지 못한다. AI 개발 설계에서 문서를 역할별로 나누어 관리하는 구조가 필요한 이유가 여기에 있다.
| 레이어 | 역할 | 핵심 특징 |
|---|---|---|
| 방향 문서 | “무엇을 만들려는가”를 유지 | 의도적으로 모호하게 작성 |
| 가드레일 문서 | AI가 하면 안 되는 것을 명시 | 임시 패치·범위 이탈 방지 |
| 실행 문서 | 진행 상황·측정 기준 기록 | 작게 쪼개고 검증하며 조립 |
| 학습 문서 | 실수와 판단 기준을 자산화 | 다음 세션 반복 방지 |
방향 문서는 이 프로젝트가 무엇을 하려는지를 담는다. 세부 스펙을 쓰지 않는 것이 핵심이다. 오히려 의도적으로 모호하게 작성한다. AI가 세부 내용에 매몰되지 않고 큰 방향을 유지하게 하기 위해서다. 세션이 몇 번 바뀌어도 “우리가 무엇을 만들려 하는가”를 잃지 않게 해주는 닻 역할을 한다.
가드레일 문서는 AI가 하면 안 되는 것들을 명시한다. AI는 제약이 없으면 당장 동작하는 빠른 해결책을 먼저 선택하는 경향이 있다. 구조적으로 올바른 방향보다 임시 패치를 선호한다. “이 라이브러리는 사용 금지”, “결제 모듈은 수정하지 않는다” 같은 명시적인 제약들이 여기에 들어간다.
실행 문서는 지금 어떤 작업이 진행 중인지, 어디까지 완료됐는지, 품질을 어떤 기준으로 측정하는지를 기록한다. 기능을 크게 한 번에 만들지 않고 잘게 쪼개서 검증하며 조립하는 방식을 지원하는 문서다.
학습 문서는 이 프로젝트에서 어떤 실수를 했고 어떻게 해결했는지, 어떤 판단 기준으로 설계를 결정했는지를 남긴다. 다음 세션, 다음 프로젝트에서 같은 실수를 반복하지 않기 위한 자산이다.
기능을 6단계로 조립하는 AI 개발 설계 프로세스
기능을 한 번에 크게 만들어달라고 하면 AI는 중간에 방향을 잃거나 앞뒤가 맞지 않는 코드를 내놓는다. 작업이 클수록 AI가 초반의 맥락을 잃어버리기 쉽다. AI 개발 설계에서 기능을 작게 쪼개서 검증하며 조립하는 이유가 여기에 있다.
| 단계 | 작업 내용 | 핵심 원칙 |
|---|---|---|
| 1. 개념 아키텍처 | 전체 구조에서 이 기능의 역할 설계 | 큰 그림 먼저 |
| 2. 벤치마크 설정 | 성공 기준을 정량적으로 정의 | 감이 아닌 기준으로 |
| 3. 세부 스프린트 | 큰 작업을 독립 검증 가능한 단위로 분해 | 작게 쪼개기 |
| 4. 구현 | 제어된 환경 안에서 코드 생성 | 가드레일 안에서만 |
| 5. 검증 | 2단계 기준으로 통과 여부 확인 | 불통 시 3단계로 |
| 6. 커밋 | 검증 통과 시에만 저장 | 성공한 상태만 쌓기 |
이 구조의 핵심은 “성공했을 때만 앞으로 간다”는 원칙이다. 검증을 통과하지 못하면 다시 잘게 쪼개는 단계로 돌아간다. 불안정한 상태를 쌓아가며 진행하지 않고, 각 단계가 검증된 상태에서만 조립해나간다.
바이브 코딩 초반에 많이 하는 실수가 3단계를 건너뛰는 것이다. 아키텍처를 그리고 바로 구현으로 넘어가면, AI가 만들어오는 결과물이 처음 설계와 어긋나기 시작한다. 세부 스프린트 단계에서 작업을 충분히 잘게 쪼개는 것이 전체 안정성을 결정한다.
AI가 흔들릴 때 AI 개발 설계로 대응하는 법
AI와 오래 작업하다 보면 반드시 겪는 순간이 있다. AI가 갑자기 길을 잃는 것이다. 구조적으로 잘 풀던 문제를 임시방편으로 때우려 하거나, 지금 만들어야 할 것과 무관한 기능을 스스로 추가하거나, 분명히 공유했던 맥락을 모르는 것처럼 행동한다.
이때 대부분이 하는 실수가 있다. 처음부터 다시 설명하는 것이다. 그런데 이 방법은 근본적인 해결이 아니다. 대화가 길어질수록 같은 문제가 반복된다.
AI 개발 설계에서 더 효과적인 방법은 상황에 맞는 문서를 그 자리에서 제공하는 것이다. 말로 설명하는 것이 아니라, 미리 준비해둔 문서로 대응한다.
| AI의 이상 징후 | 제공할 문서 | 목적 |
|---|---|---|
| 목적을 잃고 방황할 때 | 방향 문서 | 목적과 방향 재정렬 |
| 임시 패치로 빨리 끝내려 할 때 | 가드레일 문서 | 구조적 변경 유도 |
| 범위 밖 기능을 추가하려 할 때 | 실행 문서 | 작은 단위로 재분해 |
| 결과물 품질이 의심스러울 때 | 벤치마크 문서 | 감 대신 기준으로 판단 |
| 세션 리셋으로 맥락이 끊겼을 때 | 학습 문서 | 맥락 복구 |
이것이 문서를 역할별로 나누어 관리하는 실질적인 이유다. 예쁘게 정리하기 위한 것이 아니라, AI가 흔들리는 순간에 즉각적으로 꺼내 쓸 수 있는 대응 도구로서의 문서다.
MD 파일을 올바르게 쓰는 3가지 원칙
AI 개발 설계에서 많은 사람들이 문서를 지나치게 상세하게 작성하는 실수를 한다. 잘 정리된 문서가 AI를 더 잘 이해시킬 것이라고 생각하기 때문이다. 그런데 실제로는 반대다. 문서가 길수록 AI의 작업 기억에서 정작 중요한 정보가 희석된다.
첫째, 코드가 말하지 못하는 것만 담는다.
코드를 읽었을 때 어떤 기능인지 바로 알 수 있는 내용은 문서에 쓰지 않아도 된다. 문서에 담아야 할 것은 코드만 봐서는 절대 알 수 없는 것들이다. 이 구조를 왜 이렇게 잡았는지, 이 라이브러리를 왜 쓰면 안 되는지, 이 기능이 외부 제약 때문에 왜 이런 형태가 됐는지. 코드 어디에도 적혀있지 않은 배경과 의도, 그리고 제약만 담는다.
둘째, 문서가 짧을수록 AI가 잘 집중한다.
이 원칙을 지키면 문서는 자연스럽게 짧아진다. 그리고 짧은 문서일수록 AI는 핵심 정보에 더 잘 집중한다. 좋은 문서란 많은 것을 적은 문서가 아니라, 코드가 말하지 못하는 것만 정확하게 담은 문서다.
셋째, 문서는 설명이 아니라 대응 도구다.
문서를 잘 쓰려고 하지 말고, 어떤 상황에서 꺼내 쓸 문서인지를 먼저 생각한다. AI가 흔들리는 순간마다 어떤 문서를 주입해야 하는지가 명확할수록, 그 문서의 내용도 자연스럽게 핵심만 남게 된다.
리팩토링 타이밍 — AI 개발 설계에서 언제 정리하는가
바이브 코딩에서 리팩토링은 “코드가 지저분해 보일 때” 하는 것이 아니다. 감각이 아닌 구조적인 기준이 필요하다.
기능이 검증을 통과하고 커밋이 완료된 직후가 리팩토링의 적절한 시점이다. 동작이 확인된 상태에서 코드를 정리하기 때문에, 리팩토링 과정에서 기능이 망가질 위험이 낮다. 반대로 기능이 완성되기 전에 리팩토링을 시도하면 동작하지 않는 코드를 정리하는 것이 되어버려 방향을 잃기 쉽다.
AI에게 리팩토링을 지시할 때도 마찬가지다. “코드를 깔끔하게 만들어줘”라고 하면 AI는 기능까지 바꿔버리는 경우가 있다. “이 기능의 동작은 그대로 유지하면서, 이 부분의 구조만 정리해줘”처럼 범위와 제약을 명확하게 지정해야 한다. 리팩토링의 범위를 명시하는 것 자체가 가드레일 문서의 역할과 같다.
| 리팩토링 시점 | 권장 여부 | 이유 |
|---|---|---|
| 기능 구현 중 | ❌ 비권장 | 동작 미확인 상태에서 구조 변경 → 방향 혼란 |
| 검증 통과 후 커밋 직전 | ✅ 권장 | 동작 확인된 상태에서 정리 → 안전 |
| 커밋 완료 후 다음 스프린트 전 | ✅ 권장 | 다음 작업 전 깔끔한 출발점 확보 |
마무리 — AI 개발 설계는 환경을 만드는 일이다
AI 개발 설계의 핵심은 AI에게 무엇을 시키느냐가 아니라, AI가 일하는 환경을 어떻게 만드느냐다. 방향 문서로 목적을 유지하고, 가드레일 문서로 이탈을 막고, 실행 문서로 작업을 잘게 조립하고, 학습 문서로 실수를 자산으로 쌓는다. 그리고 AI가 흔들리는 순간마다 설명 대신 문서를 꺼내 쓴다.
바이브 코딩을 처음 시작할 때는 프롬프트를 잘 쓰는 것이 전부인 것처럼 느껴진다. 그런데 프로젝트가 커지고 세션이 쌓일수록 분명해지는 것이 있다. AI 개발 설계 없이 쌓인 코드는 언젠가 반드시 무너진다는 것이다. 감각을 구조로 바꾸는 것, 그것이 바이브 코딩을 잘 쓰는 사람과 그렇지 않은 사람의 차이다.
[링크 제안]
바이브 코딩의 구조를 이해했다면, 다음은 AI에게 올바른 맥락을 전달하는 방법이다.
설계 이전에 바이브 코딩 자체가 낯설다면 이 글부터 시작하는 것을 권장한다.
자비스는 어떻게 만들어졌을까 — Agentic AI의 시작
