[개발 회고] 주니어 개발자가 Claude Code와 협업하며 깨달은 3가지 필승 전략

클러드 코드를 사용해서 코드비 마켓을 만들었습니다.

 

처음 Claude Code를 접했을 때는 마법 같았습니다. 하지만 프로젝트 규모가 커지고 복잡해지자 문제가 터지기 시작했습니다.
AI는 옛날 문서를 보고 엉뚱한 코드를 짜거나, UI와 DB가 맞지 않는 기능을 만들어냈죠.

이 문제를 해결하기 위해 제가 정립한 3가지 핵심 전략을 소개합니다.

 

---

1. 개발 순서 뒤집기: "DB 먼저"는 망하는 지름길

가장 먼저 부딪힌 벽은 '작업 순서'였습니다.
보통 백엔드 개발을 배울 때 DB 설계 → API 구현 → UI 연동 순서로 배우잖아요? 저도 그렇게 Taskmaster에게 시켰습니다. 결과는 처참했습니다.

❌ 실패한 방식: 수평적 분할 (Horizontal Slicing)

저는 AI(Taskmaster)에게 다음과 같이 작업을 시켰습니다.

1. "상품 테이블 만들어줘." (DB)
2. "상품 등록 API 만들어줘." (API)
3. "상품 등록 페이지 만들어줘." (UI)

결과:

• AI가 만든 DB에는 막상 UI를 만들 때 필요한 필드(예: 이미지 순서, 특정 버튼 플래그)가 없었습니다.
• UI를 만들다 보니 DB를 고쳐야 했고, DB를 고치니 API도 고쳐야 했습니다.
• "백엔드 다 짜놨는데 UI랑 안 맞아서 갈아엎는 일"이 무한 반복되었습니다.

✅ 성공 전략: 수직적 슬라이싱 (Vertical Slicing) + UI First

그래서 전략을 완전히 바꿨습니다. UI(껍데기)를 먼저 완벽하게 만들고, 거꾸로 DB를 설계하는 방식입니다.

1단계: UI Mockup (Schema-less)

• "DB 생각하지 말고, 하드코딩된 더미 데이터를 써서 UI부터 완벽하게 만들어."
• 이렇게 하면 AI는 UI를 구현하면서 필요한 데이터가 무엇인지 스스로 확정하게 됩니다.

2단계: UI 기반 스키마 역설계

• "방금 만든 UI 컴포넌트(ProductForm.tsx)를 봐. 여기에 들어가는 데이터를 저장할 수 있게 Prisma Schema를 짜줘."
• 이러면 프론트와 백엔드의 필드명이 불일치할 확률이 0%가 됩니다.

3단계: API 연동 및 테스트

• 이제 더미 데이터를 실제 API로 연결만 하면 끝입니다.

💡 성과: 이 방식을 적용한 후, 기능 하나를 만드는 데 걸리는 시간이 13일에서 6일로 약 54% 단축되었습니다. 재작업이 사라졌기 때문입니다.

---

2. 작업 관리의 기술: Task Master는 '언제' 써야 할까?

Claude Code에는 tasks.json 같은 파일로 할 일을 관리해 주는 기능(Task Master)이 있습니다. 처음엔 모든 일을 여기에 등록해서 처리하려 했지만, '성능 최적화' 같은 복잡한 문제에서 막혔습니다.

🤔 발견한 패턴

구분	Task Master 사용 (O)	Task Master 사용 (X)
상황	로그인, 회원가입, UI 구현 등	검색 속도 10배 향상, 아키텍처 변경
특징	**What(무엇)**을 만들지가 명확함	How(어떻게) 할지를 먼저 찾아야 함
접근	정해진 순서대로 구현	실험, 측정, Trade-off 분석 필요

❌ 잘못된 접근: 최적화를 태스크로 만들기

제가 "검색 성능 최적화"를 바로 태스크 리스트에 넣었더니, AI는 고민 없이 바로 코드를 짜기 시작했습니다. "Redis를 쓸지, DB 인덱스를 태울지" 고민도 없이 일단 구현부터 해버리니, 나중에 전체를 갈아엎어야 했습니다.

✅ 권장 워크플로우: 하이브리드 접근법

Phase 1: 탐색 및 결정 (채팅 & 문서화)

• 먼저 시니어 개발자(AI 페르소나)와 대화하며 설계부터 합니다.
• senior-developer-conversation.md 같은 문서를 만들어 "Redis vs Elasticsearch" 장단점을 비교하고 결정을 내립니다.

Phase 2: 대규모 구현 (Task Master 활용)

• 이미 "Redis를 쓰겠다"고 결정이 났다면, 그때 비로소 태스크 파일을 만듭니다.
• "Redis 클라이언트 작성" → "API 캐싱 적용" 순서로 일을 시킵니다.

💡 핵심: Task Master는 '무엇(What)'이 정해졌을 때 실행을 돕는 도구입니다. **'어떻게(How)'**를 고민해야 할 때는 AI와 먼저 대화(Chat)를 나누고 문서를 남기세요.

---

3. AI의 기억력 관리: 문서 폴더 분리 전략

프로젝트가 길어지다 보니 문서(docs/)가 수십 개 쌓였습니다. 어느 날 AI에게 "하이브리드 방식으로 작업 리스트 뽑아줘"라고 했더니, AI가 과거에 실패했던 방식과 현재 방식을 섞어서 끔찍한 혼종 설계를 내놓았습니다.

🚨 문제 상황: 문서 간 충돌

AI는 제가 제공한 5개의 문서를 읽었는데, 그중에는 **'폐기된 옛날 아이디어'**와 **'최신 확정 아이디어'**가 섞여 있었습니다.

• 문서 A: "메모리에서 계산하자" (옛날 생각)
• 문서 B: "DB에 저장하자" (최신 생각)
• AI의 결론: "DB에 저장하면서 메모리 계산도 하자" (???)

✅ 해결책: 물리적 폴더 분리 (final vs archived)

AI가 헷갈리지 않게 문서의 유통기한을 명확히 해줬습니다.

1. docs/final/: 현재 유효한 최신 설계 문서만 넣습니다.
2. docs/archived/: 지나간 설계, 실패한 시도 등은 여기로 옮깁니다. 
   
   그리고 CLAUDE.md 파일에 아래와 같은 규칙을 작성했습니다.
   
   ## 1.8 문서 참조 우선순위
   
   ### 필수 규칙
   
   1. **`docs/final/` 폴더 우선 참조**
   - 구현 시 반드시 이 폴더의 문서만 사용
   - 최신(CURRENT) 설계만 포함
   
   2. **`docs/archived/` 폴더는 참고만**
   - 역사적 맥락 파악용
   - 절대 이 폴더 기준으로 코드 작성 금지
   - 읽었다면 사용자에게 경고: "이 문서는 ARCHIVED입니다"
   
   3. **불일치 발견 시**
   - 즉시 중단 후 사용자에게 질문
   - "docs/final/과 docs/archived/에서 다른 정의를 발견했습니다. 어느 것을 따를까요?"

docs/
├── final/                    # ✅ AI야, 여기 있는 게 진짜야.
│   ├── HOME_SORTING.md
│   └── SEARCH_SORTING.md
│
└── archived/                 # ⚠️ AI야, 이건 옛날 거야. 읽고 헷갈리지 마.
    ├── GRID_CACHE_v1.md
    └── HYBRID_MEMORY_ONLY.md

이 간단한 조치(폴더 이동)만으로 AI의 환각(Hallucination) 현상이 싹 사라졌습니다.

---

🚀 결론: AI는 유능하지만 가이드가 필요한 부사수

Claude Code를 쓰면서 느낀 점은, AI가 아무리 똑똑해도 '맥락(Context)'을 관리하는 건 인간의 몫이라는 겁니다.

1. UI First: 껍데기부터 만들어서 데이터 구조의 불일치를 막으세요.
2. Think before Task: 무작정 코딩시키지 말고, .md 문서로 먼저 설계를 확정하세요.
3. Clean Context: 옛날 문서는 치워서 AI가 헷갈리지 않게 하세요.

이 3가지만 지켜도 주니어 개발자로서 AI와 협업하는 효율이 폭발적으로 늘어날 것입니다.
여러분의 AI 협업 꿀팁이 있다면 댓글로 공유해 주세요! 😊