30일 만에 Claude Code로 프로덕션 AI 플랫폼 구축하기: 솔직한 이야기
화요일 새벽 2시, 결제 시스템이 사용자에게 요금을 이중으로 청구하고 있다는 사실을 깨달았습니다. 그 버그는 이미 6시간 동안 프로덕션 환경에 배포되어 있었습니다. 그날 오후 Claude Code가 결제 정산 로직을 생성했고, 저는 이를 검토하고 테스트한 뒤 배포했습니다. 코드는 완벽해 보였습니다. 모든 테스트를 통과했죠. 하지만 근본적으로 망가져 있었습니다.
이것은 AI 코딩 어시스턴트와 함께 274개의 API 라우트, 46개의 데이터베이스 모델, 10만 줄 이상의 코드로 구성된 LemonData를 구축한 이야기입니다. "AI가 얼마나 생산적인지 보세요"라는 식의 다듬어진 이야기가 아닙니다. 실패와 새벽 3시의 디버깅 세션, 그리고 AI 지원 개발이 정말 좋은 생각인지 의심했던 순간들이 담긴 진짜 이야기입니다.
AI 지원 개발의 홍보 문구 vs 현실
AI 코딩 어시스턴트의 홍보 문구는 매혹적입니다. 원하는 것을 설명하면 AI가 작성하고, 당신은 검토 후 배포하기만 하면 됩니다. 이론적으로는 이제 개발자 한 명이 전체 팀의 업무를 수행할 수 있습니다.
현실은 어떨까요? 처음 2주 동안은 놀라웠습니다. Claude Code는 내 코드베이스를 이해했고, 완전한 기능을 생성했으며, 여러 파일에 걸쳐 리팩토링을 수행했습니다. 제 경력을 통틀어 그 어느 때보다 빠르게 결과물을 내놓고 있었습니다. 이슈를 그렇게 빨리 해결하며 느끼는 도파민은 중독적이었습니다.
그러다 균열이 생기기 시작했습니다.
동일한 함수가 약간씩 다른 구현으로 세 개의 서로 다른 파일에 나타났습니다. 설정값들이 무작위 위치에 하드코딩되었습니다. 타입 정의가 패키지마다 서로 모순되었습니다. 코드베이스는 빠르게 성장했지만, 동시에 "작동은 하지만 이유는 모르는" 코드의 미로가 되어가고 있었습니다.
그리고 그 결제 버그요? Claude는 겉보기에는 완벽한 정산 함수를 생성했습니다. 하지만 비동기 결제 확인 흐름에서의 race condition을 고려하지 않았습니다. 제가 명시적으로 말해주지 않았기 때문에 AI는 그 엣지 케이스를 알 방법이 없었고, 부분적으로 AI가 생성한 테스트 스위트 역시 이를 다루지 않았습니다.
계속해서 반복된 7가지 패턴
Claude Code로 한 달간 개발한 후, 저는 목록을 작성하기 시작했습니다. 정확히는 버그 목록이 아니라 패턴 목록이었습니다. 동일한 종류의 실패가 반복되었는데, 이는 Claude의 잘못이라기보다는—적어도 전적으로는—AI가 "내일 작동할 코드"보다는 "지금 작동하는 코드"에 최적화된 결과로 나타나는 예측 가능한 현상이었습니다.
1. 일관성 문제 (The Consistency Problem)
Claude는 작업 중인 파일, 최근에 본 예시, 또는 단순히 무작위적인 변덕에 따라 동일한 로직을 다르게 구현하곤 했습니다. 어떤 API 엔드포인트는 { data: users }를 반환하고, 다른 엔드포인트는 { users }를 반환했습니다. 둘 다 작동은 했지만, 서로 일치하지 않았습니다. 디버깅은 마치 고고학 발굴 작업처럼 변했습니다.
2. 복사-붙여넣기 문제 (The Copy-Paste Problem)
코드 복제가 더 빠르고 기존 기능을 망가뜨릴 위험이 없는데, AI가 왜 공통 유틸리티를 만들겠습니까? 기존 기능과 유사한 새 기능을 요청할 때마다 리팩토링된 공유 솔루션 대신 새로운 구현을 받게 되었습니다. 3주 후, 코드베이스 여기저기에 5개의 서로 다른 "format currency" 함수가 흩어져 있었습니다.
3. 타입 드리프트 문제 (The Type Drift Problem)
새로운 상태 값이 한 파일에는 추가되지만 enum 정의에는 누락되곤 했습니다. API 응답에서는 선택 사항인 필드가 프론트엔드 타입에서는 필수 사항으로 되어 있기도 했습니다. TypeScript가 일부는 잡아냈지만, 타입은 기술적으로 맞지만 논리적으로 일치하지 않는 semantic mismatch는 잡아내지 못했습니다.
4. 설정 분산 문제 (The Configuration Scatter Problem)
데이터베이스 URL, API 키, feature flag, rate limit 등—Claude는 현재 작업에 편리한 곳이라면 어디든 이를 배치했습니다. 때로는 환경 변수에, 때로는 설정 파일에, 때로는 하드코딩으로 말이죠. 값이 정의된 모든 위치를 찾는 것은 보물찾기가 되었습니다.
5. 테스트 커버리지의 착각 (The Test Coverage Illusion)
AI가 생성한 테스트는 happy path는 철저히 테스트하지만 엣지 케이스는 완전히 놓치는 경향이 있습니다. 결제 버그가 완벽한 예시입니다. 테스트 스위트는 일반적인 결제 흐름은 훌륭하게 커버했지만, 동일한 millisecond 내에 두 개의 결제 확인이 도착했을 때 어떤 일이 벌어지는지는 전혀 테스트하지 않았습니다.
6. 침묵하는 실패 문제 (The Silent Failure Problem)
Claude는 예외를 삼켜버리는 catch (error) { console.log(error) } 블록을 추가하곤 했습니다. 개발 중에는 콘솔에 에러가 표시되므로 괜찮아 보였지만, 프로덕션에서는 치명적인 실패가 조용히 로그에 남겨진 채 잊혀졌습니다.
7. 문서화의 공백 (The Documentation Gap)
Claude는 훌륭한 코드 주석을 작성합니다. 하지만 아키텍처 문서는 형편없습니다. 함수가 무엇을 하는지는 설명할 수 있지만, 시스템이 왜 그렇게 구조화되었는지, 또는 특정 설계 결정에 어떤 제약 조건이 있었는지는 설명하지 못합니다.
CLAUDE.md 솔루션
전환점은 3주 차에 CLAUDE.md를 만들었을 때 찾아왔습니다. 프로젝트 루트에 위치하며 Claude가 알아야 할 모든 컨벤션, 제약 조건, 아키텍처 결정을 담은 파일입니다.
사람을 위한 문서가 아니라, AI를 위한 문서입니다.
## API Response Format
Always use: { success: true, data: T } or { success: false, error: string }
Never return raw data without the wrapper.
## Currency
Internal storage: USD. Display: formatCurrency(amount, currency, rate).
Never hardcode exchange rates. Never store CNY directly.
## Error Handling
Never use catch(e) { console.log(e) }.
Always use the logger: logger.error('context', { error }).
효과는 즉각적이었습니다. Claude는 컨벤션을 일관되게 따르기 시작했습니다. 규칙을 위반하는 코드를 생성했을 때 CLAUDE.md의 특정 라인을 지적하면 스스로 수정했습니다.
하지만 CLAUDE.md만으로는 충분하지 않았습니다. 자동화된 강제 수단이 필요했습니다.
안전망 구축: AI 생성 코드를 위한 CI 게이트
저희는 전통적인 코드베이스에서는 편집증적으로 보일 법한 게이트가 포함된 CI 파이프라인을 구축했습니다. 이는 AI가 생성한 버그가 사용자에게 도달하기 전에 잡아내기 위해 존재합니다.
- 모든 monorepo에 대한 Type checking (타입 드리프트 방지)
- 중복 구현이 없는지 확인하는 SSOT audit
- 데이터베이스 enum이 TypeScript enum과 일치하는지 확인하는 Enum sync check
- API 응답 형식 검증 (일관성 문제 해결)
- 결제, 권한, 인증 코드를 위한 Security gates
핵심 통찰: Claude는 대체재가 아니라 증폭기입니다. 생산성을 증폭시키지만, 실수도 증폭시킵니다. 강력한 컨벤션이 없다면 Claude는 스스로 컨벤션을 만들어낼 것이고, 그것들은 일관성이 없을 것입니다. 자동화된 체크가 없다면 Claude의 버그는 인간의 버그보다 더 빠르게 프로덕션에 도달할 것입니다.
이제 결제 버그는 더 이상 발생할 수 없습니다. Claude가 더 똑똑해졌기 때문이 아니라, 파이프라인에서 비동기 race condition에 대한 명시적인 처리를 요구하고 결제 흐름의 적절한 잠금(locking)을 확인하는 게이트를 통해 검증하기 때문입니다.
"AI 네이티브 개발"의 진짜 의미
제가 LemonData를 "AI 네이티브 인프라"라고 부를 때, 이는 기존 제품에 AI 기능을 추가했다는 뜻이 아닙니다. 개발 프로세스 전체가 AI 코딩 파트너와 함께 일하는 현실에 맞춰 형성되었다는 뜻입니다.
저희 문서는 평소보다 더 상세합니다. 인간 팀원은 추론할 수 있는 명시적인 context를 Claude는 필요로 하기 때문입니다. 저희 타입 시스템은 필요 이상으로 엄격합니다. Claude는 조금의 모호함이라도 파고들기 때문입니다. 저희 CI 파이프라인에는 전통적인 코드베이스에서는 과해 보일 수 있는 게이트들이 있습니다. AI가 생성한 버그를 사용자보다 먼저 찾아내기 위해서입니다.
그 결과, 제가 작업해 본 대부분의 코드베이스보다 실제로 더 유지보수가 쉬운 코드베이스가 탄생했습니다. AI가 인간보다 코드를 더 잘 써서가 아니라, AI 지원 개발을 위해 구축하는 과정에서 보통 시니어 개발자의 머릿속에만 들어있던 모든 컨벤션과 체크 사항들을 명시적으로 만들어야 했기 때문입니다.
AI 네이티브 철학에 대해 더 자세히 알고 싶다면 What Is AI Native?를 확인해 보세요.
AI 코딩 어시스턴트로 개발하는 개발자들을 위한 교훈
Claude Code, Cursor 또는 다른 AI 코딩 어시스턴트로 프로젝트를 시작한다면 다음을 기억하세요.
- 첫날부터 CLAUDE.md를 만드세요 — 저처럼 3주나 기다리지 마세요.
- 컨벤션 강제를 자동화하세요 — AI가 규칙을 기억할 것이라고 믿지 마세요.
- AI 코드를 주니어 개발자가 쓴 것처럼 검토하세요 — 빠르고 유능하지만 context가 부족합니다.
- 엣지 케이스를 수동으로 테스트하세요 — AI 생성 테스트는 happy path는 잘 다루지만 race condition은 놓칩니다.
- 처음부터 설정을 중앙 집중화하세요 — 분산 문제는 빠르게 복리로 불어납니다.
- Strict TypeScript를 사용하세요 — 타입 드리프트에 대한 최선의 방어책입니다.
- CI 게이트를 조기에 구축하세요 — 첫 주 안에 그 가치를 증명할 것입니다.
다시 하겠냐고요?
당연합니다. 하지만 3주 차가 아닌 첫날부터 CLAUDE.md를 시작할 것입니다. 그리고 10배의 생산성 향상에는 실수의 결과에 대한 10배의 책임이 따른다는 사실을 기억할 것입니다.
저희가 구축한 플랫폼—300개 이상의 AI 모델, 통합 API, 다중 통화 결제, 13개 언어 국제화—은 전통적인 팀이었다면 몇 달이 걸렸을 것입니다. 저희는 30일 만에 배포했습니다. 버그는 실재했지만, 속도 또한 실재했습니다.
AI 지원 개발은 마법이 아닙니다. 새로운 종류의 엔지니어링 규율입니다. 그리고 모든 규율이 그렇듯, 그 제약 조건을 존중하는 사람에게 보상을 줍니다.
FAQ
개발자 한 명이 정말로 Claude Code로 프로덕션 플랫폼을 구축할 수 있나요?
네, 하지만 주의사항이 있습니다. AI는 놀라운 속도로 코드 생성과 리팩토링을 처리하지만, 여전히 강력한 아키텍처 판단력, 자동화된 품질 게이트, 그리고 모든 것을 세심하게 검토하는 규율이 필요합니다. 10배의 속도는 주의하지 않으면 10배 더 빠른 버그 생성을 의미하기도 합니다.
CLAUDE.md가 무엇인가요?
CLAUDE.md는 AI 코딩 어시스턴트가 context를 파악하기 위해 읽는 프로젝트 수준의 지침 파일입니다. 여기에는 AI가 따라야 할 코딩 컨벤션, 아키텍처 결정 및 제약 조건이 포함됩니다. AI 팀원을 위한 온보딩 문서라고 생각하시면 됩니다.
프로덕션에서 AI 생성 버그를 어떻게 방지하나요?
자동화된 CI 게이트가 필수적입니다: type checking, SSOT audit, enum sync 검증, 도메인별 보안 게이트 등이 있습니다. 핵심은 AI가 생산성과 실수 모두를 증폭시킨다는 점이며, 증폭된 실수를 잡아내기 위해 자동화된 체크가 필요하다는 것입니다.
AI 지원 개발이 결제 및 지불 시스템에 적합한가요?
네, 하지만 각별한 주의가 필요합니다. 결제 코드는 명시적인 race condition 처리, 적절한 잠금, 철저한 엣지 케이스 테스트가 필요합니다. AI 생성 테스트는 happy path를 다루는 경향이 있으므로, 실패 시나리오와 동시 작업은 수동으로 테스트해야 합니다.
LemonData는 단일 API를 통해 300개 이상의 AI 모델에 대한 액세스를 제공합니다. 저희는 AI를 서비스하기 위해 AI로 이를 구축했습니다. 무료로 시작해 보세요 — 신규 사용자에게는 $1의 크레딧이 제공됩니다.
