우리가 Claude Code로 Nuxt 4 + Rust 모노레포를 유지하는 방법
Engineering Team
우리의 스택과 Claude Code가 적합한 이유
Open Soft에서 주요 제품은 모노레포로 구축된 웹사이트입니다: TypeScript의 Nuxt 4 프론트엔드와 PostgreSQL 기반 Rust/Axum 백엔드 API. 코드베이스는 두 가지 언어, 두 가지 빌드 시스템, 공유 데이터 계약, 데이터베이스 마이그레이션, 10개 언어의 i18n 파일, 배포 인프라를 아우릅니다. 변경은 자주 스택의 양쪽을 동시에 건드립니다.
2025년 중반에 Claude Code를 도입했고 가장 많이 사용하는 개발 도구가 되었습니다. 코드를 대신 작성해주기 때문이 아니라 다른 도구로는 불가능한 방식으로 전체 코드베이스에 대해 추론하기 때문입니다. Claude Code에게 “articles에 published_at 필드를 추가해“라고 말하면, Rust 마이그레이션을 읽고, 핸들러의 SQL 쿼리를 업데이트하고, 프론트엔드의 TypeScript 타입을 수정하고, Nuxt 페이지 컴포넌트를 조정하고, 10개 로캘 파일 모두를 업데이트하고, 검증을 위해 빌드를 실행합니다.
CLAUDE.md: 에이전트에 규약 가르치기
효과적인 Claude Code 사용의 기반은 CLAUDE.md 파일입니다. 이것은 Claude Code가 매 세션 시작 시 읽는 프로젝트 수준 지침 파일입니다.
우리의 CLAUDE.md에는 다음이 포함됩니다:
- 커밋 규약: 모든 커밋은
TASK-XXX:로 시작하고 명령형 사용 - 아키텍처 개요: 모노레포 구조, 어떤 디렉토리에 무엇이 있는지
- 코드 스타일 규칙: TypeScript strict 모드,
any금지, Composition API만,<script setup>구문 - i18n 규칙: 모든 10개 로캘 동기화 유지, 키 알파벳순 정렬, 영어 평문 키
- 보안 규칙: 커밋에 비밀 없음, 매개변수화 SQL, 명시적 CORS 출처
Claude Code는 이 규약을 일관되게 따릅니다. 커밋 메시지를 생성할 때 TASK-XXX: 접두사를 사용합니다. 번역 키를 추가할 때 10개 로캘 파일 모두에 알파벳순으로 추가합니다.
다중 파일 리팩토링: 킬러 유스 케이스
가장 시간을 절약하는 워크플로우는 크로스 스택 리팩토링입니다.
작업: articles 시스템에 SEO 필드 (meta_title, meta_description, focus_keyword, robots_meta) 추가.
Claude Code 없이 이 변경에 필요한 것:
- 4개 컬럼을 추가하는 SQL 마이그레이션 작성
- Rust
Article모델 구조체 업데이트 - Rust
CreateArticle과UpdateArticleDTO 업데이트 - articles 핸들러의 모든 SQL 쿼리 업데이트
- 프론트엔드의 TypeScript
Article타입 업데이트 - 관리자 편집기 폼에 새 필드 추가
- 블로그 포스트 페이지에서 메타 태그 렌더링 업데이트
- 사이트맵 생성 로직 업데이트
- 모든 fixture 파일 업데이트
- 마이그레이션 실행, 리빌드, 테스트
Claude Code로는 명령 하나를 입력합니다. Claude Code가 단일 에이전트 루프로 실행하여 12+ 파일에 걸쳐 모든 변경을 수행합니다. 전체 프로세스는 약 5분이고, 수동으로는 45-60분 걸립니다.
마이그레이션 작성
데이터베이스 마이그레이션은 현재 스키마, 원하는 최종 상태, 그 사이의 안전한 변환 경로에 대한 이해가 필요하므로 Claude Code에 특히 적합합니다.
테스트 생성
테스트 fixture와 SQL 시드 데이터 생성에 Claude Code를 광범위하게 사용합니다. fixture 파일에는 적절한 SEO 메타데이터가 있는 현실적인 장문 콘텐츠 (1500+ 단어 기사)가 포함되며, 수동으로 작성하면 지루하고 오류가 발생하기 쉽습니다.
Claude Code로 코드 리뷰
병합 요청을 열기 전에 Claude Code를 리뷰어로 실행합니다. 인간 코드 리뷰에서 발견될 문제의 약 30%를 잡아내어 인간 리뷰어가 아키텍처와 비즈니스 로직에 집중할 수 있게 합니다.
훅: 품질 게이트 자동화
Claude Code는 훅 — 특정 액션 전후에 자동 실행되는 스크립트 — 을 지원합니다.
프리커밋 훅: Claude Code가 커밋을 만들기 전에 cargo fmt --check와 cargo clippy를 실행합니다. 어느 하나가 실패하면 Claude Code가 문제를 수정하고 재시도합니다.
포스트에딧 훅: Claude Code가 /i18n/locales/의 파일을 수정한 후, 모든 10개 로캘 파일이 동일한 키 세트를 갖는지 검증하는 스크립트를 실행합니다.
MCP 서버: Claude Code의 기능 확장
Model Context Protocol (MCP) 서버는 Claude Code에 외부 도구 접근을 제공합니다. 두 개의 커스텀 MCP 서버를 실행합니다:
- 데이터베이스 MCP 서버: Claude Code가 개발 PostgreSQL에 직접 쿼리 가능.
- 배포 상태 MCP 서버: CI/CD 파이프라인에 연결. Claude Code가 최신 배포 성공 여부를 확인하고 빌드 로그를 읽고 실패를 진단합니다.
1M 컨텍스트로 대규모 코드베이스 팁
Claude Code의 1M 토큰 컨텍스트 윈도우는 모노레포 작업에서 가장 강력한 기능입니다.
Claude Code가 탐색하게 하세요. 어떤 파일을 보여줄지 사전 선택하려 하지 마세요. 원하는 것을 설명하고 Claude Code의 도구(Grep, Glob, Read)로 관련 코드를 찾게 하세요.
안정적 컨텍스트에 CLAUDE.md 사용. 세션 간에 변하지 않는 정보는 CLAUDE.md에 넣으세요.
메가 작업을 단계로 분할. 1M 토큰이 있어도 “전체 인증 시스템 리팩토링” 같은 작업은 단계별 접근이 유익합니다.
에이전트 루프를 신뢰하세요. Claude Code가 변경하고, 빌드를 실행하고, 오류를 보고, 수정할 때 — 그 루프가 기능입니다.
함정과 해결책
함정: Claude Code의 과잉 설계. 해결책: CLAUDE.md에 “KISS — 간단하게 유지. 과잉 설계를 피하라.“를 추가.
함정: 긴 세션에서의 오래된 컨텍스트. 해결책: 각 주요 작업에 새 세션 시작.
함정: 비결정적 출력. 해결책: 구체적이고 상세한 프롬프트 사용.
함정: 테스트 데이터 품질. 해결책: 생성된 fixture를 항상 리뷰하고 전체 테스트 스위트 실행.
함정: 공격적인 파일 변경. 해결책: 수락 전 diff를 주의 깊게 리뷰.
FAQ
Claude Code 일상 사용 비용은?
4명 개발자 팀에서 모든 프로젝트의 Claude Code API 사용에 월 약 $200-300을 지출합니다. 개발자당 월 $20의 Max 플랜이 더 예측 가능한 대안입니다.
Claude Code는 오프라인으로 작동하나요?
아니요. Claude Code는 Anthropic API와 통신하기 위해 인터넷 연결이 필요합니다.
Claude Code가 빌드를 깨뜨릴 수 있나요?
네, 하지만 대부분의 문제를 스스로 잡습니다. 약 90% 빌드가 첫 번째 시도에 성공하고 99%가 자기 수정 루프 후 성공합니다.
Claude Code는 솔로 개발자에게 적합한가요?
물론입니다. 코드 리뷰의 두 번째 눈, 프로젝트 규약을 기억하는 지식 베이스, 지루한 작업의 역량 배증기로 기능합니다.
결론
Claude Code는 애플리케이션을 대신 작성해주는 마법 지팡이가 아닙니다. 크로스 스택 추론, 규약 집행, 지루한 다중 파일 변경에 뛰어난 역량 배증기입니다. 영구적 프로젝트 지식을 위한 CLAUDE.md, 품질 집행을 위한 훅, 외부 도구 접근을 위한 MCP 서버의 조합이 모노레포 작업에서 사용해본 가장 유능한 AI 개발 도구로 만듭니다.
9개월 일상 사용 후 핵심 통찰: Claude Code는 새 코드 작성이 아니라 기존 코드 유지보수 — 리팩토링, 마이그레이션, 테스트, 리뷰 — 에서 가장 가치가 있습니다.