2026년 5월, k10s.dev의 한 인디 개발자가 "I'm going back to writing code by hand"라는 글로 해커뉴스 1위 근처에 올랐어요. 내용을 요약하면 이래요. Claude와 Cursor만 가지고 쿠버네티스 GPU 대시보드를 7개월간 만들었는데, 어느 순간 코드베이스가 1,690줄짜리 단일 god file로 융합되어 더 이상 새로운 기능을 추가할 수가 없게 됐다는 거죠. 그래서 결국 손코딩으로 돌아가 처음부터 다시 짜기로 했다는 회고였습니다.
같은 주에 millionco/react-doctor가 일주일 만에 깃허브 스타 7천 개를 넘었어요. 캐치프레이즈가 "Your agent writes bad React. This catches it"입니다. 이 두 사건이 동시에 터진 게 우연이 아니에요. AI 코딩 에이전트가 짜낸 코드의 누적 부채가 2026년 스타트업의 다음 병목이 되고 있다는 신호예요.
원글 저자는 무너진 이유를 세 가지로 정리해요. 첫째, 매번 새 채팅을 시작했기 때문에 모델이 기존 모듈 경계를 모른 채 같은 파일에 계속 코드를 덧붙였어요. 둘째, 기능 단위로 PR을 나누지 않고 "버튼 하나만 더 추가해 줘" 같은 요청을 연속으로 던졌어요. 셋째, 리팩터링 비용이 0으로 보였기 때문에 정작 진짜 리팩터링을 한 번도 하지 않았어요.
여기서 핵심은 마지막 포인트예요. AI 코딩은 새 기능을 만드는 비용은 극단적으로 낮추지만, 코드를 이해하고 정리하는 비용은 그대로입니다. 그래서 인간이 의식적으로 "지금부터 30분은 리팩터링"이라고 시간을 내지 않으면, AI는 같은 파일을 영원히 키우는 쪽으로 최적화돼요.
새 프로젝트를 시작할 때 가장 먼저 해야 할 일은 모델한테 "Next.js 앱 만들어 줘"라고 던지는 게 아니에요. 도메인 모듈 경계와 디렉토리 구조를 사람이 먼저 설계한 다음, 각 모듈의 진입점만 비워둔 골격을 미리 만드는 거예요. 그 위에서 AI가 코드를 채워야 god file로 융합되지 않습니다. 포텐랩이 진행하는 MVP 프로젝트도 첫 2~3일은 코드 0줄 상태에서 아키텍처 다이어그램과 모듈 책임만 합의한 뒤 코딩에 들어가요. 늦은 게 아니라 빠른 길이에요.
react-doctor 같은 도구가 인기를 끄는 이유는 사람 리뷰어가 잡지 못하는 크기 제약을 CI 단에서 자동으로 차단해 주기 때문이에요. 추천 임계는 단일 파일 700줄, 단일 함수 80줄, 단일 컴포넌트 props 7개. 넘으면 PR이 머지되지 않게 만드세요. ESLint max-lines·max-lines-per-function 룰만 켜도 70%는 자동 차단됩니다.
AI 코딩 에이전트의 가장 큰 함정은 이전 대화의 맥락이 사라진다는 거예요. 그래서 각 모듈마다 CONTEXT.md라는 작은 카드를 두세요. "이 디렉토리는 X 책임을 진다, Y 모듈에 의존한다, Z 패턴을 따른다" 정도 다섯 줄이면 충분해요. 새 채팅을 열 때마다 그 카드를 먼저 붙여 넣으면, 같은 파일에 코드가 융합되는 빈도가 절반 이하로 떨어집니다.
AI 코딩 시대에는 커밋 단위가 더 작아져야 합니다. 사람이 손으로 짤 때는 50줄짜리 PR도 검토할 만했지만, AI가 짠 500줄짜리 PR은 누구도 진짜로 읽지 못해요. 그래서 우리는 PR 한 개의 변경 범위를 파일 5개 이하, 변경 250줄 이하로 제한해요. 넘어가는 순간 god file로 가는 첫 신호예요.
오늘 저녁 30분만 들이면 됩니다. 첫 10분에는 CONTEXT.md 템플릿을 만들어 모듈마다 한 장씩 깔아두세요. 다음 10분에는 ESLint의 max-lines: 700, max-lines-per-function: 80을 켜고 CI에 통과 조건으로 박아두세요. 마지막 10분에는 지난주 PR 중 가장 큰 것 하나를 골라 절반으로 쪼개는 연습을 해 보세요. AI 코딩의 진짜 ROI는 새 기능 속도가 아니라, 이 세 가지를 자동화해서 얻는 장기 유지보수 비용 절감에서 나와요.
포텐랩은 2026년 들어 진행한 MVP 프로젝트 12건 중 단 1건도 god file 문제를 겪지 않았어요. 이유는 단순해요. 코드를 처음부터 더 적게 짜고, AI가 짠 코드를 매주 30분씩 정리하는 루틴을 클라이언트 워크플로에 박아두기 때문이에요. AI 코딩 에이전트와 함께 6개월 뒤에도 살아남는 코드베이스를 만들고 싶다면, 포텐랩에 1시간만 시간을 내달라고 요청해 보세요. 어디서부터 god file이 자라고 있는지 PR 다섯 개만 봐도 보입니다.