혼자 북 치고 장구 치는 1인 개발자(Indie Hacker)에게 가장 큰 적은 외부의 경쟁자가 아닙니다. 바로 ‘어제의 내가 짠 스파게티 코드’죠. 서비스를 빠르게 런칭해야 한다는 압박에 코드를 방치하다 보면, 어느 순간 유지보수 비용이 개발 속도를 잡아먹는 역전 현상이 발생합니다.

최근 Next.js 기반의 SaaS 프로젝트를 진행하며 겪은 기술적 부채와 이를 해결하며 얻은 생산성 관리 원칙을 공유합니다.

인지 부하를 줄이는 ‘Rule of 300’

파일 하나가 500줄, 1,000줄을 넘어가기 시작하면 코드를 읽는 것 자체가 고역이 됩니다. 특정 로직을 찾기 위해 스크롤을 반복하다 보면 집중력이 분산되고, 이는 곧 실수로 이어지죠.

저는 이번 프로젝트에서 ‘한 파일은 최대 300줄’이라는 엄격한 기준을 적용했습니다.

• 관심사 분리(Separation of Concerns): UI 로직은 컴포넌트로, 데이터 페칭은 서버 액션이나 커스텀 훅으로 철저히 분리했습니다.
• 가독성 확보: 파일이 300줄 이내로 유지되면 전체 구조가 한눈에 들어옵니다. 새로운 기능을 추가할 때 어디를 수정해야 할지 찾는 ‘탐색 시간’이 획기적으로 줄어듭니다.
• 리팩토링의 자동화: 300줄이 넘어가는 순간을 ‘리팩토링 신호’로 삼으니 코드 퀄리티가 자연스럽게 상향 평준화되었습니다.

💡 Tip: 파일 분리는 단순히 코드를 옮기는 작업이 아닙니다. 복잡도를 하위 단위로 위임하여 개발자의 ‘단기 기억력’을 보호하는 전략적 선택입니다.

확장성을 고려한 다국어(i18n) 아키텍처

글로벌 서비스를 지향한다면 i18n 설정은 필수입니다. 하지만 관리가 허술하면 번역 파일 자체가 병목 구간이 됩니다. 초기에는 하나의 커다란 JSON 파일에 모든 번역을 담았지만, 페이지가 늘어날수록 키값이 겹치고 관리가 불가능해졌습니다.

이를 해결하기 위해 페이지 및 모듈 단위로 번역 파일을 파편화했습니다.

• 구조적 접근: locales/{lang}/{page}.json 형태로 구조화하여 해당 페이지에서 필요한 텍스트만 로드하도록 구성했습니다.
• 수정 속도 향상: 특정 화면의 문구를 수정할 때 해당 JSON 파일만 열면 되니 혼선이 없습니다.
• 성능 최적화: 불필요한 번역 데이터를 불러오지 않아 미세한 성능 이점도 챙길 수 있었습니다.

타입(Type) 정교화로 잡아낸 논리적 결함

프로토타입을 빠르게 만들다 보면 any 타입을 남발하거나 초기값 설정을 대충 넘기곤 합니다. 하지만 서비스가 커지면 이런 작은 구멍들이 치명적인 버그로 돌아옵니다.

주기적으로 타입을 정리하는 시간을 가졌는데, 이 과정에서 흥미로운 점을 발견했습니다. 로직은 완벽해 보였지만 ‘초기값 설정 오류’로 인해 특정 상황에서 샘플 데이터가 오염되는 현상이 있었죠.

• 엄격한 타입 정의: 데이터의 흐름을 타입을 통해 명확히 규정하니, 에디터 수준에서 예외 상황을 미리 잡아낼 수 있었습니다.
• 디버깅 시간 단축: 런타임 에러를 기다리는 대신 컴파일 단계에서 문제를 해결하니 개발 경험(DX)이 비약적으로 상승했습니다.

AI 시대, 왜 여전히 ‘기본 규칙’을 공부해야 하는가

최근 Cursor나 GitHub Copilot 같은 도구 덕분에 코딩의 문턱이 낮아진 건 사실입니다. 저 역시 Next.js 숙련도가 높지 않은 상태에서 AI의 도움을 많이 받았습니다. 하지만 곧 한계에 부딪혔습니다. 제가 Next.js의 컨벤션을 정확히 모르면 AI에게 명확한 가이드를 줄 수 없었기 때문입니다.

AI와의 협업 생산성을 높이기 위해 제가 선택한 방법은 ‘코딩 시간의 절대적 확보와 규칙 학습’입니다.

• 프롬프트의 질 향상: 프레임워크의 규칙을 알면 “이 컴포넌트를 클라이언트 사이드에서 상태 관리 로직과 함께 최적화해 줘”라고 구체적인 지시가 가능합니다.
• 검수 능력: AI가 뱉어낸 코드가 안티 패턴인지 아닌지 판별할 수 있는 눈이 있어야 생산성이 의미가 있습니다.
• 결론: AI는 도구일 뿐, 시스템의 아키텍처와 규칙을 설계하는 것은 여전히 개발자의 몫입니다.

---

기술 회고 및 실행 제언

3줄 요약

• 코드 비대화는 300줄 단위 파일 분리로 선제 대응하세요.
• 번역 파일 등 리소스 관리는 처음부터 페이지 단위로 쪼개는 것이 유지보수에 유리합니다.
• AI 코딩의 효율은 개발자가 보유한 해당 스택의 지식 수준에 비례합니다.

당장 실행할 Action Item

• 프로젝트 내에서 가장 복잡한 로직을 가진 파일 하나를 골라, 타입을 엄격하게 재정의하고 초기값 예외 처리를 검토해 보세요.