코드베이스 전체를 단일 파일로: repomeld 개발 과정과 기술 심층 분석

AI 시대가 도래하며 개발자들은 AI 모델에게 전체 코드베이스 컨텍스트를 제공해야 하는 필요성을 느꼈습니다. 이 과정에서 수십 개의 파일을 수동으로 복사하는 비효율성에 직면했고, 이를 해결하기 위해 'repomeld'라는 CLI 도구를 개발하게 되었습니다.

💡 repomeld란?
repomeld는 프로젝트의 전체 코드를 단일 파일로 병합하여 AI 컨텍스트 준비, 코드 리뷰 자료 생성, 또는 프로젝트 아카이빙에 최적화된 출력을 제공하는 도구입니다. 초기에는 단순한 스크립트였으나, 사용자 피드백을 반영하며 프로덕션 레벨의 복잡성을 갖추게 되었습니다.

🚀 개발 과정에서 배운 핵심 기술 및 노하우 (Technical Deep Dive)

1. 성능 최적화: 비동기 처리로 10배 성능 개선
   초기 버전은 fs.readdirSync와 같은 동기식(synchronous) 파일 시스템 접근 방식을 사용하여 이벤트 루프를 차단하고 속도가 느렸습니다. 이를 해결하기 위해 비동기 반복(Async Iteration)과 지능적인 캐싱 기법을 도입했습니다. 이 최적화를 통해 10,000개 파일을 스캔하는 시간이 기존의 45초에서 3.2초로 극적으로 단축되었습니다.

2. 정교한 바이너리 파일 감지 (Binary Detection)
   단순히 확장자를 검사하는 것만으로는 부족합니다. UTF-8 텍스트에 포함될 수 있는 널 바이트(null byte)와 실제 바이너리 데이터의 경계가 모호하기 때문입니다. 따라서, 확장자 블랙리스트와 **콘텐츠 샘플링 (Content Sampling)**을 결합한 하이브리드 접근 방식을 채택했습니다. 파일 내용을 읽어 처음 512바이트를 검사하고 널 바이트(0) 포함 여부를 확인하여 정확도를 높였습니다.

3. 크로스 플랫폼 경로 처리 (Cross-Platform Path Hell)
   Windows와 Unix 시스템 간의 경로 구분자(path separator) 차이로 인해 발생하는 버그는 CLI 개발에서 흔한 문제입니다. 모든 경로를 path.sep을 기준으로 분리하고 다시 합치는 방식으로 통일하여, 운영체제에 관계없이 일관된 결과를 보장했습니다.

4. 사용자 경험 (UX) 중심의 기능 설계

   • .gitignore 지원: 가장 요청이 많았던 기능으로, ignore 패키지를 활용하여 표준 .gitignore 규칙을 완벽히 준수하도록 구현했습니다. 이는 불필요한 파일 포함을 막아줍니다.
   • 다중 출력 스타일: 사용 목적에 맞춰 세 가지 출력을 제공합니다: 1) Banner (메타데이터와 시각적 분리), 2) Markdown (AI 도구 붙여넣기에 최적화), 3) Minimal (순수 코드만 포함).
   • 자동 백업: 기존 파일을 덮어쓰는 것을 방지하기 위해 repomeld_output__N.txt와 같은 자동 번호가 매겨진 백업 파일 및 ZIP 아카이브 기능을 제공합니다.

✨ 개발자에게 주는 교훈 (Lessons Learned)
개발 도구(CLI)를 만들 때는 라이브러리부터 시작하기보다 **사용자 경험(UX)**을 최우선으로 두고 CLI 인터페이스부터 설계해야 합니다. 또한, 초기 단계부터 Windows와 같은 다양한 OS 환경에서 테스트하는 것이 필수적입니다. 기능 플래그(--dry-run, --no-backup)를 활용하여 CI/CD 파이프라인에서의 유연성을 확보하는 것도 중요합니다.