리딩 기능 humanizer 레이어 재설계로 복구

처음 이 작업을 커밋했을 때와 지금의 차이를 생각해본다. Reapply라는 단어는 "한 번 시도했던 것을 다시 가져온다"는 뜻인데, 그 사이에 뭔가가 바뀌었다는 신호다. 이번에는 영문 사주 리딩 기능을 위해 humanizer 모듈을 1층과 2층으로 분리하는 구조를 다시 적용했다.

Revert와 재적용 사이의 학습

Reapply가 필요해진 상황을 되짚어보면, 보통 몇 가지 패턴이 있다. 처음 설계는 맞았는데 구현 과정에서 다른 모듈과의 인터페이스가 안 맞았을 수도 있고, 테스트 시나리오를 놓쳤을 수도 있다. 또는 다른 브랜치의 작업이 먼저 머지되면서 충돌이 발생했을 수도 있다.

이런 상황은 팀 관점에서 "설계를 다시 검증하는 기회"가 된다. 처음에 좋다고 생각한 것이 정말 맞는지, 어떤 부분에서 실패했는지를 냉정하게 분석할 수 있기 때문이다. 특히 아키텍처 결정 같은 것은 한 번 정해진 후에 바꾸기 어려우므로, 이렇게 다시 한 번 점검할 수 있는 게 소중하다.

humanizer의 1층과 2층: 왜 분리하나

이번 커밋에서 변경된 두 파일을 보자:
- src/lib/humanizer.ts: humanizer의 핵심 로직
- src/lib/reading.ts: reading 도메인 기능

humanizer의 역할은 데이터를 사람이 읽을 수 있게 변환하는 것이다. 사주 같은 복잡한 도메인에서는 이 변환이 여러 단계를 거친다:

이렇게 나누는 이유는 책임 분리와 재사용성이다. 1층은 데이터 구조 변환만 담당하고, 2층은 표현만 담당하면:

• 동일한 중간 형식을 여러 언어로 렌더링할 수 있다 (영문, 일문, 중문 등)
• 1층을 변경해도 2층 인터페이스가 안정적이다
• 각 레이어를 독립적으로 테스트할 수 있다

예를 들어:

// 1층: 원시 데이터 → 중간 형식
const parsed = humanizer.parse(rawData); // { stem: 'wood', branch: 'tiger', ... }

// 2층: 중간 형식 → 사용자용 텍스트
const text = humanizer.render(parsed, 'en'); // "Wood Tiger: represents growth and ambition..."

reading.ts에서의 변경은 아마도 이 새로운 호출 방식을 반영하고, parse 결과를 어떻게 활용할지 정리한 것으로 보인다.

다시 적용할 때 체크한 것들

Reapply 상황이 생기면, 단순히 코드를 다시 푸시하는 게 아니라 몇 가지를 반드시 확인해야 한다:

• 이전 Revert의 근본 원인을 파악한다. Git log를 뒤져서 충돌의 진짜 이유가 뭐였는지, 그게 정말 해결됐는지 확인해야 한다.
• 팀이 이 설계를 이해하는지 확인한다. humanizer의 1층+2층 분리는 강력하지만, 문서나 주석이 없으면 나중에 누군가 헷갈릴 수 있다.
• 테스트 커버리지를 다시 본다. 특히 1층과 2층의 경계에서 데이터 흐름을 제대로 테스트했는지 확인이 필수다.
• 다른 변경사항과의 충돌을 재확인한다. 이전과 지금 사이에 main 브랜치에 뭐가 머지됐는지 확인하고, 의존성 문제가 없는지 본다.

팀 커뮤니케이션 관점에서

리딩 같은 도메인 기능을 한두 사람이 주도하다 보면, 나머지 팀원들이 전체 구조를 놓치기 쉽다. 이번 humanizer 레이어 분리는 기술적으로 좋은 결정이지만, 그게 왜 필요했고, 앞으로 비슷한 기능을 어떻게 설계할지는 커밋만으로는 전달되지 않는다.

가능하면:
- 코드 리뷰에서 의도를 명시적으로 설명한다. "1층+2층으로 분리한 이유"를 주석이나 설명으로 남긴다.
- 비슷한 도메인 기능 추가 시 같은 패턴을 따르도록 한다. 다음에 타로 카드 리딩이나 점성술 같은 걸 추가할 때도 같은 레이어 구조를 써야 시스템이 일관성 있게 커진다.
- 팀 내에서 가이드를 공유한다. "우리는 리딩 도메인에서 humanizer를 이렇게 쓴다"를 문서화하면, 온보딩도 쉽고 유지보수도 낫다.

이번 Reapply를 통해 느낀 건데, 처음부터 완벽하게 하려고 하기보다는, 한 번 시도했을 때 뭐가 안 되는지 보고 다시 설계하는 게 오히려 더 튼튼한 아키텍처를 만드는 것 같다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.