# 30. 사례 회고: 여러 저장소 라이브러리·아키텍처 일관성 정렬

## 0. 먼저 알고 가기 (30초 요약)

- 비슷한 스택을 쓰는 여러 저장소가 세부에서 갈라질 때, 카테고리마다 표준 하나로 다시 모은 과정을 기록한 회고입니다.
- 표준은 공유 발행 config 패키지로 한 곳에서 정의하고, 서술 근거는 개발가이드에, 적용은 저장소별 작은 PR로 나눠 넣었습니다.
- 각 PR은 타입체크·린트·테스트·빌드를 통과한 뒤에만 합쳐, 일관성을 얻으면서 회귀를 막았습니다.

## 초심자용 한눈에 보기

여러 저장소가 같은 도구를 조금씩 다른 버전·다른 라이브러리로 쓰면, 저장소를 옮길 때마다 같은 문제를 다른 방식으로 풀게 됩니다. 이 회고는 그렇게 벌어진 차이를 어떻게 좁혔는지, 어떤 순서가 안전했는지, 그리고 옮기는 도중 무엇이 발목을 잡았는지를 한 문서에 모읍니다.

핵심 메시지는 단순합니다. 표준을 글로만 정하면 시간이 지나며 다시 어긋나므로, 표준 자체를 설치 가능한 패키지로 만들어 의존성으로 묶고, 바꾸는 일은 검증 게이트가 달린 작은 단위로 쪼개 넣어야 한다는 것입니다.

### 핵심 용어 빠르게 정리

| 용어            | 쉬운 뜻                                                             |
| --------------- | ------------------------------------------------------------------- |
| `드리프트`      | 처음엔 같던 설정·버전이 시간이 지나며 저장소마다 벌어지는 현상      |
| `스택형 PR`     | 한 변경을 작은 단위로 쪼개 차례로 쌓아 올리는 PR 묶음               |
| `verify 게이트` | 타입체크·린트·테스트·빌드를 한 번에 돌려 통과해야 머지하는 관문     |
| `발행 config`   | 표준 설정을 npm 패키지로 만들어 여러 저장소가 의존으로 당겨 쓰는 것 |
| `silent no-op`  | 설정이 틀려도 에러 없이 그냥 동작을 안 하는 위험한 상태             |

| 분류            | 핵심 기술                                                                                                     | 상태          | Stable    |
| :-------------- | :------------------------------------------------------------------------------------------------------------ | :------------ | :-------- |
| **연관 가이드** | [29. 표준 라이브러리 스택](./29_표준_라이브러리_스택_가이드.md), [22. 모노레포](./22_모노레포_운영_가이드.md) | **회고 기록** | 사례 중심 |
| **핵심 테마**   | 카테고리별 표준 수렴, 공유 config 메커니즘, 검증 게이트 롤아웃, 옮기며 만난 함정                              | **Update**    | 최신 기준 |

---

> **"일관성은 한 번의 대청소가 아니라, 다시 어긋나지 않게 만드는 장치로 지킨다."**
> 이 문서는 여러 저장소를 같은 표준으로 모으며 거친 결정과 순서, 그리고 옮기는 도중 부딪힌 함정을 사례로 정리합니다. 같은 작업을 다른 저장소에서 반복할 때 길잡이로 씁니다.

---

## 문서 책임 범위

| 이 문서가 결정하는 것                 | 단일 출처로 따르는 문서                                                                                          |
| :------------------------------------ | :--------------------------------------------------------------------------------------------------------------- |
| 일관성 정렬을 진행한 순서와 회고 교훈 | [29. 표준 라이브러리 스택](./29_표준_라이브러리_스택_가이드.md)                                                  |
| 카테고리별 표준 자체                  | [29. 표준 라이브러리 스택](./29_표준_라이브러리_스택_가이드.md), [05. API 통신](./05_API_통신_및_모킹_가이드.md) |
| 폴더 구조·계층 경계 정의              | [04. 아키텍처](./04_아키텍처_설계_패턴.md)                                                                       |
| 버전 정렬·릴리스 경계                 | [11. CI/CD](./11_CICD_파이프라인_표준.md), [22. 모노레포](./22_모노레포_운영_가이드.md)                          |

---

## 0. 모든 프론트엔드 그룹 공통 Baseline

| 기준                  | 최소 적용                                                                |
| :-------------------- | :----------------------------------------------------------------------- |
| **표준은 설치형으로** | 도구 표준은 글이 아니라 의존 가능한 패키지로 정의해 드리프트를 막습니다. |
| **변경은 작게**       | 큰 전환도 저장소별 작은 PR로 쪼개 검증한 뒤 합칩니다.                    |
| **머지 전 검증**      | 타입체크·린트·테스트·빌드를 모두 통과한 PR만 머지합니다.                 |
| **경계는 린트로**     | 폴더 계층 의존 방향은 사람 눈이 아니라 린트로 확인합니다.                |
| **함정은 문서로**     | 옮기며 만난 함정은 회고에 적어 다음 저장소에서 다시 밟지 않게 합니다.    |

### 0.1 교차 검증 매트릭스

| 권고                                   | 1차 출처                        | 실행 증거                      | 운영 증거               | 철회 조건                                  |
| :------------------------------------- | :------------------------------ | :----------------------------- | :---------------------- | :----------------------------------------- |
| 표준은 공유 발행 config로 정의한다     | 패키지 매니저 워크스페이스 문서 | 패키지 설치·해석 테스트        | 설정 드리프트 재발 횟수 | 저장소가 하나뿐이라 공유 비용이 더 클 때   |
| 전환은 verify 게이트 통과 후 머지한다  | 각 도구 공식 문서               | 타입체크·테스트·빌드 로그      | 머지 후 회귀 발생률     | 변경이 사소해 게이트 비용이 효용을 넘을 때 |
| 의존 방향은 boundaries 린트로 강제한다 | eslint-plugin-boundaries 문서   | 의존 위반을 일부러 만든 점검   | 구조 회귀 PR 수         | 단일 모듈 규모라 계층 구분이 불필요할 때   |
| 함정은 회고 문서에 즉시 기록한다       | 내부 회고 관행                  | 다음 저장소에서 재현 여부 확인 | 같은 함정 반복 횟수     | 함정이 일회성이고 재현 가능성이 없을 때    |

### 0.2 운영 게이트

| Gate           | Evidence                    | Owner       | Rollback                     |
| :------------- | :-------------------------- | :---------- | :--------------------------- |
| 표준 정의 변경 | 패키지 버전 diff, 변경 로그 | 플랫폼 오너 | 이전 config 버전으로 핀 복원 |
| 저장소 전환 PR | verify 로그, 동작 스모크    | 저장소 오너 | 전환 커밋 되돌리기           |
| 구조 경계      | boundaries 린트 리포트      | FE 오너     | 위반 import 되돌리기         |
| 버전 정렬      | catalog diff                | 플랫폼 오너 | 이전 버전 핀 복원            |

---

## 1. 이번 정렬에서 통일한 것

### 1.1 카테고리별로 모은 표준

저장소마다 다르던 항목을 카테고리 단위로 하나씩 골라 모았습니다. 표준 라이브러리의 선택 이유는 [29번 가이드](./29_표준_라이브러리_스택_가이드.md)에 따로 정리했고, 여기서는 "무엇을 무엇으로 모았는가"만 요약합니다.

| 카테고리        | 모으기 전 (저장소별로 갈림)           | 모은 표준                      |
| :-------------- | :------------------------------------ | :----------------------------- |
| 브라우저 HTTP   | 서로 다른 클라이언트와 raw fetch 혼재 | ky 공유 인스턴스               |
| 백엔드 DTO 검증 | 데코레이터 기반 검증과 zod 혼재       | shared zod + nestjs-zod        |
| 포맷·린트       | 저장소마다 다른 규칙·일부는 다른 린터 | 공유 Prettier·ESLint config    |
| 폴더 구조       | 평면 features·다른 계층 명명 혼재     | domains 코로케이션 + 경계 린트 |
| 의존성 버전     | 손으로 올려 어긋난 핀                 | catalog로 묶은 단일 버전       |

### 1.2 다시 어긋나지 않게 만든 장치

표를 한 번 맞추는 것만으로는 시간이 지나면 다시 갈라집니다. 그래서 표준 정의를 세 겹의 장치로 고정했습니다. 첫째는 설치 가능한 공유 config 패키지로, 규칙을 한 곳에서 고치면 의존하는 저장소가 함께 따라옵니다. 둘째는 서술적 근거를 담는 개발가이드로, 왜 그 표준을 골랐는지와 언제 철회하는지를 적습니다. 셋째는 머지 전 verify 게이트로, 표준에 맞췄다는 주장 대신 통과한 로그를 증거로 삼습니다.

---

## 2. 회고: 통한 것과 어려웠던 것

전환을 작은 PR로 쪼갠 결정은 회귀를 줄이는 데 가장 크게 기여했습니다. 한 PR이 한 카테고리만 건드리니 리뷰 범위가 좁아지고, 문제가 생겨도 되돌릴 단위가 분명했습니다. 반대로 어려웠던 부분은 대부분 "에러 없이 조용히 동작만 안 하는" 설정에서 나왔습니다. 경계 린트는 리졸버와 적용 범위 설정이 빠지면 위반을 잡지 못한 채 통과하므로, 일부러 위반을 만들어 룰이 실제로 운다는 것을 확인하는 점검을 매번 넣어야 안전했습니다.

라이브러리를 바꿀 때는 겉보기 API뿐 아니라 에러를 다루는 방식까지 확인해야 했습니다. HTTP 클라이언트를 옮기는 과정에서, 새 클라이언트가 응답 본문을 미리 소비해 두는 동작 때문에 기존 에러 계약과 모양이 달라지는 경우가 있었고, 외부 서비스로 나가는 요청은 인증 헤더가 새지 않도록 공유 인스턴스를 거치지 않게 분리해야 했습니다. 공유 config 또한 모든 규칙을 강제로 켜기보다, 저장소 성격에 따라 선택해서 켤 수 있도록 일부를 opt-in으로 분리한 편이 채택을 매끄럽게 했습니다. 의존성 충돌은 저장소별로 범위를 좁힌 override로 막되, 그 이유를 짧게 남겨 다음 사람이 영문을 모른 채 지우지 않도록 했습니다.

---

## 추천 항목 (실무 우선순위)

- **시작 추천**: 표준 표를 먼저 확정하고, 저위험 항목(버전 정렬·패키지명 교체)부터 한 카테고리씩 PR로 옮깁니다.
- **안정 추천**: HTTP·검증처럼 동작이 바뀌는 교체는 테스트와 스모크를 함께 붙여 한 PR로 넣습니다.
- **운영 추천**: 경계 린트와 공유 config 의존으로 고정해, 손으로 다시 맞추지 않아도 되게 만듭니다.

## 추천 항목 고도화 체크

- `즉시 적용` — 추천 항목 1개를 이번 주 내에 실제 작업 1건에 반영한다.
- `1주 내 정리` — 적용 결과를 PR 본문이나 회고 노트에 간단히 기록한다.
- `1개월 내 점검` — 재작업률/리뷰 충돌/배포 이슈 중 적어도 한 항목이 개선되었는지 확인한다.

## 추천 항목 실행 기록 템플릿

- `담당자` : 항목 적용 주체(문서 오너/팀원)를 명시
- `적용일` : 실제 반영된 날짜 및 작업 ID를 남김
- `측정 지표` : 리뷰 충돌/재작업/버그 재발 중 1개 이상 수치로 기록
- `보류 사유` : 적용을 못한 경우 이유를 1줄 기록하고 다음 액션을 지정

## 추천 항목 실행 우선순위 매핑

- `P1(7일 내)` — 추천 항목 1개를 우선 적용하고 1회 사용자 관측 신호(에러율/실패율/지연)와 연결한다.
- `P2(30일 내)` — 추천 항목 1개를 팀 내 표준/템플릿에 반영해 재사용성을 확보한다.
- `P3(90일 내)` — 추천 항목 1개를 다른 관련 문서에 역링크로 연동해 중복 작업을 줄인다.
- `완료 기준` — 각 항목별 산출물(예: PR 링크/체크리스트/회고 노트)을 1개 이상 남긴다.

## 추천 항목 실행 체크리스트

- [ ] `1단계(7일)` : 추천 항목 1개를 실제 작업으로 전환
- [ ] `2단계(30일)` : 전환 결과를 팀 산출물(ADR/PR/체크리스트)에 반영
- [ ] `3단계(60일)` : 정적 지표 1개 이상으로 효과 검증
- [ ] `문제 대응` : 미달성 시 보류 사유와 다음 실행 액션을 문서화

## 추천 항목 실행 운영 규칙

- `실행 게이트` : 위험, 비용, 기대 효과가 1회 이상 정량화되어야 적용한다.
- `승인 체계` : 적용 전 사전 승인자(팀 리드/보안/운영)와 rollback 담당자를 확인한다.
- `리스크 점수` : 1~5 등급으로 현재 위험도를 기록하고 정량 기준을 남긴다.
- `리더 승인자` : 최종 승인 책임자(예: 팀 리드/PO/보안리더)를 명시한다.
- `승인 역할` : 승인자, 실행자, 모니터링 주체 역할을 분리해 적는다.
- `재개 조건` : 실패 신호가 기준치 이내로 돌아오면 다음 단계로 확장한다.
- `정지 조건` : 회귀 지표 악화가 1개 이상이면 즉시 중단하고 보류 사유를 갱신한다.
- `재평가 주기` : 최소 2주 단위로 상태를 리뷰하고 조정한다.

---

## 실무 적용 가이드

### 언제 이 문서를 펼칠까

- 비슷한 스택의 저장소가 여러 개인데 도구·버전이 서로 갈라지기 시작할 때
- 한 카테고리를 표준으로 모으는 전환을 어디서부터 어떤 순서로 할지 정해야 할 때
- 이전에 옮기며 부딪힌 함정을 다음 저장소에서 다시 밟지 않으려 할 때

### 적용 순서

1. 대상 저장소들의 현재 라이브러리·버전을 카테고리별로 한 표에 모은다.
2. 표준과 다른 항목을 골라 위험도(동작 변경 여부)로 줄을 세운다.
3. 저위험 항목부터 한 카테고리씩 작은 PR로 옮기고 verify를 통과시킨다.
4. 동작이 바뀌는 교체는 테스트·스모크를 함께 붙여 한 PR로 넣는다.
5. 마지막에 공유 config 의존과 경계 린트로 고정해 재발을 막는다.

### 함께 두는 파일

- 공유 설정 의존: 각 저장소의 `package.json`과 `eslint.config.mjs`
- HTTP 공유 인스턴스: `src/infrastructure/http/`
- 버전 단일화: 워크스페이스 `catalog` 정의

### 흔한 실수

- 표를 한 번 맞추고 끝내, 시간이 지나며 다시 손으로 어긋난다.
- 경계 린트의 리졸버·적용 범위를 빠뜨려 위반을 못 잡은 채 통과시킨다.
- 라이브러리 교체에서 에러 처리·외부 요청 경로 차이를 놓쳐 계약이 깨진다.
- 큰 전환을 한 PR에 몰아 리뷰와 롤백 단위가 흐려진다.

### PR 완료 기준

- [ ] 변경한 카테고리가 표준 가이드와 일치한다
- [ ] typecheck·lint·test·build가 모두 통과한다
- [ ] 동작이 바뀌는 교체는 테스트나 스모크로 확인했다
- [ ] 버전은 catalog 또는 공통 기준에 맞춰 정렬했다