맥북 속 프로젝트 70개, 1초 만에 인덱싱하기

내 맥북의 ~/Developer 폴더는 75GB다. 카테고리 폴더 11개, 그 안에 프로젝트 70개. 문제는 그중 절반이 뭐였는지 나도 기억이 안 난다는 것이다. temp/rkserver가 뭐였더라? english-staff는 왜 있지? 새 프로젝트를 시작할 때마다 “이거 예전에 비슷한 거 만들지 않았나?“를 확인할 방법이 없었다.

그래서 인덱싱 시스템을 만들었다. 이름은 devindex. 결과부터 말하면 70개 프로젝트 전체 스캔에 1초가 걸리고, 산출물은 마크다운 파일 하나다.

결정 1: AI에게 시키지 않는다

요즘이라면 당연히 “AI 에이전트한테 폴더 다 읽고 정리하라고 하면 되지”라고 생각하기 쉽다. 실제로 처음엔 그 방향을 검토했다. 그런데 계산이 안 맞는다. 70개 프로젝트를 매번 AI가 크롤링하면 갱신할 때마다 토큰이 무더기로 나간다. 더 나쁜 건, 같은 정보를 매번 다시 읽는다는 점이다.

그래서 역할을 갈랐다. 기계가 알 수 있는 것은 스크립트가, 기계가 알 수 없는 것만 AI가. 마지막 커밋 날짜, 브랜치, 미커밋 변경, 기술 스택(package.json과 pyproject.toml만 읽으면 된다), 배포 흔적(vercel.json, Dockerfile…) — 전부 파일시스템에 이미 있는 정보다. 파이썬 표준 라이브러리만으로 다 읽힌다. AI가 필요한 건 딱 하나, “이 프로젝트가 뭔지 한 줄로 설명하기”였고, 이건 프로젝트당 최초 1회면 끝난다.

결정 2: 메타데이터는 프로젝트 옆에 둔다

설명이나 배포 정보처럼 자동 추출이 안 되는 데이터를 어디에 둘지가 실제 설계의 갈림길이었다. 중앙 파일 하나에 모으는 방식은 처음엔 편하지만, 프로젝트를 지우거나 이름을 바꾸는 순간부터 조용히 어긋난다. 유령 항목이 쌓여도 아무도 모른다.

대신 각 프로젝트 루트에 .project.toml을 하나씩 뒀다. 프로젝트를 지우면 메타데이터도 같이 사라진다. 어떤 프로젝트에서 작업하다가 배포처가 바뀌면 그 자리에서 그 파일만 고치면 된다. 정합성이 구조적으로 유지된다.

결정 3: 스캐너는 절대 메타파일을 고치지 않는다

스캐너의 파일 쓰기 권한은 정확히 두 가지로 제한했다. 메타파일이 없는 프로젝트에 스켈레톤을 만드는 것, 그리고 최종 산출물인 INDEX.md를 덮어쓰는 것. 이미 존재하는 .project.toml은 어떤 경우에도 건드리지 않는다.

이 불변 조건 덕분에 스캔은 몇 번을 돌려도 안전하고(멱등), 사람이든 AI든 메타파일에 적어둔 내용이 증발할 걱정이 없다. 실제로 최초 설명 채우기는 Claude Code 서브에이전트 6개를 병렬로 돌려 한 번에 끝냈는데, 스캐너와 에이전트가 같은 파일을 만져도 충돌할 일이 없었다.

결과

지금 ~/Developer/INDEX.md에는 70개 프로젝트가 활동 상태(🟢 활성 / 🟡 뜸함 / 🔴 방치)순으로 정렬돼 있고, 설명이 비었거나 미커밋 변경이 방치된 프로젝트는 ⚠️ 섹션에 자동으로 올라온다. 부수입도 있었다. 인덱싱 과정에서 완전히 빈 디렉토리 5개와, 서로 복제본인 프로젝트 한 쌍을 발견했다.

그리고 이 시스템은 곧 다른 것의 토대가 됐다. 지금 읽고 있는 이 포트폴리오 사이트가 바로 그 .project.toml 70개를 데이터 소스로 빌드된다. 그 얘기는 다음 글에서.