ujja: Turbo+Next.js 모노레포에서 CLAUDE.md를 8섹션 메모리로 만든 1주일

배경

ujja는 Turbo + Next.js 모노레포(다수 앱·공유 패키지·인프라·툴링)와 별도의 레거시 리포 두 개를 동시에 다룬다. Copilot/Cursor에서 Claude Code로 옮기며 모노레포에서 어떻게 안정적으로 일할 수 있는지 검증.

접근

CLAUDE.md를 단순 readme가 아니라 “메모리 앵커”로 설계 — 8섹션 구조: 명령 레퍼런스, 폴더 개요, 기술 스택, 팀/프로젝트 컨텍스트, 워크플로우, 스토리/수용 기준, PR/커밋/체인지셋 가이드, 트러블슈팅. 레거시 리포에는 별도 CLAUDE_LEGACY.md — 스택/버전 맵, 디버그 절차, 일반 실패, 알려진 위험, 버그픽스 플레이북, 업그레이드 노트. Jira/GitHub MCP 통합으로 티켓→브랜치→PR이 한 흐름.

결과

한 레거시 리포에서 수개월 묵은 race condition을 Claude가 트랜잭션 래핑 + 옛 스타일 테스트로 분 단위에 해결. 크로스 패키지 편집·NestJS 스캐폴딩·Vitest 작성이 더 빠르고 오류가 줄어듦.

교훈

“먼저 생각하고, 집중된 컨텍스트를 주고, 정확한 변경을 요청하라.” 헤더와 번호로 Claude가 “기억”할 수 있게 구조화하라. CLAUDE.md는 문서가 아니라 시스템이다.

원문 인용

“It’s not just a readme; it’s a complete, structured knowledge base that gives Claude Code everything it needs to operate safely.” 의역: 그건 readme가 아니라 Claude Code가 안전하게 일하기 위해 필요한 모든 것을 담은 구조화된 지식 베이스다.