2026년 4월 30일

AI가 만든 코드에서 가장 먼저 정리해야 할 파일 5개

Cursor, Lovable, Bolt로 만든 프로젝트를 이어서 운영하려면 README, package.json, 환경 변수, 메인 화면, 외부 서비스 연결 파일부터 정리하는 것이 좋습니다.

AI로 만든 프로젝트를 처음 열어보면 이상한 감각이 듭니다. 화면은 돌아가는데, 어디서부터 손대야 할지 잘 보이지 않습니다.

파일은 많고, 비슷한 이름의 컴포넌트가 여러 개 있고, 안 쓰는 코드인지 중요한 코드인지 구분하기 어렵습니다. 이 상태에서 바로 새 기능을 붙이면 생각보다 쉽게 꼬입니다. 버튼 하나를 바꿨는데 로그인 화면이 깨지거나, 배포 설정을 고치다 데이터 저장이 안 되는 식입니다.

그래서 AI가 만든 코드는 처음부터 전부 정리하려고 하면 안 됩니다. 먼저 운영과 수정에 직접 영향을 주는 파일 몇 개만 잡아도 충분합니다. 개발자가 이어받을 때도 보통 이 파일들부터 봅니다.

1. README.md: 프로젝트 설명서

README는 프로젝트의 현관문입니다. 그런데 AI로 만든 프로젝트에는 README가 없거나, 처음 생성된 예시 문구만 남아 있는 경우가 많습니다.

README에 필요한 내용은 길지 않아도 됩니다.

이 서비스가 무엇인지
어떤 도구로 만들었는지: Cursor, Lovable, Bolt 등
로컬에서 실행하는 명령어
배포 서비스가 어디인지
사용하는 외부 서비스: Supabase, Firebase, 결제, 이메일 등
현재 알려진 문제나 주의사항

이 정도만 있어도 나중에 프로젝트를 다시 열었을 때 훨씬 덜 헤맵니다. 개발자에게 맡길 때도 README가 있으면 첫 진단 시간이 줄어듭니다.

멋진 문서가 아니라 기억 보조용 메모라고 생각하면 됩니다. AI가 만든 코드는 만든 사람도 며칠 지나면 구조를 잊기 쉽습니다.

2. package.json: 실행과 배포의 기준

package.json은 이 프로젝트가 어떤 기술로 돌아가는지 보여주는 파일입니다. 여기에는 실행 명령어, 빌드 명령어, 설치된 패키지들이 들어 있습니다.

AI가 여러 번 수정한 프로젝트에서는 package.json이 지저분해지는 일이 많습니다. 쓰지 않는 패키지가 남아 있거나, 비슷한 라이브러리가 여러 개 들어 있거나, build 명령어가 현재 구조와 맞지 않을 수 있습니다.

먼저 확인할 것은 단순합니다.

npm run dev가 실제로 실행되는가
npm run build가 성공하는가
사용하지 않는 큰 패키지가 남아 있지 않은가
같은 역할의 라이브러리가 여러 개 들어 있지 않은가
Next.js, React, Tailwind 같은 핵심 패키지 버전이 서로 맞는가

배포 오류가 날 때도 package.json은 거의 항상 확인합니다. 앱이 어떻게 생겼는지보다, 배포 환경에서 어떤 명령으로 만들어지는지가 먼저이기 때문입니다.

3. .env.example: 비밀값 말고 이름표

환경 변수는 AI 프로젝트에서 자주 문제를 만듭니다. 로컬에서는 .env 파일에 값이 있어서 잘 되는데, Vercel에는 빠져 있어서 배포 후에만 깨지는 경우가 많습니다.

중요한 것은 실제 비밀값을 문서에 적는 게 아닙니다. 어떤 값이 필요한지 이름만 정리하는 것입니다. 그래서 .env.example 같은 파일이 있으면 좋습니다.

예를 들면 이런 식입니다.

NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
TOSS_SECRET_KEY=
RESEND_API_KEY=

이 파일에는 실제 키를 넣지 않습니다. 대신 이 프로젝트가 어떤 환경 변수를 필요로 하는지 알려주는 목록으로 씁니다.

비개발자 입장에서도 이 파일이 있으면 배포 서비스에 무엇을 넣어야 하는지 확인하기 쉽습니다. 개발자에게 맡길 때도 "어떤 키가 필요한 프로젝트인지"를 바로 볼 수 있습니다.

4. 메인 페이지 파일: 사용자가 처음 보는 화면

Next.js라면 app/page.tsx, Vite나 React 프로젝트라면 App.tsx 같은 파일이 메인 화면의 시작점입니다. AI가 만든 프로젝트를 정리할 때는 이 파일이 너무 많은 일을 하고 있지 않은지 봐야 합니다.

처음에는 빠르게 만들기 위해 한 파일에 모든 섹션, 상태, 데이터 요청, 이벤트 처리가 들어갈 수 있습니다. 작은 랜딩페이지라면 괜찮지만, 서비스가 커지면 이 파일이 금방 무거워집니다.

확인할 것:

한 파일에 화면 전체가 너무 길게 들어 있지 않은가
안 쓰는 섹션이나 예시 데이터가 남아 있지 않은가
버튼 링크와 CTA가 실제 운영 주소로 연결되어 있는가
모바일에서 깨지는 고정 너비 요소가 있는가
중요한 문구가 여러 파일에 중복되어 있지 않은가

메인 페이지가 정리되면 이후 수정이 쉬워집니다. 반대로 첫 화면부터 복잡하면 작은 문구 하나 바꾸는 일도 불안해집니다.

5. 외부 서비스 연결 파일

Supabase, Firebase, 결제, 이메일처럼 외부 서비스를 붙였다면 연결 파일을 꼭 찾아야 합니다. 보통 lib/supabase.ts, lib/firebase.ts, lib/api.ts, lib/payments.ts 같은 이름으로 들어 있습니다.

이 파일은 서비스의 콘센트 같은 역할을 합니다. 화면에서는 버튼 하나로 보이지만, 실제로는 이 파일을 통해 데이터베이스나 결제사와 연결됩니다.

확인할 것:

같은 외부 서비스를 초기화하는 코드가 여러 곳에 중복되어 있지 않은가
테스트 키와 운영 키를 섞어 쓰지 않는가
브라우저에 노출되면 안 되는 키를 클라이언트 코드에서 쓰지 않는가
에러가 났을 때 최소한의 로그나 반환값이 있는가
운영 도메인 기준으로 콜백 주소가 맞는가

AI가 만든 코드에서 가장 위험한 지점은 화면보다 외부 서비스 연결부일 때가 많습니다. 특히 결제와 로그인은 이 파일을 먼저 보는 편이 안전합니다.

전부 정리하려고 하지 않기

처음부터 모든 파일을 깔끔하게 만들려고 하면 오히려 멈춥니다. AI가 만든 프로젝트에는 지금 당장 안 써도 되는 코드, 나중에 지워도 되는 코드, 건드리면 위험한 코드가 섞여 있습니다.

처음 정리는 청소보다 지도 만들기에 가깝습니다. 어디가 입구인지, 배포는 어떻게 되는지, 외부 서비스는 어디서 연결되는지, 중요한 화면은 어디서 시작하는지만 알면 됩니다.

정리

AI가 만든 코드는 처음부터 나쁜 코드라고 볼 필요는 없습니다. 다만 빠르게 만들어진 만큼, 운영을 위해 필요한 표지판이 빠져 있는 경우가 많습니다.

가장 먼저 정리할 파일 5개는 README.md, package.json, .env.example, 메인 페이지 파일, 외부 서비스 연결 파일입니다. 이 파일들만 정리해도 "어디서부터 봐야 하지?"라는 막막함이 줄어듭니다.

그리고 이 정리는 개발자를 위한 일이기도 하지만, 결국 만든 사람 자신을 위한 일이기도 합니다. 한 달 뒤에 다시 열어도 알아볼 수 있는 프로젝트가 되어야 계속 고칠 수 있습니다.

AI·바이브코딩으로 해결되지 않는 개발 이슈, 먼저 원인부터 확인하세요

Cursor 에러, Vercel·Next.js 배포 실패, 결제·예약 연동 오류, 소규모 기능 개발을 단건 중심으로 진단합니다. 월 구독 파트너는 정식 상품을 준비 중입니다.

무료 진단 신청 다른 글 보기