배경 및 목표
백엔드 코드베이스가 여러 레포로 흩어져 있었고, 레포마다 컨벤션·리뷰 기준·자동화가 제각각이었스빈다. 동일한 Claude Code 설정(에이전트·규칙·훅)을 적용하기 위해선 모든 레포에 설정을 적용해주어야 했고, 모든 레포가 Claude Code 설정 동기화가 어려운 구조입니다.
목표
- 흩어진 코드베이스를 단일 모노레포로 통합해, 팀 공용 Claude 설정을 한 곳에서 적용한다.
- 누구나 동일한 컨벤션·리뷰·자동화 환경을 갖도록 하여 산출물을 균일화한다.
해결 방법과 해결 후보군
후보군 비교
| 방식 | 설명 | 한계 |
|---|---|---|
| 멀티 레포 유지 + 개인별 설정 | 각자 .claude를 개별 관리 | 설정 드리프트, 컨벤션 제각각 |
| 문서로만 컨벤션 공유 | 위키 가이드 문서 | 강제성 없음, 문서-실제 괴리 |
모노레포 + 공용 .claude 하네스 (채택) | 저장소에 하네스 내장 | clone 즉시 동일 환경, 훅으로 강제 |
1. 단일 모노레포로 통합
멀티 레포들을 하나의 저장소로 합치고, 팀 공용 .claude/ 하네스를 구성합니다.
모노레포는 AI 에이전트가 전체 영향 범위를 직접 추적할 수 있고, 컨벤션 문서를 루트 한 곳에 두면 모든 하위 프로젝트에 동일 규칙을 강제할 수 있습니다: Claude 설정 표준화에 유리한 구조입니다.
2. 이관 과정: git history 보존 점진 이관
한 번에 전부 옮기지 않고 레포 단위로 점진 이관하여 롤백 비용을 최소화했습니다.
핵심 기법:
- 히스토리 보존: 단순 복사(blame·log 유실) 대신
git subtree add(원본 커밋 보존 + 양방향 동기화로 점진 이관) 또는git filter-repo --to-subdirectory-filter(디렉토리 하위로 재작성)로 이관 - 작업 동결: 이관 시점 신규 작업 중지 → 누락 커밋 방지
- affected-only CI:
paths필터로 변경 영향 모듈만 빌드해 CI 비용 폭증 방지 - 점진 이관: 의존성 적은 레포부터 순차 이관, 각 레포 read-only 전환 후 다음으로
3. .claude 하네스 구성: 디렉토리별 역할
| 디렉토리 | 역할 | 목적 |
|---|---|---|
HARNESS.md | 하네스 진입점 + 진단 rubric (SSOT) | 전체 구조·사용법을 단일 문서로 |
onboarding.md | 팀원 5분 셋업 가이드 | 신규 합류 즉시 온보딩 |
settings.json | 권한 화이트리스트 + 훅 정의 | 위험 동작 차단·안전 게이트 |
rules/ | Kotlin/Spring 코드 작성 규칙 (controller-api · service-transaction · dto-validation · testing) | 레이어·DTO·트랜잭션·테스트 스타일 통일 (paths로 자동 로드) |
hooks/ | 12개 표준 훅 (커밋 접두사 · JVM 가드 · 인프라 write · git push 승인 · mainline merge · 시크릿 차단 · detekt/Avro 리마인더) | 컨벤션·안전을 코드로 강제 |
agents/ | 15개 전문 서브에이전트 (PRD→TDD · Jira 분해 · 백엔드 리뷰 · JPA/QueryDSL · DBA · PR 콜그래프 · Avro/OpenAPI drift · incident) | 설계·리뷰 품질 균일화 |
skills/ | 스킬 (module-router · pr-create · db-migration · kafka-tracer · self-code-review · release-tagger) | 반복 작업(PR·마이그레이션·릴리즈) 표준화 |
docs/ | conventions.md(PR/커밋/strangler/JDK 4대 룰) · ssot-map | 프로세스/머지 게이트 SSOT |
dependency-graphs/ | 생태계 의존성 정본 (HTTP/Kafka/DB) | 영향 분석 근거 |
templates/ | 회고 등 산출물 템플릿 | 문서 형식 통일 |
결과: 산출물 균일화
| 산출물 | 규칙 | 결과 |
|---|---|---|
| PR 내용 | pr-create 스킬(사내 템플릿·호환성·배포 의존성 본문) + check-commit-prefix 훅 + conventions Rule 2 | 제목 접두사, 본문 구조가 팀 전체 동일 |
| 코드 컨벤션 | rules/(controller-api·service-transaction·dto-validation) 자동 로드 + backend-engineer 에이전트 + detekt 리마인더 훅 | Controller·DTO·트랜잭션·응답 래퍼·네이밍이 일관 |
| 테스트 코드 | rules/testing.md 자동 로드(src/test/**/*.kt) | 모듈별 스택 핀(Kotest/JUnit·MockK/Mockito), given/when/then, 단위 vs 통합, fixture 관례, mock 혼용 금지 준수 |
| 리뷰·안전 | JPA/QueryDSL·PR 콜그래프·DBA 리뷰 에이전트 + git push/mainline merge/인프라 write/시크릿 차단 훅 | 리뷰 관점 통일, 위험 동작 원천 차단 |
결과적으로 팀원들이 균일한 PR·코드·테스트를 산출하게 되었습니다.
모니터링
- PR 제목 접두사·템플릿 준수율과 CI
check_pr_title.yml통과율을 관측한다. - detekt·테스트 게이트 통과율, 리뷰 지적 재발 빈도를 관측해 하네스의 표준화 효과를 점검한다.