AI가 만든 코드가 처음에는 작동하지만 기능을 추가할수록 꼬이는 이유를 설명합니다. 속도, 역할 혼재, 중복, 검증 부족을 점검하는 방법입니다.
AI 코드 꼬임은 기능 추가 속도가 구조를 이해하고 검증하는 속도보다 빨라질 때 시작됩니다.
연재 안내: 27편 전체 순서와 현재 공개된 글은 비개발자 바이브코딩 로드맵에서 확인할 수 있습니다.
설치 단계에서 막혔다면 먼저 npm install 오류 점검 순서를 확인하세요. 이번 글은 설치가 아니라 기능이 늘어난 뒤 코드가 흔들리는 이유를 다룹니다.
한 줄 답변
AI 코드 꼬임은 AI가 코드를 못 써서만 생기는 문제가 아닙니다. 코드 생성 속도가 사람의 이해와 검증 속도보다 빠르고, 매 요청이 현재 기능 하나의 성공만 목표로 삼으면서 화면·규칙·통신이 한곳에 누적될 때 생깁니다.
작동하는 코드와 유지할 수 있는 코드는 다르다
버튼이 보이고 한 번 저장됐다는 사실은 현재 입력과 현재 컴퓨터에서 한 번 성공했다는 뜻입니다. 좋은 코드는 다음 기능을 붙여도 기존 기능이 깨지지 않고, 문제가 생겼을 때 수정 위치를 찾고, 정상 상태로 돌아갈 수 있어야 합니다.
초반에는 코드가 짧아서 두 종류의 차이가 잘 보이지 않습니다. 그러나 중복 예약 방지, 이메일 알림, 관리자 권한을 차례로 추가하면 구조의 차이가 드러납니다. 작은 변경이 관련 없는 화면과 저장 기능을 흔들기 시작합니다.
생성 속도가 이해 속도를 앞선다
AI는 몇 초 안에 수백 줄을 만들 수 있습니다. 작업자가 실행 결과만 보고 곧바로 다음 기능을 요청하면 어떤 파일이 어떤 역할을 맡았는지 확인할 시간이 없습니다. 코드 양은 늘지만 프로젝트를 설명할 수 있는 사람은 없어집니다.
속도를 줄이라는 뜻이 아닙니다. 기능 하나가 끝날 때마다 변경 파일, 데이터 흐름, 실패 상황, 테스트 결과를 짧게 기록해 이해 속도를 따라잡아야 합니다.
AI는 빈칸을 추측한다
“중복 신청을 막아줘”라는 요청에는 중복의 기준, 검사 위치, 오류 메시지, 기존 데이터 처리 방법이 없습니다. AI는 현재 보이는 코드와 일반적인 패턴을 바탕으로 빈칸을 채웁니다. 다음 대화에서 다른 가정을 하면 앞선 구현과 충돌할 수 있습니다.
요구사항, 제외 조건, 완료 기준을 매 기능마다 제공해야 같은 방향을 유지할 수 있습니다. 대화가 길어질수록 중요한 기준은 채팅 밖의 문서에 남겨야 합니다.
역할이 한 파일과 함수에 섞인다
한 함수가 버튼을 그리고, 입력값을 검사하고, API를 호출하고, 성공 문구까지 바꾸면 수정 범위가 넓습니다. 버튼 색만 바꾸려다 저장 로직을 건드릴 수 있고, 서버 주소를 바꾸다 화면 상태를 깨뜨릴 수 있습니다.
파일 수보다 역할의 경계가 중요합니다. 화면, 업무 규칙, 외부 통신이 서로의 내부 구현을 몰라도 입력과 결과만 주고받을 수 있어야 합니다.
복사한 코드는 미래의 수정 지점을 늘린다
비슷한 검증 코드를 여러 화면에 복사하면 당장은 빠릅니다. 하지만 규칙이 바뀔 때 모든 복사본을 찾아 수정해야 합니다. 하나를 놓치면 같은 서비스에서 화면마다 다른 결과가 나옵니다.
두 번째 복사가 필요해지는 순간 공용 함수로 분리할 수 있는지 검토하세요. 무조건 추상화할 필요는 없지만 같은 업무 규칙이 여러 곳에 존재하는 상태는 기록해야 합니다.
기술적 부채는 나쁜 코드라는 낙인이 아니다
마감 때문에 임시로 빠르게 만드는 선택은 가능하며 때로는 합리적입니다. 문제는 임시 선택을 영구 구조처럼 잊는 것입니다. TODO: 중복 검증 공통화, 현재는 관리자 한 명만 가정처럼 빚의 위치와 상환 조건을 남겨야 합니다.
기술적 부채가 쌓이면 기능 추가 속도보다 수정에 대한 두려움이 커집니다. 파일을 열기 싫고 AI에게 전체 교체를 반복하게 된다면 구조 점검이 필요한 신호입니다.
AI 코드 꼬임의 다섯 가지 위험 신호
- 작은 화면 수정 뒤 저장이나 로그인이 깨진다.
- 같은 규칙이 여러 파일에 복사되어 있다.
- 한 함수가 화면, 계산, 통신을 모두 처리한다.
- AI가 매번 파일 전체 교체를 제안한다.
- 정상 상태를 설명하거나 되돌릴 커밋이 없다.
두 개 이상 해당하면 새 기능을 잠시 멈추고 역할과 변경 이력을 정리하는 편이 좋습니다.
새 기능 전에 AI에게 물을 질문
이번 기능을 추가하기 전에 현재 구조에서 영향을 받는 화면, 함수, API, 데이터 표를 목록으로 보여줘. 기존 동작을 바꾸지 않는 최소 수정안을 제안하고, 중복 코드와 역할 혼재가 늘어나는 부분이 있다면 코드 작성 전에 알려줘.
AI 코드 꼬임은 한 번의 대규모 청소보다 작은 경계를 계속 지킬 때 줄어듭니다. 설계 방법 자체는 스파게티 코드를 피하는 5칸 구조에서 확인할 수 있습니다.
속도를 조절하는 완료 신호
다음 기능으로 넘어가기 전 현재 기능의 입력과 결과, 변경 파일, 실패 테스트, 정상 커밋을 한 줄씩 설명해보세요. 하나라도 설명하지 못하면 코드를 더 생성하기 전에 AI에게 현재 흐름을 요약하게 하고 실제 파일과 대조합니다.
생성 속도를 포기할 필요는 없습니다. 다만 기능 한 개를 만든 시간과 이해·검증에 쓴 시간을 분리해 기록하면 프로젝트가 과속 중인지 알 수 있습니다.
AI 코드 꼬임 최종 점검
AI 코드 꼬임이 의심되면 새 기능 요청을 잠시 멈추고 같은 역할의 함수·상태·API 호출이 여러 곳에 복제됐는지 찾아보세요. AI 코드 꼬임은 한 파일의 줄 수보다 변경 이유를 설명하기 어렵고 작은 수정의 영향 범위를 예측할 수 없을 때 더 분명하게 나타납니다.
먼저 정상 버전을 저장하고 사용자가 실제로 통과해야 할 흐름을 테스트로 고정하세요. 그다음 중복 하나나 긴 함수 하나처럼 가장 작은 구조 문제만 정리하고 결과가 같다는 것을 확인한 뒤 다음 정리로 넘어갑니다.
한 함수에 화면 처리와 검증, 저장, 안내 문구가 함께 들어 있다면 다음 글 긴 함수 나누기: 초보자 3단계에서 역할을 구분하고 안전하게 분리하는 순서를 확인하세요.
바이브코딩 전체 순서 보기
바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.
