Claude Code가 다시 똑똑해진다 - MCP Serena 실무 활용 가이드

Claude Code가 다시 똑똑해진다 - MCP Serena 실무 활용 가이드

Claude Code를 쓰다 보면 누구나 겪는 답답한 순간이 있습니다. 분명 5분 전에 설명한 프로젝트 구조를 또 설명해야 하고, 대화가 길어지면 Claude가 초반에 했던 약속을 까맣게 잊어버립니다. 컨텍스트가 사라지는 순간, Claude Code는 당신의 코드베이스를 처음 보는 초보자처럼 행동합니다. 이 문제를 근본적으로 해결하는 도구가 바로 MCP Serena입니다.

Claude Code가 멍청해지는 이유

Claude Code의 가장 큰 적은 바로 컨텍스트 윈도우의 한계입니다. 대화가 길어지면 Claude는 자동으로 오래된 정보를 압축하거나 버립니다. 문제는 이 과정에서 프로젝트의 핵심 구조, 아키텍처 결정, 코딩 컨벤션까지 함께 사라진다는 점입니다.

실제 개발자들이 보고한 증상들:

• 세션 중반부터 Claude가 프로젝트 구조를 잊어버림
• CLAUDE.md에 작성한 가이드라인을 무시하기 시작
• 같은 질문을 반복해서 물어봄
• 이미 존재하는 패턴을 무시하고 제너릭한 코드를 생성

한 개발자는 이렇게 토로했습니다: "세션당 10-15분을 프로젝트 컨텍스트를 다시 설명하는 데 쓴다. 이게 매번 반복된다."

Serena가 가져오는 실질적 변화

70% 토큰 절약, 그 이상의 의미

커뮤니티에서 보고된 실제 수치는 인상적입니다. 복잡한 기능 구현 시 60-70%의 토큰 절약과 시간 단축이 일관되게 보고됩니다. 하지만 진짜 게임 체인저는 숫자가 아닙니다.

한 사용자의 경험담: "OAuth 구현에 기존에 30분 걸리던 작업이 8분으로 줄었다. 더 중요한 건, 생성된 코드가 우리 프로젝트의 기존 패턴을 완벽하게 따랐다는 점이다."

왜 토큰이 줄어들까? Serena는 전체 파일을 읽는 대신 심볼 레벨에서 코드를 이해합니다. authenticate_user 함수가 필요하면 그 함수만 가져오고, 파일 전체의 2000 토큰이 아닌 50 토큰만 사용합니다.

컨텍스트가 사라지지 않는다

Serena의 메모리 시스템은 프로젝트 이해를 .serena/memories/ 디렉토리에 저장합니다. 여기에는:

• 프로젝트 구조와 주요 모듈
• 기술 스택과 프레임워크
• 코딩 컨벤션과 패턴
• 아키텍처 결정사항

세션이 끝나도 이 정보는 남아있습니다. 다음 대화에서 Claude는 이 메모리를 읽고 마치 프로젝트를 계속 작업해온 것처럼 행동합니다.

실제 사용자 보고: "Cross-platform Sudoku 앱 (iOS, Android, Electron, Next.js)을 Serena에게 보여줬더니, 설명 없이도 프로젝트 구조를 완벽히 파악했다. TODO 파일까지 읽고 내가 계획한 것을 이해했다."

바로 적용 가능한 설정 가이드

1단계: 5분 만에 설치하기

# Claude Code 프로젝트 디렉토리에서 실행
claude mcp add serena -- uvx --from git+https://github.com/oraios/serena \
  serena start-mcp-server --context ide-assistant --project $(pwd)

이게 전부입니다. 이 한 줄이면 Serena가 Claude Code에 통합됩니다.

필수 요구사항:

• Python 3.11 이상
• uv 패키지 매니저 (설치 가이드)

2단계: 프로젝트 온보딩 (중요!)

첫 세션에서 Claude에게 이렇게 말하세요:

"이 프로젝트를 온보딩해줘. 구조를 파악하고 메모리를 생성해."

Serena는 프로젝트를 분석하고 핵심 정보를 .serena/memories/에 저장합니다. 이 과정은 한 번만 하면 됩니다. 이후 모든 세션에서 Claude는 이 메모리를 기반으로 작업합니다.

⚠️ 주의: 온보딩은 많은 토큰을 소비합니다. 대형 프로젝트는 프리 티어 한도를 고려하세요.

3단계: (선택) 대형 프로젝트 최적화

프로젝트가 크다면 인덱싱으로 속도를 크게 높일 수 있습니다:

uvx --from git+https://github.com/oraios/serena serena project index

이 명령은 심볼 정보를 캐시하여 모든 작업을 빠르게 만듭니다.

즉시 써먹는 워크플로우 팁

패턴 1: 깨끗한 Git 상태에서 시작

git status  # 커밋되지 않은 변경사항 확인
git commit -am "Before AI changes"

이유: Claude가 자신이 만든 변경사항을 git diff로 검토할 수 있습니다. 자체 수정 능력이 극적으로 향상됩니다.

패턴 2: 심볼 레벨 질문하기

❌ 나쁜 예: "auth.py를 읽고 인증 로직을 찾아줘"
✅ 좋은 예: "인증과 관련된 모든 심볼을 찾아줘"

두 번째 방식은 Serena의 시맨틱 검색을 활용합니다. 파일을 통째로 읽는 대신 관련 함수와 클래스만 정확히 찾아냅니다.

패턴 3: 장기 작업의 연속성 유지

복잡한 기능을 여러 세션에 걸쳐 작업할 때:

세션 종료 전: "지금까지의 진행사항을 요약해서 메모리에 저장해줘"
다음 세션: "[기능명] 메모리를 읽고 작업을 이어서 해줘"

이 패턴으로 Claude의 컨텍스트 리셋 문제를 완전히 우회할 수 있습니다.

패턴 4: Sequential Thinking과 조합

다른 MCP 서버와 함께 쓰면 시너지가 폭발합니다:

항상 사용:
- serena: 시맨틱 코드 검색과 편집
- context7: 최신 서드파티 라이브러리 문서
- sequential-thinking: 복잡한 의사결정

루트 디렉토리의 claude.md 파일을 먼저 읽어라.

Rob Marshall이라는 개발자는 이 조합으로 복잡한 기능 구현 시간을 70% 단축했다고 보고했습니다.

일반적인 문제와 해결법

문제 1: Windows에서 npm 관련 오류

증상: "npm: command not found (exit code 127)"

원인: fnm이나 nvm 같은 Node 버전 관리자를 쓸 때 PATH 환경변수 문제

해결법:

# 시스템 전역에 Node.js 설치 또는
# 환경변수를 명시적으로 설정

현재 활발히 개발 중인 이슈로, 곧 수정될 예정입니다.

문제 2: 온보딩 후 메모리 부정확

증상: Serena가 생성한 메모리에 틀린 정보가 있음

해결법: .serena/memories/ 디렉토리의 마크다운 파일을 직접 수정하세요. 이 파일들은 그냥 텍스트이므로 수동으로 편집 가능합니다.

팁: 프로젝트 초기에 project_structure.md에 핵심 정보를 직접 작성하는 것도 좋은 전략입니다.

문제 3: 큰 가상환경에서 멈춤

증상: Python venv가 있는 프로젝트에서 서버가 응답 없음

해결법: .gitignore에 venv 디렉토리를 명시하세요. Serena가 불필요한 파일을 스캔하지 않도록 합니다.

문제 4: 중요한 버그 수정 시 컨텍스트 손실

흥미로운 피드백: 일부 사용자는 "버그를 찾을 때는 Serena를 끄는 게 더 낫다"고 보고했습니다.

이유: 버그 수정에는 광범위한 컨텍스트가 필요한 경우가 있습니다. Serena의 효율적인 심볼 레벨 접근이 오히려 "전체 파일을 읽으며 얻는 우연한 인사이트"를 놓칠 수 있습니다.

해결책: 탐색 단계에서는 Serena 없이 작업하고, 수정할 위치를 찾은 후 Serena를 켜서 정확한 편집을 수행하세요.

언제 Serena를 쓰면 좋을까?

✅ Serena가 빛나는 상황

대형 구조화된 코드베이스: 수십~수백 개 파일, 복잡한 의존성이 있는 프로젝트

실제 사례: "Vue.js 프론트엔드 + .NET 백엔드 + Terraform 인프라 모노레포에서 완벽하게 작동했다. 각 파트를 정확히 이해했다."

리팩토링과 유지보수: 기존 코드 이해, 안전한 이름 변경, API 사용처 찾기

멀티 언어 프로젝트: TypeScript + Python + Rust 같은 이종 언어 조합

토큰 예산이 타이트할 때: API 비용 절감이 중요하거나 프리 티어를 쓸 때

⚠️ Serena가 오버킬인 상황

작은 프로젝트: 파일이 몇 개 안 되는 간단한 스크립트

처음부터 새로 작성: 아직 구조가 없어서 분석할 게 없을 때

빠른 프로토타이핑: 코드를 자주 갈아엎는 초기 실험 단계

실제 성공 사례

사례 1: James Acres - 크로스플랫폼 UI 개선

프로젝트: iOS, Android, Electron을 지원하는 Next.js + React Sudoku 앱

작업: "src/app/page.tsx를 iOS 네이티브처럼 느껴지게 만들어줘"

결과:

• 모든 버튼, 헤딩, 색상, 그라디언트, 호버 효과를 일관되게 수정
• Tailwind 스타일 가이드를 완벽히 따름
• 첫 시도에서 성공, 린트만 하고 커밋

소감: "결과가 놀라웠다. 설명 없이도 프로젝트를 완벽히 이해했다."

사례 2: Rob Marshall - OAuth 구현

Before (전통적 방식): 30분

• 제너릭한 코드 생성 (5분)
• 프로젝트 아키텍처 설명 (5분)
• 기존 패턴 설명 (5분)
• 구식 API 수정 (5분)
• 컴포넌트 구조 적응 (10분)

After (Serena + Sequential Thinking): 8분

• Sequential Thinking이 요구사항 매핑 (2분)
• Serena가 기존 인증 패턴 발견 (1분)
• Context7이 최신 NextAuth.js 문서 가져옴 (1분)
• 완전한 구현 생성 (4분)

차이점: 생성된 코드가 자동으로 기존 패턴을 따랐고, 최신 베스트 프랙티스를 사용했으며, 완벽하게 통합되었습니다.

비용 대비 효과

Serena는 완전 무료 오픈소스입니다. Cursor나 Windsurf 같은 도구가 월 $20-40를 받는 반면, Serena는 무료로 비슷하거나 더 강력한 기능을 제공합니다.

Claude Desktop 프리 티어와 조합하면? 완전히 무료로 강력한 코딩 에이전트를 쓸 수 있습니다. 이것이 커뮤니티에서 "게임 체인저"라고 부르는 이유입니다.

API 비용 절감: Claude Code를 API로 쓴다면 토큰 절약이 직접적인 비용 절감으로 이어집니다. 70% 토큰 절감은 곧 70% 비용 절감입니다.

결론: 왜 지금 당장 써야 하는가

Claude Code의 컨텍스트 유지 문제는 단순히 불편한 게 아니라 생산성을 직접적으로 갉아먹는 문제입니다. 매 세션마다 프로젝트를 다시 설명하고, 같은 패턴을 반복 설명하고, 제너릭한 코드를 수정하는 시간은 순수한 낭비입니다.

Serena는 이 문제를 근본적으로 해결합니다:

• 심볼 레벨 이해로 정확한 코드 조작
• 메모리 시스템으로 세션 간 연속성 보장
• 70% 토큰 절약으로 비용과 시간 절감
• 완전 무료로 진입 장벽 제로

설치는 5분, 온보딩은 한 번만. 그 이후로는 Claude Code가 마치 처음부터 당신의 프로젝트를 알고 있었던 것처럼 작동합니다.

지금 당장 시도해보세요. 첫 세션에서 차이를 느낄 것입니다.