화요일 새벽 2시, 결제 시스템이 사용자에게 요금을 이중으로 청구하고 있다는 사실을 깨달았습니다. 버그는 이미 6시간 동안 프로덕션 환경에 배포되어 있었습니다. 그날 오후 Claude Code가 결제 대조 logic을 생성했고, 저는 이를 검토하고 테스트한 뒤 배포했습니다. 코드는 완벽해 보였습니다. 모든 테스트를 통과했죠. 하지만 근본적으로 망가져 있었습니다.
이것은 AI 코딩 어시스턴트를 사용하여 274개의 API route, 46개의 database model, 100,000줄 이상의 코드로 LemonData를 구축한 이야기입니다. "AI가 얼마나 생산적인지 보세요"라는 식의 다듬어진 이야기가 아닙니다. 실패와 새벽 3시의 debugging 세션, 그리고 AI 지원 개발이 정말 좋은 아이디어인지 의문을 가졌던 순간들이 담긴 진짜 이야기입니다.
AI 지원 개발의 홍보 문구 vs 현실
AI 코딩 어시스턴트의 홍보 문구는 매혹적입니다. 원하는 것을 설명하면 AI가 코드를 작성하고, 당신은 검토 후 배포하기만 하면 됩니다. 이론적으로는 이제 개발자 한 명이 팀 전체의 업무를 수행할 수 있습니다.
현실은 어떨까요? 처음 2주 동안은 놀라웠습니다. Claude Code는 내 codebase를 이해하고, 완전한 feature를 생성하며, 여러 파일에 걸쳐 refactor를 수행했습니다. 제 경력을 통틀어 그 어느 때보다 빠르게 결과물을 내놓고 있었습니다. issue들을 그렇게 빨리 해결하며 느끼는 도파민은 중독적이었습니다.
그러다 균열이 생기기 시작했습니다.
동일한 function이 세 개의 서로 다른 파일에 약간씩 다른 implementation으로 나타났습니다. configuration 값들이 무작위 위치에 hardcoded되어 있었습니다. package 간에 type definition이 서로 모순되었습니다. codebase는 빠르게 성장하고 있었지만, 동시에 "작동은 하지만 왜 그런지 모르는" 코드의 미로가 되어가고 있었습니다.
그리고 그 결제 버그 말인가요? Claude는 겉보기에는 완벽하게 합리적인 대조 function을 생성했습니다. 하지만 우리의 async 결제 확인 flow에서 발생하는 race condition을 고려하지 못했습니다. 제가 명시적으로 말해주지 않았기 때문에 AI는 그 edge case를 알 방법이 없었고, 부분적으로 AI가 생성한 테스트 suite 역시 이를 잡아내지 못했습니다.
계속해서 발생했던 7가지 패턴
Claude Code로 개발한 지 한 달이 지난 후, 저는 목록을 만들기 시작했습니다. 정확히는 버그 목록이 아니라 패턴 목록이었습니다. 동일한 종류의 실패가 계속 반복되었는데, 이는 Claude의 잘못이라기보다는(적어도 전적으로는 아닙니다), AI가 "내일 작동할 코드"보다는 "지금 당장 작동하는 코드"에 최적화된 결과로 나타나는 예측 가능한 현상이었습니다.
1. 일관성 문제 (The Consistency Problem)
Claude는 작업 중인 파일, 최근에 본 예시, 혹은 단순히 무작위적인 변덕에 따라 동일한 logic을 다르게 구현하곤 했습니다. 어떤 API endpoint는 { data: users }를 반환하고, 다른 endpoint는 { users }를 반환했습니다. 둘 다 작동은 했지만, 서로 일치하지 않았습니다. debugging은 마치 고고학 연구처럼 변해버렸습니다.
2. 복사-붙여넣기 문제 (The Copy-Paste Problem)
코드를 복제하는 것이 더 빠르고 기존 기능을 망가뜨릴 위험이 없는데, AI가 굳이 공통 utility를 만들 이유가 있을까요? 기존 기능과 유사한 새로운 feature를 요청할 때마다, refactor된 공통 솔루션 대신 새로운 implementation을 받게 되었습니다. 3주 후, codebase 여기저기에 5개의 서로 다른 "format currency" function이 흩어져 있었습니다.
3. 타입 드리프트 문제 (The Type Drift Problem)
새로운 status 값이 특정 파일에는 추가되었지만 enum 정의에는 누락되었습니다. 어떤 field는 API response에서는 선택 사항(optional)이지만 frontend type에서는 필수 사항(required)이었습니다. TypeScript가 이 중 일부를 잡아냈지만, type은 기술적으로 맞더라도 logic상 일관성이 없는 semantic 불일치는 잡아내지 못했습니다.
4. 설정 분산 문제 (The Configuration Scatter Problem)
database URL, API key, feature flag, rate limit 등이 현재 작업에 편리한 곳이라면 어디든 위치하게 되었습니다. 때로는 environment variables에, 때로는 config 파일에, 때로는 hardcoded된 상태로 말이죠. 어떤 값이 정의된 모든 위치를 찾는 것은 보물찾기가 되었습니다.
5. 테스트 커버리지의 착각 (The Test Coverage Illusion)
AI가 생성한 테스트는 happy path를 철저하게 테스트하는 경향이 있지만, edge case는 완전히 놓치곤 합니다. 결제 버그가 완벽한 예시입니다. 테스트 suite는 일반적인 결제 flow를 아름답게 커버했습니다. 하지만 두 개의 결제 확인이 동일한 millisecond 내에 도착했을 때 어떤 일이 벌어지는지는 전혀 테스트하지 않았습니다.
6. 침묵하는 실패 문제 (The Silent Failure Problem)
Claude는 exception을 삼켜버리는 catch (error) { console.log(error) } 블록을 추가하곤 했습니다. 개발 단계에서는 에러가 console에 나타나므로 괜찮아 보였습니다. 하지만 프로덕션 환경에서는 치명적인 실패가 조용히 로깅만 되고 잊혀졌습니다.
7. 문서화의 공백 (The Documentation Gap)
Claude는 훌륭한 코드 주석을 작성합니다. 하지만 아키텍처 문서는 형편없습니다. function이 무엇을 하는지는 설명할 수 있지만, 시스템이 왜 그렇게 구조화되었는지, 또는 특정 설계 결정을 내리게 된 제약 조건이 무엇인지는 설명하지 못합니다.
CLAUDE.md 솔루션
전환점은 3주 차에 찾아왔습니다. 프로젝트 root에 Claude가 알아야 할 모든 컨벤션, 제약 조건, 아키텍처 결정을 담은 CLAUDE.md 파일을 만들었습니다.
인간을 위한 문서가 아니라, 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 gate
우리는 전통적인 codebase에서는 편집증적으로 보일 수 있는 gate를 가진 CI pipeline을 구축했습니다. 이는 사용자가 발견하기 전에 AI가 생성한 버그를 잡기 위해 존재합니다.
- 전체 monorepo에 대한 Type checking
- 중복 구현이 없는지 확인하는 SSOT audit
- database enum과 TypeScript enum 간의 sync 체크
- API response format validation
- 결제, 권한, authentication 코드에 대한 보안 gate
핵심 통찰은 간단합니다. Claude는 대체재가 아니라 증폭기(amplifier)입니다. 당신의 생산성을 증폭시키지만, 당신의 실수도 증폭시킵니다. 강력한 컨벤션이 없다면 Claude는 스스로 컨벤션을 만들어낼 것이고, 그것들은 일관성이 없을 것입니다. 자동화된 체크가 없다면 Claude의 버그는 인간의 버그보다 훨씬 빠르게 프로덕션에 도달할 것입니다.
이제 결제 버그는 더 이상 발생할 수 없습니다. Claude가 더 똑똑해졌기 때문이 아니라, pipeline에서 이제 async race condition에 대한 명시적인 처리를 요구하고, 결제 flow에서 적절한 locking을 확인하는 gate를 통해 검증하기 때문입니다.
"AI Native 개발"의 진정한 의미
LemonData가 "AI Native Infrastructure"라고 말할 때, 이는 단순히 기존 제품에 AI 기능을 추가했다는 뜻이 아닙니다. 개발 프로세스 전체가 AI 코딩 파트너와 함께 일하는 현실에 맞춰 형성되었다는 뜻입니다.
우리의 문서는 인간 동료라면 추론할 수 있는 명시적인 context를 Claude가 필요로 하기 때문에 평소보다 더 상세합니다. 우리의 type 시스템은 Claude가 어떤 모호함이라도 이용할 것이기 때문에 필요 이상으로 엄격합니다. 우리의 CI pipeline은 사용자가 발견하기 전에 AI 생성 버그를 잡기 위해 전통적인 codebase에서는 편집증적으로 보일 법한 gate들을 가지고 있습니다.
그 결과, 제가 작업해 본 대부분의 코드보다 실제로 더 유지보수가 쉬운 codebase가 탄생했습니다. AI가 인간보다 코드를 더 잘 써서가 아니라, AI 지원 개발을 위해 구축하는 과정에서 평소 시니어 개발자들의 머릿속에만 들어있던 모든 컨벤션과 체크 사항들을 명시적으로 만들어야 했기 때문입니다.
AI Native가 철학적으로 무엇을 의미하는지에 대해 더 자세히 알고 싶다면 What Is AI Native?를 참조하세요.
실질적으로 "어떻게 적용하기 시작할까?"라는 측면이 궁금하다면, agent-first API design guide와 migration guide를 읽어보시는 것을 추천합니다. 하나는 API의 형태를 설명하고, 다른 하나는 workflow가 model switching에 맞게 설계되었을 때 팀이 얼마나 빨리 방향을 전환할 수 있는지 보여줍니다.
AI 코딩 어시스턴트로 개발하는 개발자를 위한 교훈
Claude Code, Cursor 또는 다른 AI 코딩 어시스턴트로 프로젝트를 시작한다면 다음을 기억하세요.
- 저처럼 3주 차가 아니라, 첫날에
CLAUDE.md를 만드세요. - 컨벤션 준수를 자동화하세요. AI가 규칙을 기억할 것이라고 믿지 마세요.
- AI 코드를 junior developer가 작성한 것처럼 검토하세요. 빠르고 유능하지만 context가 부족합니다.
- edge case는 수동으로 테스트하세요. AI 생성 테스트는 happy path는 커버하지만 race condition은 놓칩니다.
- 처음부터 설정을 중앙 집중화하세요. 분산 문제는 빠르게 복리로 불어납니다.
- 엄격한 TypeScript를 사용하세요. type drift에 대한 최선의 방어책입니다.
- CI gate를 조기에 구축하세요. 첫 주 안에 그 가치를 증명할 것입니다.
다시 하겠냐고요?
당연하죠. 하지만 3주 차가 아닌 첫날부터 CLAUDE.md와 함께 시작할 것입니다. 그리고 10배의 생산성 향상에는 실수의 결과 또한 10배로 커진다는 사실을 기억할 것입니다.
우리가 구축한 플랫폼, 300개 이상의 AI 모델, 통합 API, 다중 통화 결제, 13개 언어 국제화는 전통적인 팀이었다면 몇 달이 걸렸을 일입니다. 우리는 이를 30일 만에 배포했습니다. 버그는 실재했지만, 속도 또한 실재했습니다.
AI 지원 개발은 마법이 아닙니다. 그것은 새로운 종류의 엔지니어링 규율(discipline)입니다. 그리고 모든 규율이 그렇듯, 그 제약 조건을 존중하는 사람에게 보상을 줍니다.
FAQ
개발자 한 명이 정말로 Claude Code로 프로덕션 플랫폼을 구축할 수 있나요?
네, 하지만 주의사항이 있습니다. AI는 놀라운 속도로 코드 생성과 refactoring을 처리하지만, 여전히 강력한 아키텍처적 판단력, 자동화된 품질 gate, 그리고 모든 것을 세심하게 검토하는 규율이 필요합니다. 10배의 속도에는 주의하지 않을 경우 10배 더 빠른 버그 발생도 포함됩니다.
CLAUDE.md가 무엇인가요?
CLAUDE.md는 AI 코딩 어시스턴트가 context를 파악하기 위해 읽는 프로젝트 수준의 지침 파일입니다. 여기에는 AI가 따라야 할 코딩 컨벤션, 아키텍처 결정 사항, 제약 조건 등이 포함됩니다. AI 팀원을 위한 온보딩 문서라고 생각하시면 됩니다.
프로덕션에서 AI 생성 버그를 어떻게 방지하나요?
자동화된 CI gate가 필수적입니다. Type checking, SSOT audit, enum sync 검증, 도메인별 보안 gate 등이 필요합니다. 핵심은 AI가 생산성과 실수 모두를 증폭시키므로, 증폭된 실수를 잡아내기 위한 자동화된 체크가 필요하다는 점입니다.
AI 지원 개발이 결제 및 지불 시스템에 적합한가요?
네, 하지만 각별한 주의가 필요합니다. 결제 코드는 명시적인 race condition 처리, 적절한 locking, 철저한 edge case 테스트가 필요합니다. AI 생성 테스트는 happy path를 커버하는 경향이 있으므로, 실패 시나리오와 concurrent 작업을 수동으로 테스트해야 합니다.
LemonData는 단일 API를 통해 300개 이상의 AI 모델에 대한 액세스를 제공합니다. 무료로 시작하고 $1의 크레딧으로 플랫폼을 테스트해 보세요.
