이력서 · 포트폴리오

모노레포 전환과 팀 Claude 하네스 (산출물 표준화)

NEW8 min read

배경 및 목표

Greeting 백엔드 코드베이스가 여러 레포에 흩어져 있었습니다. 레포마다 컨벤션·리뷰 기준·자동화가 제각각이라, 팀원들이 동일한 Claude Code 설정(에이전트·규칙·훅)을 일관되게 적용하기 어려웠고, 그 결과 PR 형식·코드 스타일·테스트 방식이 사람마다 달랐습니다.

목표

  • 흩어진 코드베이스를 단일 모노레포로 통합해, 팀 공용 Claude 설정을 한 곳에서 적용한다.
  • clone만으로 누구나 동일한 컨벤션·리뷰·자동화 환경을 갖도록 하여 산출물을 균일화한다.

해결 방법과 해결 후보군

후보군 비교

방식설명한계
멀티 레포 유지 + 개인별 설정각자 .claude를 개별 관리설정 드리프트, 컨벤션 제각각
문서로만 컨벤션 공유위키 가이드 문서강제성 없음, 문서-실제 괴리
모노레포 + 공용 .claude 하네스 (채택)저장소에 하네스 내장clone 즉시 동일 환경, 훅으로 강제

1. 단일 모노레포로 통합

19개 모듈을 하나의 저장소로 합치고, 팀 공용 .claude/ 하네스를 git tracked 자산으로 저장소에 내장했습니다. clone + 환경변수 + .mcp.json 첫 승인 1회면 팀원 전원이 동일하게 동작합니다.

graph LR
    subgraph before["❌ 기존: 멀티 레포"]
        R1["레포 A"] --> D["설정 제각각"]
        R2["레포 B"] --> D
        R3["레포 C"] --> D
    end
    subgraph after["✅ 개선: 모노레포 + 공용 하네스"]
        M["모노레포<br/>(.claude 내장)"] --> T1["팀원 A"]
        M --> T2["팀원 B"]
        M --> T3["팀원 C"]
    end
    before -.->|"통합"| after

모노레포는 호출자/피호출자·인터페이스/구현이 같은 트리에 있어 AI 에이전트가 변경 영향 범위를 직접 추적할 수 있고, 컨벤션 문서를 루트 한 곳에 두면 모든 하위 프로젝트에 동일 규칙을 강제할 수 있습니다: Claude 설정 표준화에 유리한 구조입니다.

2. 이관 과정: git history 보존 점진 이관

한 번에 전부 옮기지 않고 레포 단위로 점진 이관하여 롤백 비용을 최소화했습니다.

flowchart TD
    A["① 사전 인벤토리<br/>(레포·배포 단위·외부 의존)"] --> B["② 타겟 골격 구성<br/>(디렉토리·빌드·CODEOWNERS)"]
    B --> C["③ 이관 대상 선정 (의존성 순서)"]
    C --> D["④ 작업 동결 공지"]
    D --> E["⑤ git history 보존 이관<br/>(subtree / filter-repo)"]
    E --> F["⑥ 빌드·배포 워크플로우 통합<br/>(paths 필터)"]
    F --> G["⑦ CI/CD 검증"]
    G --> H{"산출물 동등?"}
    H -->|"No"| F
    H -->|"Yes"| I["⑧ 구 레포 read-only"]
    I --> C

핵심 기법:

  • 히스토리 보존: 단순 복사(blame·log 유실) 대신 git subtree add(원본 커밋 보존 + 양방향 동기화로 점진 이관) 또는 git filter-repo --to-subdirectory-filter(디렉토리 하위로 재작성)로 이관
  • 작업 동결: 이관 시점 신규 작업 중지 → 누락 커밋 방지
  • affected-only CI: paths 필터로 변경 영향 모듈만 빌드해 CI 비용 폭증 방지
  • 점진 이관: 의존성 적은 레포부터 순차 이관, 각 레포 read-only 전환 후 다음으로

이관 시 GitHub Secrets·Environments 재구성, 모니터링·이슈 트래커의 레포 URL 갱신, 레포별로 다르던 라이브러리 버전 단일화가 동반됩니다.

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제목 접두사([GRT-]/[BE-]/[LIVEISSUE-])·본문 구조가 팀 전체 동일, strangler 변경은 영향 분석 첨부
코드 컨벤션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·코드·테스트를 산출하게 되었고, 신규 합류자도 clone 즉시 동일한 기준으로 작업할 수 있게 되었습니다.

모니터링

  • PR 제목 접두사·템플릿 준수율과 CI check_pr_title.yml 통과율을 관측한다.
  • detekt·테스트 게이트 통과율, 리뷰 지적 재발 빈도를 관측해 하네스의 표준화 효과를 점검한다.

그래프 뷰

백링크