지난번 【설계 편】에서는 '정리 뽑기 가챠' 앱 MicroWin의 설계를 여러 AI에게 검토받으며, 결제 설계의 자기 모순이나 측정 방식의 허점을 보완한 이야기를 작성했습니다.
이번 글은 구현 편입니다. 데이터 계층(SQLite 마이그레이션)을 소재로 삼아, 'AI와의 설계 리뷰에서 나온 지적 사항들을 코드 구조적으로 어떻게 녹여냈는지'를 기록합니다.
소재로 이 부분을 선정한 이유는 간단합니다. 개인 개발에서도 스키마는 반드시 변경되기 때문입니다. v1로 출시한 기능이 v2에서 바뀌거나, 컬럼을 추가하거나, 타입을 수정하는 경우 — 그럴 때마다 사용자 단말기 내 데이터베이스를 손상시키지 않고 업데이트할 수 있는 메커니즘이 없다면, 업데이트 시 데이터가 사라집니다. 취미용 앱이라도 이 부분을 대충 처리하면 나중에 큰일 납니다 (저는 그러고 싶지 않아서 만들었습니다).
MicroWin의 데이터 계층은 React Native (Expo) + expo-sqlite를 사용합니다. 구성은 다음 2단계로 진행했습니다.
| 단계 | 내용 | 테스트 수 | 커버리지 |
|---|
| PR1 | 마이그레이션 프레임워크 + SQLite 어댑터 추상화 | 98건 | 88.88% |
| Day 5+ | 실제 expo-sqlite SDK와의 통합 | 133건 | 90.57%(DB 계층은 100%) |
TypeScript, 테스트는 Jest, tsc와 lint는 제로(zero) 상태를 유지했습니다.
먼저, AI들의 설계 리뷰(여러 벤더의 AI에게 동일한 설계서를 보여주고 독립적으로 검토받는 방식)에서 나온 지적 사항들을 다음 4가지 구조 판단으로 구현했습니다.
리뷰 과정에서 '마이그레이션 러너에 PRAGMA 문자열을 직접 삽입하지 말라'는 지적이 있었습니다. 초기 구상은 러너에 직접 삽입하는 것이었으나, 지적대로 어댑터 계층을 만들자:
- 테스트에서는 Fake 어댑터(메모리 구현)로 완료 가능하며,
- 실제 환경에서는 expo-sqlite용 어댑터로 교체만 하면 됩니다.
- SDK를 변경하고 싶어도 1 파일 수정으로 흡수할 수 있습니다.
'테스트에서 Fake, 실전에서 진짜'를 동일한 러너 코드에서 구동할 수 있게 되면서, 이후의 Day 5+ 작업이 상당히 수월해졌습니다.
PRAGMA user_version
숫자만으로는 'v1은 적용되었지만, 테이블이 손상된 상태'라는 것을 감지할 수 없습니다. 리뷰에서 3개의 AI가 독립적으로 이력 관리를 지적했기 때문에, schema_migrations 테이블을 만들어 적용 완료된 마이그레이션을 기록하는 방식으로 변경했습니다.
게다가 '기존 데이터베이스가 이미 v1 상당이었을 경우, 실수로 v1을 주입하지 않는다'는 부트스트랩(bootstrap) 조건 역시 리뷰에서 1개의 AI가 지적하여 테스트를 수정했습니다.
이것 또한 여러 개체가 독립적으로 지적한 critical 사항입니다. DDL은 트랜잭션으로 감싸지 않으면, 도중에 실패했을 때 절반만 적용된 상태가 남게 됩니다. 그렇게 되면 재시도(retry)도 롤백(rollback)도 할 수 없고, 단말기마다 손상되는 방식이 제각각이 됩니다.
'1 마이그레이션 = 1 트랜잭션 = 실패 시 전부 롤백'을 계약처럼 러너 구조에 심었습니다.
PR1의 설계 리뷰에서 38건의 지적이 나와 그중 11건을 채택한 후, 구현 코드를 또 다른 리뷰에 거치자 36건이 나왔고, 그중 critical 5건을 즉시 수정했습니다. 설계 리뷰를 거쳤다고 해서 구현상의 허점이 사라지는 것은 아닙니다. 이 '설계 리뷰 → 구현 → 구현 리뷰'의 2단 구조는 비용 대비 효과가 좋았습니다.
PR1은 Fake 어댑터로 TDD(Test-Driven Development)를 진행했기 때문에, 실제 expo-sqlite (SDK 57)와 연결하는 단계에서 실기적인 제약에 직면했습니다.
체크섬 계산을 Node의 crypto로 작성했던 부분을, 실제 환경에서는 expo-crypto로 대체해야 할 필요가 있었습니다. 여기서 선택지가 3가지였습니다:
- expo-crypto의 digestStringAsync로 전환 (문자열을 직접 받을 수 있음) - crypto의 digest (Uint8Array 받음)를 유지하고, 문자열 → Uint8Array 변환을 자체 구현
- polyfill 라이브러리를 추가
2번은 Hermes에 TextEncoder가 존재하지 않기 때문에, UTF-8 인코딩을 직접 구현해야 합니다. 인코딩을 직접 구현하는 것은 감사 위험이 높고, 3번은 의존성이 증가하여 Expo의 권장 경로에서 벗어납니다. 결과적으로, 1번의 "인터페이스를 비동기화하는" 방식을 채택했습니다. 인터페이스의 파괴적 변경(러너 2개소 + 테스트 기대값 계산)이라도 수정 범위가 작아 다행이었습니다.
expo-sqlite의 withTransactionAsync는 공식 문서 실측 기반으로 스코프 외부 쿼리까지 트랜잭션에 포함시키는 동작을 보였습니다. async/await의 특성상 피할 수 없는 것입니다. 마이그레이션 용도에서는 "이 범위만 확실하게 트랜잭션에 포함하고 싶다"는 요구사항 때문에, 배타적 스코프를 제공하는 withExclusiveTransactionAsync를 채택했습니다.
이 부분은 "실제 SDK를 읽어보기 전까지 알 수 없는 종류의 문제"였고, Fake 테스트는 모두 녹색(Green)이었습니다. Fake에서의 TDD와 실제 SDK에서의 통합 테스트, 두 가지 가치를 다시금 상기시켜 준 국면이었습니다.
- 테스트: 98건 (PR1) → 133건 (Day 5+)・모두 녹색(Green) - 커버리지: 88.88% → 90.57% (SQLite 어댑터와 마이그레이션 본체는 100%) - 설계 리뷰 38건 → 채택 11건 / 구현 리뷰 36건 → Critical 5건 즉시 수정
- 기계 체크 (tsc・lint)는 항상 0을 유지
이번에 가장 효과적이었던 방법은, 리뷰 지적 사항을 그대로 구현하지 않고, 선택지를 3가지 정도 나열하고 "왜 그것을 채택했는지"를 작성한 후에 구현하는 방식이었습니다.
지적 자체는 맞는 경우가 많지만, 구현 형태는 여러 가지가 있을 수 있습니다. checksum 비동기화 3가지 안처럼 "지적은 같더라도, 채택하는 구조에 따라 미래의 부채가 달라지는" 상황이 반드시 옵니다. 선택한 이유를 기록해 두면 나중에 "왜 이걸로 만들었더라?"라고 질문받았을 때 (대부분은 미래의 자신에게) 답할 수 있습니다.
참고로, 설계 편에서 작성했듯이 이 프로세스에서는 "AI의 지적을 채택했을 때, 그 수정 과정에 새로운 구멍이 생기지 않았는지"를 별도의 리뷰 라운드에서 확인하고 있습니다. 구현 편에서 소개한 판단들 역시 지난 기사와 동일한 리뷰 프레임워크로 여러 AI에게 검토받았습니다.
다음으로는 인지 획득 편 (릴리스를 위해 테스터를 모으는 시스템 및 측정 설계)을 작성할 예정입니다. 앱 자체의 내부 테스트 준비도 진행하고 있습니다.
※ 본 기사의 개발 작업은 Claude Code 상에서 진행했지만, 판단은 모두 사람이 수행했습니다.
(이 기사는 개발 과정의 기록입니다. 오류가 있다면 댓글로 알려주세요)
본 기사는 개인 Zenn에서도 공개하고 있습니다.