백엔드 개발자의 End-to-End 개발기 with. Claude Code

대 클로드 코드 시대를 맞아, 관심있던 주제의 사이드 프로젝트를 혼자 개발해보기로 했다.

기획, 디자인, FE, BE, 인프라.. 리얼 End-to-End로!

클코와 함께 한 달 정도 작업했다. 결론부터 말하면 — 어렵지 않았다.

잘 아는 쪽에서는 AI가 손발이 됐고, 모르는 쪽에서는 AI가 가이드가 됐다. 두 경우 모두 내가 한 건 디렉팅이었다.

 

바이브 코딩이라고들 하지만, 실제로 해보니 "바이브"으로만 되는 건 아니었다. 체계가 있어야 했다.

한달동안 클로드와 지지고 볶으며 작업했던 방식 및 꾸르팁들을 소개하려 한다.

---

1. 화면 먼저, 서버는 나중에

나는 보통 개발할 때에 API를 만들고, 클라이언트를 붙인다. 백엔드 개발자로서 어쩌면 당연한지도 모르겠다.

하지만 클로드 코드와 일하면서는 화면부터 만들었다. 

Flutter로 홈 화면, 상세 화면, 검색 화면을 먼저 그렸다.

화면을 만들다 보면 "여기서 카드 목록이 필요하네", "여기서 카테고리별 통계가 필요하네" — 필요한 API가 자연스럽게 드러난다.

처음에는 매번 "이 화면에 필요한 API를 API_SPECIFICATION.md에 정리해줘"라고 말했다.

그런데 반복되길래 아예 CLAUDE.md에 룰로 넣었다:

## 클라이언트에서 API가 필요할 때
- 서버 API가 필요한 기능을 구현할 때:
  1. 필요한 엔드포인트를 API_SPECIFICATION.md에 먼저 추가
  2. 클라이언트에서는 mock 데이터로 대체하여 화면이 동작하게 구현
  3. 서버 구현은 별도로 진행
- 존재하지 않는 API를 직접 호출하는 코드를 작성하지 말 것

이 룰 하나로, Claude가 화면을 구현하다가 API가 필요하면 자동으로 명세에 추가하고 mock으로 대체한다.

매번 말할 필요가 없다. 반복되는 지시는 룰로 만들어라 — 이게 CLAUDE.md의 핵심 활용법이다.

mock으로 화면을 돌리다 보면 "이 데이터 구조가 화면에 맞지 않네"라는 걸 발견한다. 서버가 아직 없으니 명세만 고치면 된다.

명세가 굳으면, 서버를 짠다

화면이 완성되고 mock으로 충분히 검증되면, 그때 서버를 짠다. API_SPECIFICATION.md는 이미 완성되어 있다.

Claude에게 "이 스펙대로 구현해"라고 하면 된다.

서버 코드는 내 영역이니까 결과물을 보고 바로 판단할 수 있다. "이 sealed class 구조가 맞는지", "예외 처리가 빠졌는지", "트랜잭션 범위가 적절한지". AI가 짠 코드를 리뷰할 수 있으니까 안심하고 맡긴다.

화면 구현 → API가 드러남 → Claude가 API 명세 작성
→ mock으로 화면 검증 → 명세대로 서버 구현

이렇게 하면 "쓸모없는 API"를 만들 일이 없다. 화면이 필요로 하는 것만 만든다.

---

2. AI에게 "느낌"을 전달하는 법

문제: 기능은 맞는데, 느낌이 아니다

Flutter를 활용하여 개발하는 것과, UI를 "잘" 만드는 건 다른 얘기다.

처음 Claude에게 "홈 화면 만들어줘"라고 했을 때 기능적으로는 맞았지만 게시판 같았다. 텍스트 나열, flat한 배경, 시각적 계층 없음.

AI에게 "어떻게 만들어"가 아니라 "어떤 느낌이어야 해"를 전달해야 했다.

해결: design-system.md

프로젝트 안에 docs/design-system.md 파일을 만들었다. 여기에 넣은 건 코드가 아니라 취향이다:

## 디자인 철학

### 레퍼런스
삼성카드 monimo, 스픽(Speak)

### 원칙
1. 미니멀하고 깔끔하게 — 요소가 적을수록 좋다.
2. 단, depth는 유지 — 미니멀 ≠ flat. 그림자, 레이어, 시각적 계층.
3. Vivid Spectrum 그라데이션 — 블루 → 퍼플 → 핑크.
4. 텍스트 중심 — 정보 전달은 타이포그래피로.

### 하지 말 것
- 텍스트 나열식 리스트 (게시판처럼 보임)
- 시각 요소를 전부 제거한 flat 디자인
- 일정 중심으로 치우친 홈 화면
- 카드 내부에 아이콘 넣기

### 판단 기준
1. monimo/스픽 앱에 이 화면을 넣어도 어색하지 않은가?
2. depth가 느껴지는가?
3. "사진 찍기" 행동이 눈에 띄는가?

핵심은 "하지 말 것"과 "판단 기준" 섹션이다.

AI는 "이렇게 해"보다 "이건 하지 마"를 더 정확하게 따른다.

그리고 "monimo/스픽에 넣어도 어색하지 않은가?"라는 질문은 Claude가 레퍼런스 앱과 비교하면서 스스로 검증하게 만든다.

디자인 시스템은 진화한다

이 문서는 한 번 쓰고 끝이 아니다. 처음에는 인디고 블루 단색이었는데, 실제 앱을 쓰다 보니 밋밋했다.

그래서 Vivid Spectrum 그라데이션(블루→퍼플→핑크)으로 바꾸고, 글래스모피즘 카드를 도입했다.

중요한 건 코드를 먼저 바꾸지 않았다는 것. design-system.md의 원칙을 먼저 업데이트하고, 그 원칙에 맞춰 구현했다.

design-system.md는 "느낌"을 전달하는 문서였다.

 

그런데 프로젝트에는 느낌 말고도 AI에게 전달해야 할 것들이 있다 — 작업 순서, 프로세스, 하지 말아야 할 실수. 이걸 담는 곳이 CLAUDE.md다.

---

3. CLAUDE.md — AI에게 맥락을 주는 법

Claude Code에는 CLAUDE.md라는 파일이 있다. 프로젝트 루트에 넣으면 매 세션마다 자동으로 읽힌다. 프로젝트의 규칙서 같은 것이다.

처음: 모든 걸 다 넣었다

처음에는 기술 스택, 아키텍처 패턴, 파일 구조를 상세하게 넣었다:

## 클라이언트 (Flutter)
- 상태관리: StatefulWidget + setState
- 아키텍처: Screen → Service(singleton) → BaseApiClient
- 주요 파일: home_screen.dart, card_service.dart, ...

## 서버 (Spring Boot + Kotlin)
- 4계층: ui → application → domain → infrastructure
- Card 도메인: sealed interface (GeneralCard, EventCard)
- JWT 인증, FCM 푸시, 토큰 블랙리스트, 레이트 리미팅

## 인프라
- Docker + Railway 배포
- PaddleOCR + Flask OCR 서버

그런데 돌아보니, 이건 Claude가 pubspec.yaml이나 build.gradle.kts를 읽으면 바로 아는 정보다.

폴더 구조를 탐색하면 아키텍처도 파악한다. 넣어봐야 컨텍스트만 낭비한다. 전부 뺐다.

최종본

# Glip

사진을 찍으면 AI가 정보를 분석·분류·저장하고,
필요할 때 검색하는 앱. 

## UI 작업 시
- 반드시 docs/design-system.md를 먼저 읽고 따를 것
- 레퍼런스: monimo, 토스
- 미니멀하되 flat 금지 — depth(그림자, 레이어링) 유지
- 텍스트 나열식 리스트 금지 (게시판처럼 보임)

## 클라이언트에서 API가 필요할 때
- 서버 API가 필요한 기능을 구현할 때:
  1. 필요한 엔드포인트를 API_SPECIFICATION.md에 먼저 추가
  2. 클라이언트에서는 mock 데이터로 대체하여 화면이 동작하게 구현
  3. 서버 구현은 별도로 진행
- 존재하지 않는 API를 직접 호출하는 코드를 작성하지 말 것

## API 작업 시
- API 스펙 문서: API_SPECIFICATION.md (프로젝트 루트)
- API 추가/변경 시 이 문서를 먼저 업데이트하고 구현할 것

 

왜 이게 효과적인가

여기 있는 건 전부 코드를 읽어도 알 수 없는 것들이다:

항목왜 필요한가

"게시판처럼 보임"	사람의 감각적 판단. 코드로 표현 불가
mock-first 프로세스	"API가 필요하면 명세 추가 → mock 대체"라는 작업 흐름
"일정 관리 앱이 아님"	코드에 일정 기능이 있어서 AI가 일정 앱으로 오해할 수 있다

CLAUDE.md가 길면 두 가지 문제가 생긴다.

매 세션마다 컨텍스트를 낭비하고, 코드와 문서가 어긋나면 AI가 혼란스러워한다. 

코드에서 읽어낼 수 있으면 넣지 않는다 — 이 원칙 하나면 충분하다.

---

4. Superpowers — "다시 해줘" 루프 탈출

Claude Code에는 Superpowers라는 플러그인이 있다. 스킬이라 불리는 작업 프로세스를 설치해두면, 자연어로 요청했을 때 Claude가 맥락에 맞는 스킬을 알아서 발동시킨다.

"홈 화면을 개편하고 싶다"고 말하면, Claude가 brainstorming 스킬을 발동시켜 먼저 대화를 시작한다. 뭘 바꿀지, 제약이 뭔지 물어보고, 내가 고른 방향으로 스펙 문서를 만든다. 스펙이 나오면 writing-plans 스킬이 이어져 실행 계획을 체크리스트로 쪼개고, executing-plans가 한 스텝씩 처리하면서 매번 확인을 받는다.

brainstorming → 방향 고정 (스펙 문서)
    ↓
writing-plans → 순서 결정 (실행 계획)
    ↓
executing-plans → 단계별 구현 + 검수

이게 좋았던 건, "홈 화면 리디자인해줘" 한 번에 시키고 마음에 안 들면 "다시 해줘"를 반복하는 루프에 안 빠진다는 것이다.

매 단계마다 내가 개입하니까 방향이 어긋날 틈이 없다.

UI 변경 때 특히 빛났다. "온보딩 가이드를 넣고 싶다"고 말하자 brainstorming이 발동됐는데, 이 때에는 실제 HTML 목업을 만들어서 로컬 서버를 띄워주었다.

브라우저에서 각 안을 직접 눈으로 보고 고를 수 있었다.

"설명 들어보고 상상해봐"가 아니라 "직접 보고 골라"인 셈이다. 텍스트로 "A안은 이렇고 B안은 이렇습니다"를 읽는 것과, 실제 화면을 보면서 고르는 건 판단의 정확도가 다르다.

---

만든 앱: Glip

이렇게 만든 앱이 Glip다.

휴대폰 용량이 가득 차 사진을 지우다보니, 정보성 사진들이 굉장히 많았다. (나중에 갈 맛집, 화장품 정보 등 일단 찍어놓고 보는 것들..)

이런 사진들 용량만 차지하고 나중에 다시 찾기도 쉽지 않은데, 꼭 사진으로 찍어놔야하나라는 문제의식에서 출발했다.

 

사진을 찍으면 AI가 알아서 분석하고, 카테고리별로 정리하고, 나중에 검색할 수 있게 저장해준다.

영수증, 일정, 연락처, 메모 — 뭐든 찍으면 된다. 찍고 잊어도 된다. 나중에 "지난달 영수증 어디 있지?" 하면 검색하면 된다.

 

글립 - AI로 사진 속 정보만 쏙 - Google Play 앱

(앱스토어: TO BE)

---

정리

백엔드 개발자가 엔드투엔드로 앱을 만들면서 느낀 것:

1. 본인 영역의 전문성이 다른 영역에서도 작동한다. 서버 개발하면서 쌓은 "좋은 코드를 판단하는 눈"은 Flutter에서도 통한다. 구현은 AI가 한다.
2. CLAUDE.md는 짧게. 코드에서 읽어낼 수 있으면 넣지 않는다.
3. 문서가 코드에 선행한다. API 명세든, 디자인 가이드든, 먼저 문서로 정의하고 구현한다. AI가 임의로 결정하게 두면 내 의도와 어긋난다.
4. 바이브코딩도 체계가 있다. 방향 → 계획 → 실행. 한 번에 시키면 "다시 해줘"의 무한 루프에 빠진다. 매 단계에서 디렉팅할 수 있어야 한다.