Claude Code + Flutter로 앱 만들기 실전 가이드 — GentleDo 2주 출시기

결론부터: Claude Code + Flutter 조합이면 Flutter 경험 0인 비개발자도 2주 만에 iOS 앱을 App Store에 출시할 수 있다. 단, CLAUDE.md 규칙 설계와 실기기 디버깅은 사람이 해야 한다.

Flutter 경험 0에서 Claude Code로 앱 만들기에 도전했습니다. 결과는 GentleDo — 에너지 기반 태스크 관리 앱, 2026-04-22 App Store 출시. 제출 후 심사 승인까지 2일, 전체 개발은 약 2주가 걸렸습니다. 3주간 매일 Claude Code와 페어링한 실사용 기준으로, 기술 스택 선택 기준·CLAUDE.md 작성법·실전 삽질·비용까지 공개합니다.

Claude Code란?

Claude Code는 터미널에서 실행되는 AI 코딩 에이전트입니다. ChatGPT·Cursor와 달리 파일을 직접 읽고·쓰고·커밋하며, 프로젝트 전체를 컨텍스트로 들고 작업합니다.

실제로 쓰면서 체감한 Claude Code의 강점은 "커밋 전체를 조율하는 감각" 입니다. Cursor는 블록 단위 제안에 강하고, ChatGPT는 아이디어 브레인스토밍에 강한데, Claude Code는 "이 기능을 만들자" 한 문장에서 시작해서 파일 5개를 자연스럽게 수정하고 테스트까지 돌립니다.

Claude Code vs Cursor 14일 교차 테스트에서 두 도구의 사용 감각 차이를 자세히 정리했습니다.

(캡션) Claude Code가 5개 파일을 동시에 수정하며 커밋까지 만드는 실제 세션

비개발자에게 Flutter가 맞는 이유는?

AI와 함께 앱을 만들 때 언어·프레임워크 선택이 성패를 가릅니다. 3주간 검토한 결과, 비개발자 1인에게는 Flutter가 가장 현실적이었습니다.

후보 비교 — Flutter vs React Native vs SwiftUI vs Kotlin

Flutter를 고른 세 가지 이유

1. 하나의 코드베이스로 iOS + Android + macOS — 1인 개발자에게 SwiftUI × Jetpack Compose 병렬 학습은 불가능합니다.
2. Dart의 정적 타입 + null 안정성 — AI 페어 프로그래밍에서 타입이 명시될수록 AI 제안 품질이 올라갑니다. JS보다 Dart가 실패 비용이 적었습니다.
3. Hot Reload 속도 — 저장 후 0.5초 내 반영. AI가 생성한 코드를 즉시 눈으로 확인할 수 있어 피드백 루프가 짧습니다.

Flutter의 실제 단점 2가지

• iOS 네이티브 기능 접근이 패키지 품질에 의존 — path_provider_foundation, home_widget 같은 패키지의 소수 버전이 특정 iOS 기기에서 크래시를 내는 경우가 있습니다. 문제 추적이 어렵습니다.
• Material 디자인 냄새 — 기본 위젯을 그대로 쓰면 "Flutter로 만든 앱"이 티가 납니다. iOS 사용자가 위화감을 느끼지 않게 하려면 커스텀 테마·위젯 작업이 필수입니다.

GentleDo 개발 2주 타임라인 — 비개발자 실제 경로

GentleDo는 에너지 기반 태스크 관리 앱입니다. Flutter + Drift + Riverpod 스택으로 2주 만에 App Store까지 갔습니다.

핵심 인사이트: 일주일간 파일 숫자는 약 120개, 커밋 수는 40개 이상이었습니다. 이 중 90% 이상이 Claude Code가 초안 작성했고, 제가 한 일은 (1) 요구사항 정의 (2) 실기기 검증 (3) 결정적 판단이었습니다.

(캡션) 제출 2일 만에 승인된 GentleDo 1.0.0 — 2026-04-22

CLAUDE.md 작성법이 핵심인 이유

Claude Code를 제대로 쓰려면 프로젝트 루트의 CLAUDE.md 파일이 전부입니다. 이 한 문서가 모든 대화의 컨텍스트가 됩니다.

(캡션) 실제로 쓴 CLAUDE.md — 5개 섹션 87줄로 슬림화

CLAUDE.md에 반드시 포함해야 할 5개 섹션

## 1. 역할 정의
너는 이 프로젝트의 시니어 Flutter 개발자다.
- 요청하지 않은 기능을 임의로 추가하지 않는다
- 한 커밋당 3~5개 파일만 수정한다
- 에러 시 원인과 해결책을 함께 제시한다
 
## 2. 기술 스택
| 레이어 | 선택 |
| --- | --- |
| Framework | Flutter 3.x |
| DB | Drift 2.x, schemaVersion = 3 |
| State | Riverpod 2.x (Provider 금지) |
 
## 3. 아키텍처 — 단방향 의존성
app → features → shared → data → core
 
## 4. 절대 하지 말 것
- 앱에 적색(Red) 사용 금지
- UI 문자열 하드코딩 금지 (ARB 경유 필수)
- Phase 1에서 서버·AI API 추가 금지
- Material Icons 사용 금지 (lucide_icons만)
 
## 5. 참조 문서
- docs/PROJECT_BRIEF.md — 기능 스펙
- docs/CONVENTIONS.md — 디자인·코드 규칙

이 5개 섹션의 효과: "Material Icons 쓰지 마"를 매번 말하지 않아도 됩니다. "Red 컬러 쓰지 마"도 마찬가지. 비슷한 규칙 10~20개를 문서화하면 같은 지시를 두 번 할 일이 사라집니다.

Claude MCP 활용법에서 다룬 것처럼 MCP를 같이 쓰면 CLAUDE.md가 외부 시스템(Obsidian·GitHub 등)까지 컨텍스트로 끌어올 수 있습니다.

반대로, CLAUDE.md에 넣으면 안 되는 것

• 자주 바뀌는 태스크 목록 — 문서가 금방 오래됩니다. TODO는 GitHub Issues에.
• 비밀번호·API 키 — .env로 분리.
• 모든 컨벤션 설명 — 너무 길면 AI가 중요 규칙을 놓칩니다. 핵심 5~10개만.

실전 삽질 3가지 — AI가 풀지 못한 것들

정직하게 기록합니다. Claude Code로 해결되지 않은 3건입니다.

1) path_provider_foundation 2.6.0 FFI 크래시

증상: build 7까지 시뮬레이터는 정상. 실기기 TestFlight 빌드에서 앱 기동 직후 크래시.

AI의 시도: 크래시 로그를 주면 "권한 문제 같다"는 추측만 반복. 패키지 이슈 트래커까지 가지 못함.

사람의 해결: GitHub 이슈 검색 → 2.6.0의 알려진 버그 확인 → dependency_overrides로 2.4.4 고정.

dependency_overrides:
  path_provider_foundation: 2.4.4

교훈: 패키지 버전 이슈는 여전히 구글링이 빠릅니다. AI에게 맡기면 겉도는 답변만 받기 쉽습니다.

2) iPad 스크린샷 요구 — TARGETED_DEVICE_FAMILY

증상: App Store Connect 제출 시 "iPad 13-inch display screenshots are required." 에러.

AI의 시도: 스크린샷 크기 가이드 설명은 정확. 단, "iPad 타깃 자체를 제거해서 회피"라는 해결책은 먼저 제시하지 않음.

사람의 해결: ios/Runner.xcodeproj/project.pbxproj에서 TARGETED_DEVICE_FAMILY = "1,2" → "1"로 변경.

교훈: AI는 표준 경로에 강하고, 우회 해결책 제안은 약합니다. MVP에서 "이 기능을 빼자"는 결정은 사람이 해야 합니다.

3) DB 마이그레이션 실기기 실패

증상: v2 → v3 마이그레이션이 dev 기기에선 통과, 일부 테스터 기기에선 컬럼 기본값이 NULL로 들어가면서 크래시.

AI의 시도: 마이그레이션 코드 자체는 정상. AI는 "기본값이 명시되어 있다"고 판단.

사람의 해결: ALTER TABLE ... ADD COLUMN ... DEFAULT ... 구문을 실기기 최소 3대에서 검증. ALTER 문의 DEFAULT가 기존 레코드에 소급 적용되지 않는 SQLite 동작을 확인.

교훈: 실기기 테스트 매트릭스는 AI가 대체할 수 없습니다. 최소 3개 기기, OS 2개 버전.

비용·시간 정산 — 솔직한 숫자

2주간의 실제 투입을 공개합니다.

시급 환산 관점: 월 20만 원 짜리 외주로 Flutter 앱을 맡기면 절대 나올 수 없는 속도입니다. 단, "2주 만에 MVP"는 로컬 전용·서버 없음·수익화 없음 같은 강한 스코프 제약이 있었기 때문입니다. 스코프가 커지면 시간도 제곱으로 늘어납니다.

비개발자에게 추천하는 AI 코딩 스택

3주 실전 후 정리한 조합입니다.

더 넓은 AI 도구 맵은 2026 AI 도구 완벽 가이드에서 전체 스택을 확인할 수 있습니다. 모델 선택은 Claude 4 Sonnet vs GPT-4o 비교를, 모바일 자동화는 Apple 단축어로 만드는 AI 자동화 5가지를, 1인 개발자 전체 스택은 1인 개발자 자동화 스택 10가지를 참고하세요.

이 가이드를 누구에게 추천하나?

자주 묻는 질문 (FAQ)

Flutter를 배운 적이 없어도 Claude Code로 앱을 만들 수 있나요?

가능합니다. 단, Dart/Flutter의 용어 20개 정도는 읽을 수 있어야 합니다. "Widget", "State", "Provider", "Build Context" 수준. 이것 없이는 AI가 출력한 코드가 맞는지 판단이 안 됩니다. 첫 3일은 Flutter 공식 튜토리얼을 가볍게 따라가는 걸 추천합니다.

Claude Code Max 구독을 언제 시작해야 하나요?

프로젝트를 시작하는 날. 무료 티어(Sonnet 제한)로는 1주일 안에 한도를 소진합니다. Max $20/월 기준으로 중형 프로젝트까지 커버됩니다. 월말 한도 초과가 잦으면 상위 플랜을 검토합니다.

서버가 필요한 앱도 만들 수 있나요?

가능하지만 난이도가 급상승합니다. GentleDo처럼 로컬 전용이면 실수 비용이 작지만, 서버 붙는 순간 인증·보안·배포 파이프라인이 동시에 붙습니다. 첫 앱은 로컬 전용 Phase 1로 시작하고, 두 번째 앱부터 Supabase 같은 BaaS로 확장하는 것을 권합니다.

앱 심사는 얼마나 걸리나요?

iOS 기준 첫 심사는 통상 3~7일. GentleDo는 2일에 통과했는데, 로컬 전용·계정 없음·광고 없음 — 심사관이 체크할 항목이 적은 특성이 영향을 준 것 같습니다. Android Play Console은 별도로 더 엄격해질 수 있습니다.

GentleDo 직접 써볼 수 있나요?

네. 현재 iOS 전용으로 다운로드 가능합니다 (App Store에서 "GentleDo" 검색). 시리즈 맥락은 GentleLab 랜딩페이지에서 확인할 수 있고, 두 링크 모두 글 마지막에 정리해뒀습니다. Android는 iOS 1개월 피드백 수집 후 출시 예정입니다.

마무리 — Claude Code + Flutter로 바뀐 것, 바뀌지 않은 것

3주 실사용 결과를 한 줄로 요약하면 — "혼자서는 못 만들었을 앱"을 "혼자서도 만들 수 있게" 해주는 도구입니다. 대신 CLAUDE.md 규칙 설계·실기기 검증·스코프 결정은 여전히 사람의 영역입니다. AI가 커버하지 못하는 구멍을 이해하고 시작해야 2주 안에 App Store까지 갈 수 있습니다.

직접 만든 결과물이 궁금하면 — App Store에서 GentleDo 받기 (iOS 전용). 시리즈 맥락은 GentleLab 랜딩페이지에서 확인할 수 있습니다.