[TYPESCRIPT] 타입 규칙 운영 전략: 고급 제네릭을 팀 단위로 유지·공유하는 방법

 

고급 제네릭 패턴을 프로젝트에 잘 적용했다고 해서 바로 “좋은 타입 설계”가 완성되는 것은 아닙니다. 실제 운영 단계에서는 또 다른 문제가 등장합니다.

 

• 이 타입은 왜 이렇게 생겼는지 아무도 설명하지 못한다
• 새로운 팀원이 오면 타입부터 이해하는 데 시간이 걸린다
• 비슷한 제네릭 패턴이 조금씩 다른 형태로 늘어난다
• 리뷰에서 타입 설계는 늘 뒷순위로 밀린다

 

이 시점의 문제는 기술 난이도가 아니라 타입 규칙을 어떻게 팀 자산으로 관리하느냐에 가깝습니다. 이번 글에서는 고급 제네릭을 “개인 기술”이 아니라 “팀 규칙”으로 만드는 방법을 정리합니다.

 

개념/배경 설명: 타입은 왜 팀에서 무너지기 쉬운가

타입은 코드 중에서도 가장 빨리 복잡해지는 영역입니다. 그 이유는 명확합니다.

• 동작에는 직접적인 영향을 주지 않는다
• 당장 급한 기능 개발에서 우선순위가 밀린다
• 암묵적인 합의에 기대는 경우가 많다

 

그래서 타입 설계는 문서로만 남기면 실패하기 쉽고, 구두로만 공유하면 금방 흐려집니다. 실무에서는 타입 규칙을 코드 자체로 고정해야 합니다.

 

고급 제네릭은 전용 영역에 모은다

팀 단위에서 가장 먼저 해야 할 일은 “제네릭 패턴이 흩어지지 않게 하는 것”입니다.

 

// src/shared/types/compositions.ts
export type WithAudit<T> = T & {
  audit: {
    requestId: string;
    timestamp: number;
  };
};

export type ServiceResult<T> =
  | { ok: true; data: T }
  | { ok: false; errorCode: string };

 

이렇게 모아두면,

• 새로운 패턴이 생길 때 위치가 명확해지고
• 중복된 제네릭이 생기는 것을 막을 수 있으며
• 타입 자체가 하나의 라이브러리처럼 관리됩니다

 

실무 포인트 정리

• 고급 제네릭은 shared 영역에만 둔다
• 도메인/기능 폴더 안에 흩어두지 않는다
• “어디에 추가해야 하는지”가 명확해야 한다

 

타입 이름을 규칙으로 강제한다

고급 제네릭에서 가장 중요한 것은 이름입니다. 이름이 곧 문서이기 때문입니다.

 

실무에서 유용한 네이밍 기준은 다음과 같습니다.

• WithX: 무언가를 추가하는 타입
• AsX: 형태를 변환하는 타입
• Result / Response: 흐름 제어 타입

 

// 좋은 예
type WithPermission<T> = T & { canEdit: boolean };

// 피해야 할 예
type Decorated<T> = T & { flag: boolean };

 

이 기준이 없으면, 타입은 금방 의미 없는 별칭의 집합이 됩니다.

 

타입 규칙을 코드 리뷰 기준에 포함시킨다

타입 설계가 유지되려면, 리뷰에서 반드시 다뤄져야 합니다.

 

리뷰 시 다음 질문을 기준으로 삼는 것이 효과적입니다.

• 이 제네릭은 기존 패턴으로 표현할 수 없는가?
• 이 Compose 순서는 팀 기준과 일치하는가?
• 타입 이름만 보고 의도를 이해할 수 있는가?
• 도메인 타입에 불필요한 제네릭이 들어가 있지 않은가?

 

이 질문들이 반복되면, 팀 내에서 자연스럽게 타입 감각이 맞춰집니다.

 

타입 사용 예제를 “정답 코드”로 둔다

문서보다 강력한 것은 예제 코드입니다.

 

// 권장 사용 예
type UserResponse =
  ServiceResult<WithAudit<Readonly<User>>>;

 

이런 예제를 shared 영역이나 README 수준에 남겨두면,

• 새로운 타입을 만들 때 기준점이 생기고
• 리뷰에서 “왜 이렇게 안 썼나요?”라는 질문이 가능해집니다

 

운영/실무에서 자주 겪는 문제

• 고급 제네릭을 이해하는 사람이 한 명뿐인 경우
• 타입 규칙이 문서에만 있고 코드에는 반영되지 않은 경우
• 리뷰에서 타입은 항상 “나중에 보자”가 되는 상황
• 비슷한 제네릭이 조금씩 다른 이름으로 늘어난 구조

 

이 문제들은 모두 타입을 “개인 역량”으로 취급했을 때 발생합니다.

 

실무 권장 체크리스트

• 고급 제네릭이 한 곳에 모여 있는가
• 타입 네이밍 규칙이 암묵적이지 않은가
• 리뷰에서 타입 설계를 실제로 확인하는가
• 정답으로 삼을 수 있는 예제 타입이 존재하는가
• 새로운 팀원이 타입 구조를 따라갈 수 있는가

 

---

 

 

고급 제네릭은 잘 쓰면 강력하지만, 관리되지 않으면 가장 먼저 기술 부채가 됩니다.

규칙을 코드로 고정하고, 위치를 제한하고, 리뷰 기준으로 반복 확인하는 것. 이 세 가지가 갖춰질 때, 고급 제네릭은 팀의 부담이 아니라 생산성을 높이는 공통 언어가 될 것 입니다.