주말 과제: Claude Code를 사용하여 SQLite를 C에서 Zig로 모듈별 포팅 중 — 102개 번역 유닛 중 90개가 Zig로 실행됨

저는 Claude Code (Opus)를 사용하여 SQLite 3.54.0을 C에서 Zig로 점진적으로 포팅했습니다.

저는 30년 이상 애플리케이션 / 웹 / 엔터프라이즈 시스템 개발자로 활동해 왔지만, 시스템 프로그래머는 아닙니다. C와 Zig에 대해서는 기본적인 작동 지식만 가지고 있습니다.

왜 Zig인가?

저는 인기를 얻고 있지만 아직 v1.0에 도달하지 않아 움직이는 요소가 많고, 이 실험이 어디까지 갈 수 있는지 확인해 볼 수 있는 언어이자, (이전에 시도했던 몇 가지 실험을 제외하고는) 제가 잘 익숙하지 않은 언어를 원했습니다.

그것이 사실 이 실험의 목적이었습니다.

단순히 "이것을 Zig로 다시 작성해줘"라고 프롬프팅(prompting)하는 것이 아니라, 빌드, 테스트, ABI 호환성, 그리고 반복 가능한 검증에 의해 제약되는 진지한 시스템 코드 마이그레이션(migration) 상황에서 에이전트 기반 코딩 워크플로우(agentic coding workflow)가 어디까지 갈 수 있는지 보고 싶었습니다.

이 프로젝트는 SQLite v3.54.0을 C에서 Zig로 점진적으로 포팅하는 작업입니다.

에이전트들은 가이드만 받았을 뿐 검토(review)를 받지는 않았으며, 이것이 제가 공유하는 직접적인 결과물이라는 점을 유의해 주세요. 어떠한 필터링도 거치지 않은 최대한 가공되지 않은 상태입니다.

따라서 이것을 AI 슬롭(AI slop)이라고 부르는 것은 의미가 없습니다 (만약 당신이 리포지토리(repo)를 클론하여 테스트해 보고 무엇이 깨지는지 저에게 알려주지 않는다면 말이죠. 저는 Claude Code를 사용하여 수정할 수 있고, 격차가 어디에 있는지, 혹은 테스트가 취약한지 확인할 수 있습니다. 저는 여기에 꽤 많은 시간을 투자했으므로, 부정하기 전에 전체적인 목표와 의도가 무엇인지 확인하고 개선을 도와주는 데 몇 분만 할애해 주시길 부탁드립니다. 겸허한 요청입니다).

그것이 커뮤니티에 더 도움이 될 것이며, 이 서브레딧(subreddit) 자체의 목적도 달성될 것입니다. 만약 이것이 완전히 쓸모없다면, 기꺼이 삭제하겠습니다.

이것은 일회성 재작성(one-shot rewrite)이 아닙니다. 접근 방식은 다음과 같습니다:

• 한 번에 하나의 .c 파일을 하나의 .zig 파일로 포팅
• Zig에서 동일한 C ABI 심볼(symbols)을 내보내기(export)
• 포팅된 Zig와 아직 포팅되지 않은 C를 하나의 작동하는 바이너리(binary)로 링크
• 매 단계마다 데이터베이스를 사용 가능한 상태로 유지
• 원래의 SQLite 테스트 스위트(test suite)를 게이트(gate)로 실행

따라서 이 프로젝트는 마지막에만 작동하는 "대규모 재작성 브랜치(big rewrite branch)"가 되지 않습니다. 매일 계속 작동해야 합니다.

현재까지 소요된 대략적인 시간: 약 25~32시간.

현재까지의 규모
Claude Code 세션 트랜스크립트(transcripts)를 분석한 결과(문자 수/4 추정치가 아님):

• 입력(input), 캐시(cache), 출력(output)을 포함하여 현재까지 실제 API 사용량 약 9억 1,900만(919M) 토큰
• 최근 단일 세션에서만 약 7억 8,000만(780M) 토큰 사용
• 활성 C 번역 유닛(translation units) 102개 중 90개가 현재 Zig로 전환됨
• 약 169,000라인의 Zig 코드 생성
• 업스트림(upstream) C 코드 약 287,000라인을 포팅 중

현재 활성 Linux 엔진은 다음 구성 요소 전반에 걸쳐 엔드 투 엔드(end-to-end)로 Zig로 구현되었습니다:
Unix VFS → pager/WAL → btree → VDBE 바이트코드 인터프리터(bytecode interpreter) → tokenizer → 쿼리 플래너(query planner) → 코드 생성(codegen) → 공개 API(public API)

포팅에는 다음과 같은 주요 확장 기능(extensions)도 포함됩니다:

• R*Tree
• session / changeset
• FTS3/4
• FTS5

워크플로우(Workflow)
가장 효과적이었던 워크플로우는 '병렬 초안 작성, 순차적 통합(parallel drafting, serial integration)' 방식이었습니다.

Claude Code 서브 에이전트(sub-agents)들이 개별 모듈의 초안을 작성했습니다. 각 서브 에이전트는 하나의 C 파일에 집중하여 그에 대응하는 src/<name>.zig 파일을 생성했습니다.
메인/오케스트레이터(orchestrator) 흐름은 공유 파일, 빌드 설정(build config), 오프셋 테이블(offset tables), 재연결(relinking), 테스트 및 커밋(commits)을 관리했습니다.
따라서 초안 작성은 병렬로 진행될 수 있었지만, 검증은 항상 순차적이고 권위적으로 이루어졌습니다.

테스트 스위트(test suite)가 실질적인 관문(gate)이었습니다.
모든 모듈 작업이 끝날 때마다, 빌드 시스템은 Zig 객체로 교체된 SQLite 자체의 TCL 테스트 피스처(testfixture)를 재연결(relinks)합니다.
포팅은 테스트가 여전히 통과할 때만 완료된 것으로 간주됩니다.
테스트 통과 사례는 다음과 같습니다:

• ioerr: 10,885개 테스트
• pager1: 1,373개 테스트
• pragma: 0개 오류 / 236개 테스트
• select, join, trigger, index, insert, where: 1,000개 이상의 테스트
• 엄격한 SQLITE_DEBUG 설정 적용

"내가 보기엔 괜찮아 보인다

통합 과정에서 발견된 몇 가지 사례:

a. 호출자가 int를 기대하는 동안 u8을 반환하는 함수 — 이로 인해 상위 반환 레지스터 바이트(upper return-register bytes)가 정의되지 않은 상태가 되어 FTS5의 색인(index)이 손상됨
b. C의 i16 반환 값이 c_int로 노출됨 — 이로 인해 -1인 rowid가 65535로 변하여 트리거(trigger) 동작이 깨짐
c. MEMCELLSIZE가 24바이트 차이 남 — 이로 인해 레지스터와 바운드 파라미터(bound parameter)가 버퍼를 공유하게 되어 결국 double-free 발생
d. 잘못된 테이블 플래그(table-flag) 상수 — 이로 인해 구체화된 CTE(materialized CTEs)가 실제 테이블로 열리며 크래시 발생

이 모든 사례는 대충 읽어서는 통과할 수 있는 것들이었습니다. 오직 기존의 테스트 스위트(test suite)가 관문 역할을 해주었기에 비로소 드러날 수 있었습니다.
이것이 저에게 준 가장 큰 교훈입니다. 만약 이런 종류의 포팅(porting)에 LLM을 사용한다면, 출력물(output)은 진실의 원천(source of truth)이 아닙니다. 원본 프로젝트의 테스트, ABI 동작, 디버깅 도구, 그리고 재현 가능한 빌드 프로세스가 진실의 원천입니다.

한계
아직 포팅되지 않은 파일이 12개 남아 있습니다.
현재의 Linux 빌드 관점에서 볼 때, 이 파일들은 생성된 파서/코드 생성(parser/codegen) 출력물, Windows 전용 파일, 또는 플래그 비활성 대안(flag-inactive alternates)들입니다. 저는 포팅이 "100% 완료"되었다고 가장하는 대신, 이들을 별도로 추적하고 있습니다.
또한 리포지토리(repo) 내의 토큰 사용량도 추적하고 있는데, 이 정도 규모의 프로젝트라면 비용에 대해 책임을 져야 하기 때문입니다.
참고용 리포지토리:
https://github.com/algorisys-oss/sqlite-zig
여기에는 SQLite 바이너리를 실행하기 위한 sqlite-zig 터미널/CLI 애플리케이션도 포함되어 있습니다.

이 작업을 수행한 이유
이것은 프로덕션 환경에 즉시 투입 가능한(production-ready) SQLite로 제시된 것이 아닙니다.
또한 Claude가 대규모 포팅을 생성해냈다고 해서 제가 갑자기 시스템 프로그래머가 되었다는 주장도 아닙니다.
저의 진짜 목표는 어렵고 테스트 가능한 코드베이스를 대상으로 에이전틱 AI(agentic AI) 워크플로우를 연구하는 것이었으며, 생성된 출력물을 학습 도구(learning artifact)로 사용하여 시스템 프로그래밍을 더 잘 이해하는 것이었습니다.
저는 구조(전체 코드는 아님), 설계 결정, ABI 경계, 그리고 실패 지점들을 검토할 것입니다. 생성된 16만 9천 줄의 코드를 반드시 한 줄씩 모두 검토하겠다는 것은 아니지만, 마이그레이션(migration)이 어떻게 형성되었고 중요한 기술적 리스크가 어디에 있는지 이해할 수 있을 만큼은 검토할 것입니다.

이 포스트는 주로 Claude Code의 로그, 프롬프트(prompts), 그리고 리포지토리(repo) 진행 노트를 기반으로 작성되었으며, 명확성을 위해 약간의 인간 편집을 거쳤습니다.

추신(PS): 이 포스트는 이 스레드의 댓글과 피드백을 바탕으로 업데이트되었습니다.
저는 기술적 실험을 명확하고 책임감 있게 공유하는 방법을 여전히 배우는 중이므로, 피드백 그 자체도 저에게는 학습 과정의 일부입니다.

추가 추신(PSS): 많은 분이 이런 종류의 콘텐츠를 싫어한다는 것을 알고 있으며, 그렇게 느끼시는 것도 당연합니다. 하지만 이곳은 ClaudeAI 서브레딧(subreddit)이기에, 저는 모든 내용을 필터링 없이 ClaudeAI가 생성한 그대로 유지하되 필요한 경우에만 약간의 개인적인 터치를 가하고, 이후 이 커뮤니티의 피드백을 바탕으로 개선하려고 노력했습니다.

제출자: /u/thinkrajesh
[링크] [댓글]