주말 과제: Claude Code를 사용해 SQLite를 C에서 Zig로 모듈 단위로 포팅 중 — 102개 번역 단위 중 90개 완료, 9억 1,900만 토큰 사용, 매 단계마다 SQLite 자체 테스트 스위트로 검증

워크플로우

병렬로 초안 잡고, 직렬로 통합하는 방식이 제일 잘 먹혔음.

Claude Code 서브 에이전트들이 개별 모듈 초안을 짰음. 각 에이전트는 C 파일 하나를 맡아서 src/<name>.zig를 만드는 식.

메인 오케스트레이터는 공유 파일, 빌드 설정, 오프셋 테이블, 재링크, 테스트, 커밋을 관리함.

그러니까 초안 작업은 병렬로 가능했지만, 검증은 항상 순차적으로 확실하게 진행했음.

테스트 스위트가 진짜 관문이었음

모듈 하나 끝날 때마다 SQLite 자체 TCL testfixture를 Zig 오브젝트랑 바꿔 끼워서 재링크함.

테스트를 통과해야만 포팅이 끝난 걸로 침.

통과한 테스트 예시:

• ioerr: 10,885개 테스트
• pager1: 1,373개 테스트
• pragma: 에러 0 / 236개 테스트
• select, join, trigger, index, insert, where: 1000개 이상 테스트
• 엄격한 SQLITE_DEBUG 설정

"내 눈엔 괜찮아 보이는데?" 같은 건 없음. 원본 프로젝트 테스트 통과 못 하면 포팅 인정 안 함.

디버깅

문제가 생기면 진짜 디버깅 툴을 썼음:

• gdb
• Zig랑 C 동작 비교
• EXPLAIN 바이트코드 차이 분석
• 실패한 SQLite TCL 테스트
• ABI/시그니처 체크

이게 중요했던 게, 제일 골치 아픈 버그들은 뻔한 번역 실수가 아니었거든. 데이터가 조용히 깨지는 그런 류의 버그들이었음.

통합 과정에서 잡힌 몇 가지 예시:

• 호출자는 int를 기대하는데 함수는 u8을 반환해서, 상위 반환 레지스터 바이트가 정의되지 않은 상태가 되고 FTS5 인덱스가 망가지는 문제
• C의 i16 반환값이 c_int로 노출되면서 -1 rowid가 65535로 바뀌어 트리거 동작이 박살 나는 문제
• MEMCELLSIZE가 24바이트만큼 어긋나서 레지스터와 바인드 파라미터가 버퍼를 공유하다가 결국 더블 프리(double-free)가 발생하는 문제
• 테이블 플래그 상수가 잘못되어 구체화된(materialized) CTE가 실제 테이블로 열리면서 크래시가 나는 문제

이런 것들은 대충 훑어보면 그냥 넘어갈 수도 있는 수준임. 원래 있던 테스트 스위트가 관문 역할을 해준 덕분에 겨우 찾아낸 거지.

이게 나한테는 가장 큰 교훈임. 이런 식의 포팅에 LLM을 쓴다면, LLM이 뱉어낸 결과물이 진실의 원천(source of truth)이 아니라는 거. 원본 프로젝트의 테스트, ABI 동작, 디버깅 도구, 그리고 재현 가능한 빌드 과정이 진짜 진실의 원천임.

한계

아직 포팅 안 된 파일이 12개 남았음.

지금 리눅스 빌드 관점에서 보면, 이건 파서/코드 생성기가 만든 결과물이거나 윈도우 전용 파일, 혹은 플래그가 꺼져 있는 대체 파일들임. 포팅이 "100% 완료"됐다고 구라치지 않고 따로 추적 중임.

이 정도 규모의 프로젝트라면 비용에 대해서도 책임감이 있어야 한다고 생각해서 리포지토리의 토큰 사용량도 기록하고 있음.

참고용 리포지토리:

https://github.com/algorisys-oss/sqlite-zig

SQLite 바이너리를 실행할 수 있는 sqlite-zig 터미널/CLI 애플리케이션도 포함되어 있음.

이걸 왜 했냐고?

이걸 프로덕션용 SQLite라고 내놓는 게 아님.

Claude가 대규모 포팅을 해줬다고 해서 내가 갑자기 시스템 프로그래머가 됐다고 주장하는 것도 아니고.

내 진짜 목표는 어렵고 테스트 가능한 코드베이스에서 에이전트형 AI 워크플로우를 연구하고, 생성된 결과물을 학습 자료로 삼아 시스템 프로그래밍을 더 깊게 이해하는 거였음.

구조(전체 코드는 아니고), 설계 결정, ABI 경계, 그리고 실패 지점들을 검토할 생각임. 16만 9천 줄이나 되는 코드를 한 줄 한 줄 다 보겠다는 건 아니지만, 마이그레이션이 어떤 식으로 이루어졌고 중요한 기술적 리스크가 어디에 있는지 파악할 정도로는 볼 거임.

이 글은 대부분 Claude Code 로그, 프롬프트, 리포지토리 진행 상황 노트를 바탕으로 작성했고, 가독성을 위해 사람이 살짝 다듬었음.

추신: 이 글은 이 스레드에 달린 댓글과 피드백을 바탕으로 업데이트됐음.

기술적인 실험을 명확하고 책임감 있게 공유하는 법을 아직 배우는 중이라, 피드백 자체가 나한테는 학습 과정의 일부임.

추추신: 이런 류의 글을 싫어하는 사람이 많다는 거 알고 있고, 그들의 반응도 충분히 이해함. 하지만 여긴 ClaudeAI 서브레딧이니까, 최대한 필터링 없이 ClaudeAI가 생성한 내용을 그대로 담으려 노력했고, 필요한 부분에만 내 개인적인 느낌을 살짝 섞은 뒤 커뮤니티 피드백을 반영해서 개선했음.