Claude Code를 도입한 첫날 기록. 하네스 템플릿을 v2.0까지 끌어올리고, 바로 DiveBase 코드베이스에 적용해서 쌓인 기술 부채를 하루 만에 정리했다.
시작 전: 왜 지금 Claude Code인가
DiveBase는 스쿠버/프리다이빙 로그를 기록하는 Flutter 앱이다. 3월 중순에 MVP를 찍고 TestFlight까지 올렸지만, 빠르게 만들면서 쌓인 기술 부채가 계속 눈에 밟혔다. .env가 앱 번들에 포함되어 있고, Navigator.push와 GoRouter가 혼재하고, 에러 처리 없이 Supabase를 호출하는 곳이 있고, 1,000줄 넘는 위젯 파일이 있었다.
AI를 쓴다면 단순 코드 생성보다 "계획 → 구현 → 검증"을 구조화해서 쓰고 싶었다. 그래서 먼저 하네스 템플릿부터 만들었다.
1부: 하네스 템플릿 v2.0
Claude Code 마스터 가이드(583p)를 기반으로 초기 템플릿을 만들고, 빠르게 개선을 반복했다. 이날 가장 핵심이 된 건 3-Role Workflow다.
Planner → Developer → Reviewer- Planner: 태스크 계획 + Epic 분해
- Developer: 구현만 담당 (커밋 없음)
- Reviewer: 검토 후 APPROVE 시에만 커밋 + 푸시
Developer는 코드만 작성하고, Reviewer가 APPROVE할 때만 커밋+푸시한다. 사람이 셀프 리뷰하면 놓치기 쉬운 것들 — dead code, 잔존하는 직접 호출 — 을 Reviewer 단계에서 잡아내는 구조다.
문서는 전부 영어로 전환했다. 새 Claude 세션마다 한국어를 해석하는 데 소모되는 토큰이 무시할 수 없어서다. 인간이 읽는 README.md만 한국어로 남겼다.
세션 간 컨텍스트 유실 문제는 두 가지 장치로 해결했다.
- carry-over 필드: Reviewer가 발견한 이슈를 다음 Planner에게 명시적으로 전달
- decision-log: 과거 의사결정을 기록해두어 같은 논의를 반복하지 않도록
2부: DiveBase에 바로 적용
템플릿이 생기자마자 DiveBase 코드베이스에 던져봤다. 세션 시작 시점에 Claude가 분석한 점수는 이랬다.
| 영역 | 점수 | 비고 |
|---|---|---|
| 디자인 시스템 | 9/10 | 토큰 중앙화 우수 |
| Feature 구조 | 8/10 | Home/Logs 우수, Auth/MyPage 미흡 |
| Riverpod 패턴 | 7/10 | — |
| 데이터 계층 | 6/10 | 일관성 부족 |
| 보안 | 5/10 | .env 번들 포함 |
| 테스트 가능성 | 4/10 | — |
우선순위를 P0/P1으로 나눠서 Task를 쳐냈다.
P0 — 보안 및 필수 수정
Task 1: .env 앱 번들 포함 제거
flutter_dotenv 의존성을 제거하고 --dart-define 방식으로 전환했다. APK를 풀면 Supabase 키가 그대로 노출되는 상태였다.
Task 2: 불필요 파일 정리 (~38MB)
Figma export JSON 22개, 디버깅 로그, 빈 디렉토리 등을 정리. .gitignore에 패턴도 추가했다.
Task 3: HomeScubaRepository 에러 처리
Supabase 호출 4곳에 on PostgrestException catch + debugPrint를 추가. 기존엔 에러가 나면 그냥 크래시했다.
Task 4: Navigator.push → GoRouter 통일
5곳 전부 context.push()로 전환. 두 방식이 혼재하면 딥링크나 뒤로가기에서 문제가 생긴다.
P1 — 구조 개선
Task 5: MyPage → ProfileRepository 분리
MyPage에서 Supabase를 직접 호출하고 있었다. ProfileRepository를 만들어 Home/Logs와 동일한 Repository 패턴으로 통일했다.
Task 6: Auth feature 레이어 추가
AuthRepository + AuthProviders를 추가하고 직접 호출을 제거했다. Reviewer가 dead code와 Supabase 직접 호출 잔존을 추가로 잡아냈다.
Task 7: 대형 파일 분리
총 2,186줄 → 790줄. 3개 파일을 8개로 추출. Reviewer 승인은 다음 세션으로 넘겼다.
| 파일 | Before | After |
|---|---|---|
dive_log_detail_screen.dart | 1,084줄 | 352줄 |
home_page.dart | 626줄 | 211줄 |
step1_basic_info.dart | 476줄 | 227줄 |
회고
3-Role Workflow가 핵심이었다. Task 6 리뷰에서 Reviewer가 dead code와 Supabase 직접 호출 잔존을 잡아낸 게 인상적이었다. 사람이 셀프 리뷰하면 놓치기 쉬운 부분이다.
보안은 MVP에서도 미루면 안 된다. .env가 번들에 포함된 건 "나중에 고치지"로 넘겼던 전형적인 케이스다. TestFlight에 올린 순간 이미 외부에 노출된 거나 마찬가지였다. 다행히 anon key라 피해는 없었지만, 습관이 되면 위험하다.
패턴이 잡혀 있으면 확산이 빠르다. Task 5, 6은 새 파일 생성 + 기존 코드 수정이라 조금 더 걸렸지만, 이미 Home/Logs에 Repository 패턴이 있어서 그걸 따라가면 됐다. 구조를 먼저 잡아두는 게 나중에 속도를 만든다.
다음에 할 것: Task 7 Reviewer 승인 마무리, 하네스 템플릿 실전 피드백 수집, Epic 플래닝 워크플로우 실전 테스트.
