배경 및 목표
팀에 Claude Code 하네스를 도입하려는 목표가 있었습니다. 백엔드 코드베이스가 여러 레포로 흩어져 있어 하네스를 적용하기 위한 전제 조건으로 코드베이스를 먼저 하나로 합쳐야 했습니다.
왜 중요했는가
동일한 설정(에이전트, 규칙, 훅)을 적용하려면 모든 레포에 같은 작업을 반복해야 하고, 이후 동기화 문제도 계속 남습니다. 또한 LLM이 전체 코드베이스를 한 번에 파악하고, 여러 레포에 걸친 작업을 하나의 Pull Request로 처리할 수 있게 하려는 목적도 있었습니다.
제약
| 제약 | 선택지에 미친 영향 |
|---|---|
| 이관 중 팀 작업 중단 최소화 | 한 번에 전부 옮기는 빅뱅 이관은 그 기간 전체 개발이 멈춥니다. 레포 단위 점진 이관을 택한 이유입니다. |
| CI 비용 증가 위험 | 모노레포는 변경 하나에 전체 빌드가 돌기 쉽습니다. paths 필터로 영향 모듈만 빌드하도록 제약을 먼저 걸었습니다. |
목표
- 흩어진 코드베이스를 단일 모노레포로 통합해 팀 공용 설정을 한 곳에서 적용할 수 있게 만듭니다.
- 이관 과정에서 팀 작업 중단을 최소화합니다.
맡은 역할과 판단
| 구분 | 내용 |
|---|---|
| 담당 범위 | 이관 대상 레포 조사와 점진 이관 방식 수립을 담당했습니다 |
| 직접 내린 판단 | 1. 빅뱅 이관 대신 의존성 적은 레포부터 순차 이관 2. affected-only CI로 비용 통제 |
| 협업, 합의 | 이관 방식을 DevOps 팀에 제안해 합의한 뒤 진행했습니다 |
해결 방법과 해결 후보군
후보군 비교
| 방식 | 설명 | 한계 |
|---|---|---|
| 멀티 레포 유지 | 레포마다 공용 설정을 개별 관리 | 설정 드리프트, 레포 수만큼 반복 작업 |
| 레포별 설정 동기화 자동화 | 스크립트로 각 레포에 설정 배포 | 레포 수에 비례해 실패 지점 증가, 원본이 여전히 분산 |
| 단일 모노레포로 통합 (채택) | 코드베이스를 한 저장소로 합침 | clone 한 번으로 동일 환경, 설정 원본이 한 곳 |
1. 단일 모노레포로 통합
멀티 레포들을 하나의 저장소로 합쳐, 팀 공용 설정을 한 곳에서 적용할 수 있는 구조를 만듭니다.
모노레포는 AI 에이전트가 전체 영향 범위를 직접 추적할 수 있고, 컨벤션 문서를 루트 한 곳에 두면 모든 하위 프로젝트에 동일 규칙이 적용됩니다. 하네스를 이용하기에 유리한 구조입니다.
2. 이관 과정: git history 보존 점진 이관
한 번에 전부 옮기지 않고 레포 단위로 점진 이관하여 롤백 비용을 최소화했습니다.
- 작업 동결: 이관 시점 신규 작업 중지하여 누락 커밋 방지
- affected-only CI:
paths필터로 변경 영향 모듈만 빌드해 CI 비용 방지 - 점진 이관: 의존성 적은 레포부터 순차 이관, 각 레포 읽기 전용 전환
결과
| 항목 | 기존 | 개선 |
|---|---|---|
| 코드베이스 | 여러 레포로 분산 | 단일 모노레포 |
| 공용 설정 원본 | 레포마다 개별 관리 | 한 곳에서 관리 |
| 이관 방식 | - | 의존성 적은 레포부터 순차 이관, 단계별 롤백 지점 확보 |
| CI | 전체 빌드 위험 | 변경 영향 모듈만 빌드 |
이 전환으로 팀이 목표하던 Claude 하네스를 한 곳에 적용할 수 있는 전제가 마련됐습니다. 하네스 구성과 그로 인한 산출물 변화는 이 작업의 범위 밖입니다.