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

결론부터: Claude Code + Flutter 조합이면 Flutter 경험이 없는 비개발자도 작은 범위의 iOS 앱을 App Store까지 낼 수 있다. 단, CLAUDE.md 규칙 설계와 실기기 디버깅, 범위 결정은 사람이 해야 한다.

Flutter 경험 0에서 Claude Code로 앱 만들기에 도전했습니다. 결과는 GentleDo — 에너지 기반 태스크 관리 앱, 2026-04-22 App Store 출시. 제출 후 심사 승인까지 2일, 본격 개발은 약 2주가 걸렸습니다. Claude Code와 함께 작업한 과정을 바탕으로 기술 스택 선택 기준·CLAUDE.md 작성법·실전 문제·비용을 정리합니다.

Claude Code란?

Claude Code는 터미널에서 실행되는 AI 코딩 에이전트입니다. 필요한 파일을 직접 찾아 읽고, 여러 파일을 수정하고, 명령을 실행합니다(권한 승인 후).

요금 출처: Claude, Cursor 공식 페이지.

작성자가 쓰면서 느낀 Claude Code의 강점은 기능 단위로 일을 맡길 수 있다는 점입니다. "이 기능을 만들자"는 요청에서 시작해 관련 파일 여러 개를 수정하고 테스트까지 돌립니다(개인 경험).

두 도구의 작업 방식 차이는 Claude Code vs Cursor 비교에서 정리했습니다.

(캡션) Claude Code 세션 흐름을 재구성한 예시 화면 — 실제 화면 캡처가 아닙니다

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

AI와 함께 앱을 만들 때 언어·프레임워크 선택이 중요합니다. 작성자가 검토한 결과, 비개발자 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 — 저장하면 실행 중인 앱에 바로 반영됩니다. AI가 생성한 코드를 즉시 눈으로 확인할 수 있어 피드백 루프가 짧습니다.

Flutter의 실제 단점 2가지

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

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

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

핵심: 코드 초안은 대부분 Claude Code가 작성했고, 작성자가 한 일은 (1) 요구사항 정의 (2) 실기기 검증 (3) 범위와 우선순위 결정이었습니다.

(캡션) GentleDo 1.0.0 개발 타임라인 — 2026-04-22 App Store 승인

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주 만에 MVP"가 가능했던 것은 로컬 전용·서버 없음·수익화 없음이라는 강한 범위 제약 덕분입니다. 범위가 커지면 시간은 훨씬 더 늘어납니다.

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

작성자가 실제로 쓴 조합입니다.

더 넓은 AI 도구 맵은 2026 AI 도구 가이드에서 확인할 수 있습니다. 모델 선택은 Claude Sonnet 4 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는 어떤 요금제로 시작해야 하나요?

Claude Code는 Claude 무료 플랜에는 포함되지 않고 Pro(월 20달러, 연간 결제 시 월 17달러) 이상 유료 플랜에 포함됩니다. 작은 앱은 Pro로 시작해 보고, 사용량 한도에 자주 걸리면 월 100달러부터인 Max를 검토하세요. API 키로 쓰면 토큰 사용량만큼 과금됩니다.

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

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

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

심사 기간은 앱의 성격과 시기에 따라 달라지므로 일정에 여유를 두세요. GentleDo는 제출 2일 만에 승인됐는데, 로컬 전용·계정 없음·광고 없음이라 확인할 항목이 적었던 것이 영향을 줬을 수 있습니다(작성자의 추정). Google Play는 신규 개인 개발자 계정에 비공개 테스트 요건이 있으니 출시 전에 확인하세요.

GentleDo 직접 써볼 수 있나요?

네. App Store에서 "GentleDo"를 검색하면 받을 수 있습니다. 다른 플랫폼 출시 현황과 시리즈 맥락은 GentleLab 랜딩페이지에서 확인할 수 있고, 두 링크 모두 글 마지막에 정리해 뒀습니다.

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

작성자의 경험을 한 줄로 요약하면 — "혼자서는 못 만들었을 앱"을 "혼자서도 만들 수 있게" 해 주는 도구였습니다. 대신 CLAUDE.md 규칙 설계·실기기 검증·스코프 결정은 여전히 사람의 영역입니다. AI가 커버하지 못하는 부분을 이해하고 시작해야 출시까지 헤매는 시간이 줄어듭니다.

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

이 프로젝트가 Claude Code 활용의 어디쯤에 해당하는지는 AI 코딩 완벽 가이드 2026에서 정리한 도구 역할 중 "터미널 에이전트로 앱 만들기"에 해당합니다.