Backend Developer

5 분 소요

이전 글에서 Claude Code가 무엇인지, 어떤 특징을 가지고 있는지 살펴봤습니다. 이번엔 실제로 실무에 써봤습니다.

대규모 상용 백엔드 시스템에 새로운 비즈니스 모듈을 추가하는 작업이었는데,
기존 코드베이스가 꽤 복잡했기 때문에 살짝 걱정도 되었습니다.

결과부터 말하자면, Claude Code는 내 기대를 넘어섰습니다.
어떻게 활용했는지, 무엇이 좋았는지, 그리고 어떤 실수들이 있었는지 공유해보려고 합니다.

📋 프로젝트 배경

작업한 프로젝트는 이미 수년간 운영되고 있는 대규모 백엔드 시스템이었다. Node.js와 TypeScript로 구축된 마이크로서비스 아키텍처로, 모노레포 구조를 채택하고 있었다. 여기에 새로운 비즈니스 모듈을 추가해야 했는데, 기존 코드와의 일관성을 유지하면서도 빠르게 개발해야 하는 상황이었다.

Claude Code와의 실무 첫 만남

🔍 기존 코드 패턴을 이해하다

처음 시도해본 건 기존 프로젝트의 패턴을 Claude Code가 얼마나 이해할 수 있는지 테스트하는 것이었다.

# 간단한 요청으로 시작했다
"기존 프로젝트의 엔티티 패턴을 분석해서 새로운 비즈니스 엔티티를 만들어줘"

Claude Code는 프로젝트 전체를 스캔하기 시작했다.
기존 엔티티 파일들을 하나씩 읽어가며 패턴을 파악하고, 프로젝트에서 사용하는 데코레이터나 라이브러리까지 확인했다.
심지어 검증 로직이나 변환 패턴같은 세부사항까지 분석해서 새 엔티티를 만들어냈다.

💫 첫 번째 실수, 그리고 빠른 회복

물론 처음부터 완벽했던 건 아니다. Claude Code가 처음에 잘못된 ORM 라이브러리를 사용해서 코드를 생성했다.
(이 레포지토리는 Knex를 쓰지만, 얘는 갑자기 TypeORM을 기준으로 만들더라..)

사실 이런 일이 꽤 자주 있었다. 프로젝트 구조가 복잡하다 보니 Claude Code가 잘못된 가정을 하는 경우가 종종 있었다. 예를 들어:

  • 없는 헬퍼 함수를 import하려고 시도
  • 프로젝트에서 사용하지 않는 라이브러리 추천
  • 잘못된 디렉토리 구조로 파일 생성 시도
// Claude Code가 처음 생성한 코드
@Entity('business_entity')
export class BusinessEntity {
  @PrimaryGeneratedColumn()
  id: number;
  // ...
}

이걸 보고 “아, 이 프로젝트는 TypeORM을 안 써요”라고 피드백을 줬다. 그러자 즉시 프로젝트 전체를 다시 스캔하기 시작했고,
우리가 실제로 사용하는 데이터 접근 패턴을 찾아냈다. 그리고 모든 관련 파일을 올바른 패턴으로 리팩토링했다.

이 때 중점적으로 봤던 것은 얼마나 빨리 피드백을 받아들이고 수정하는가였는데,
Claude Code는 이 부분에서 탁월했다.

다만 가끔은 너무 과도하게 수정하려고 하는 경향이 있었다. “이 부분만 고쳐줘”라고 했는데 관련된 파일 전체를 리팩토링하려고 시도하는 경우가 있어서, 계속해서 범위를 제한해줘야 했다.

✅ 테스트까지 알아서 척척

개발하다 보면 테스트 작성이 가장 귀찮을 때가 많다. 특히 Mock 설정이나 복잡한 의존성 처리는 시간을 많이 잡아먹는다.

# 테스트 실행해보니 당연히 실패
yarn test libs/core/src/business-module/business-module.service.spec.ts

14개의 테스트가 모두 실패했다. 보통이라면 하나씩 디버깅하면서 수정해야 했을 텐데, Claude Code는 테스트 실패 원인을 즉시 분석하고 Mock 설정 문제를 파악했다. 그리고는 테스트 케이스를 하나씩 수정해가며 모든 테스트를 통과시켰다.

이 과정을 지켜보면서 “이거 정말 시간 많이 아끼겠는데?”라는 생각이 들었다.

📝 Git 커밋도 깔끔하게

Claude Code의 또 다른 장점은 Git 워크플로우 관리였다. 작업을 논리적 단위로 나누어 커밋하는데, 이게 정말 깔끔했다.

git commit -m "feat: 비즈니스 모듈 코드 길이 변경"
git commit -m "fix: 모듈 코드 예시 형식 수정" 
git commit -m "test: 비즈니스 모듈 테스트 파일 업데이트"

우리 팀의 커밋 컨벤션(feat, fix, test 등의 접두사)도 자연스럽게 따라했다. 나중에 코드 리뷰할 때 정말 편했다.

🐛 예상치 못한 버그 발견

개발 중에 재미있는 일이 있었다. API를 테스트하다가 관련 데이터가 표시되지 않는 문제를 발견했다.

“API 응답에서 관련 데이터가 누락되어 있어요”라고 말하니, Claude Code가 디버깅을 시작했다. 컨트롤러에서 하드코딩된 빈 배열을 발견하고, 서비스 레이어를 추적해서 실제 데이터 조회 로직이 누락된 걸 찾아냈다.

좀 더 테스트해보니, API 응답에서 불필요한 내부 필드를 반환하고있었다. 이를 제거하는 보안 개선도 제안했고 잘 수정해주었다.

하지만 이 과정에서 몇 가지 문제도 있었다:

  • 처음엔 필요한 필드까지 제거하려고 시도
  • 응답 구조를 너무 단순화해서 프론트엔드와 호환성 문제 발생
  • 결국 내가 직접 어떤 필드가 필요한지 하나씩 지정해줘야 했다

🏗️ 아키텍처 결정에 대한 조언

Claude Code가 만든 데이터 업데이트 로직을 테스트해보면서 “기존 관련 데이터를 모두 삭제하고 다시 추가하는 게 맞나?”라는 질문을 했다.
업데이트건에 관련있는 데이터는 무수히 많을 가능성이 있다. 불필요한 Insert와 Delete가 많이나갈것이 뻔했다.

Claude Code에게 이 고민을 털어놨더니, 꽤 심도 있는 분석을 해줬다. 현재 방식의 성능 문제를 지적하고, 세 가지 대안(차분 업데이트, Upsert, 현재 방식 유지)을 제시했다.
각 방식의 장단점과 구현 복잡도까지 비교해줬는데, 실무적 관점에서 균형 잡힌 조언이었다고 생각한다.

💭 실제로 써보니 느낀 점

🎨 기존 코드와의 조화

가장 인상적이었던 건 Claude Code가 기존 코드베이스와 완벽하게 조화를 이뤘다는 점이다. 대규모 프로젝트의 패턴을 정확히 파악하고, 팀의 코딩 컨벤션을 자연스럽게 따라했다. 마치 오래 함께 일한 팀원처럼 느껴졌다.

⚡ 빠른 피드백 처리

실시간으로 피드백을 주고받을 수 있다는 점도 좋았다. 에러가 발생하면 즉시 원인을 분석하고, 내가 지적한 부분은 바로 수정했다. 이런 빠른 반복 작업이 전체적인 개발 속도를 크게 향상시켰다.

🔎 놓치기 쉬운 부분까지

코드 작성부터 테스트, 문서화, Git 관리까지 개발의 전 과정을 지원받을 수 있었다. 특히 보안이나 성능 관점에서 놓치기 쉬운 부분들을 짚어주는 게 도움이 됐다.

🤔 그럼에도 불구하고 아쉬운 점들

  1. 컨텍스트 이해의 한계: 아무리 프로젝트 전체를 스캔해도, 팀 내부의 암묵적인 규칙이나 히스토리는 이해하지 못했다. “이 부분은 레거시라서 건드리면 안 돼”같은 걸 일일이 설명해야 했다.

  2. 과도한 자신감: 가끔 확실하지 않은 부분도 자신있게 구현하는 경향이 있었다. 특히 복잡한 비즈니스 로직에서는 내가 다시 검증해야 했다.

  3. 반복적인 실수: 한 번 수정한 패턴을 다른 파일에서 또 실수하는 경우가 있었다. 매번 같은 피드백을 반복해야 하는 게 조금 피곤했다.

📚 학습 도구로서의 가치

단순히 코드를 생성하는 것 이상의 가치가 있었다. 기존 프로젝트 구조를 학습하고, 모범 사례를 적용하며, 더 나은 아키텍처를 제안하는 과정에서 나도 많이 배웠다.

📊 구체적인 성과

실제로 얼마나 도움이 됐는지 숫자로 정리해봤다.

⏱️ 개발 시간 단축

완전한 CRUD API와 테스트, 문서화까지 포함해서 4시간 만에 완성했다. 평소라면 하루 반에서 이틀은 걸렸을 작업이다. 대략 3-4배 정도 빨라진 셈이다.

🎯 코드 품질 향상

14개의 단위 테스트를 모두 통과시켰고, Swagger를 통한 API 문서화도 완료했다. 테스트 커버리지는 70% 이상을 달성했다.

👥 팀워크 개선

기존 팀 코딩 스타일과 비슷한 코드를 생성해서, 코드 리뷰가 정말 수월했다. Git 히스토리도 깔끔하게 정리되어 있어서 추후에 확인할때도 수월히 이해할 수 있을 것 같다.

💡 Claude Code 잘 쓰는 팁

실제 사용하면서 터득한 몇 가지 팁을 공유하려고 한다.

📄 프로젝트 컨텍스트를 충분히 제공하자

CLAUDE.md 파일을 만들어서 프로젝트 개요, 아키텍처, 코딩 컨벤션, 자주 쓰는 명령어 등을 정리해두면 좋다. Claude Code가 프로젝트를 더 잘 이해하고 일관된 코드를 생성한다.

💬 명확한 피드백이 중요하다

막연하게 “틀렸어”라고 하기보다는 “이 프로젝트는 TypeORM을 사용하지 않습니다”처럼 구체적으로 알려주는 게 좋다. Claude Code는 명확한 피드백을 받으면 빠르게 학습하고 수정한다.

🔍 중간중간 검증하자

작업 중간에 테스트를 실행하고, Git 상태를 확인하면서 의도하지 않은 변경이 없는지 체크하는 게 중요하다.

🌟 마무리하며

Claude Code를 처음 써보기 전엔 “AI가 과연 실무에 도움이 될까?”라는 의구심이 있었습니다. 하지만 실제로 사용해보니 단순한 코드 생성기가 아닌 진짜 개발 파트너라는 느낌을 받았습니다.

물론 “파트너”라고 하기엔 아직 부족한 점도 많습니다. 내가 계속 가이드하고, 검증하고, 수정 방향을 제시해야 했습니다. 마치 신입 개발자를 교육하는 느낌이었습니다. 능력은 있지만 프로젝트의 맥락을 완전히 이해하지는 못하는, 그런 느낌이었습니다.

특히 대규모 프로젝트나 팀 협업이 중요한 환경에서 더욱 빛을 발한다고 생각합니다. 기존 코드의 맥락을 이해하고, 팀의 개발 문화에 맞춰 일관성 있는 코드를 생성하는 능력이 인상적이었습니다.

물론 Claude Code가 모든 걸 해결해주는 만능 도구는 아닙니다. 여전히 개발자의 판단과 검증이 필요하고, 복잡한 비즈니스 로직이나 아키텍처 결정은 사람이 해야 합니다.

솔직히 말씀드리면, Claude Code를 쓰면서 오히려 더 피곤한 순간들도 있었습니다.

  • 생성된 코드를 일일이 검토하는 시간
  • 잘못된 방향으로 가는 걸 계속 수정해주는 과정
  • “이걸 내가 그냥 짜는 게 더 빠르지 않나?”하는 생각이 들 때

하지만 전체적으로 봤을 때, 반복적인 작업을 자동화하고, 놓치기 쉬운 부분을 챙겨주며, 더 나은 코드를 위한 제안을 해주는 똑똑한 동료가 생긴 것 같습니다. 다만 이 동료는 아직 많은 가이드가 필요한 주니어 수준이라고 생각하면 될 것 같습니다.

앞으로도 Claude Code와 함께 작업하면서 더 많은 경험을 쌓아가려고 합니다. 다음에는 더 복잡한 프로젝트에서의 활용 사례를 공유할 수 있으면 좋겠습니다.

개인적으로는 Claude Code가 더 발전해서 이런 부분들이 개선되면 좋겠습니다.

  • 한 번 학습한 패턴을 세션 내내 기억하기
  • 프로젝트의 히스토리와 맥락을 더 깊이 이해하기
  • 불확실한 부분에 대해서는 더 신중하게 접근하기
  • 개발자의 의도를 더 정확히 파악하기

그때까지는 내가 좋은 가이드가 되어주면서, Claude Code의 장점을 최대한 활용해 나가려고 합니다. AI와 함께 성장하는 개발자가 되는 것도 나쁘지 않은 선택이라고 생각합니다. 🙏

댓글남기기

참고