다국어 지원 기능, 팀이 모르면 없는 거나 마찬가지
목차
이미 구현되어 있던 위젯의 다국어(i18n) 지원 기능을 CLAUDE.md에 명시적으로 기록했다. 아주 작은 변경이지만, 팀 전체의 개발 효율과 중복 방지에 생각보다 큰 영향을 미친다.
숨겨진 기능의 문제
개발 초기 단계나 프로토타입 시절에 만든 기능들 중 일부는 "당연히 있는 줄 알겠지"라고 가정하고 문서화되지 않은 채로 남곤 한다. creq widget의 다국어 지원도 그런 경우였던 것 같다. 이미 코드에는 locale-aware 로직이 들어 있었지만, 팀원들이 그것을 알 방법이 없으면 결국 그 기능은 존재하지 않는 것과 같다.
무엇보다 위험한 건 신입이나 다른 팀 멤버가 "이 위젯은 다국어 지원을 안 한다고 생각"하고 똑같은 기능을 다시 구현하는 악순환이 생긴다는 것이다. 지금까지 몇 명이 이 기능을 모른 채로 일했는지 모르겠지만, 각자 서로 다른 방식으로 i18n을 처리하거나 비슷한 기능을 중복 개발했을 가능성이 있다. 시간이 지날수록 코드는 파편화되고, 나중에 한 곳을 고치면 다른 곳은 깨진다.
문서가 인터페이스다
CLAUDE.md는 우리 팀의 "규약" 문서다. 여기에 명시되지 않은 기능은 존재하지 않는 것과 같고, 명시되면 모두가 쉽게 접근할 수 있는 공공 인터페이스가 된다. 이 커밋은 creq widget의 i18n 지원을 "공식 기능"으로 승격시킨 것이다.
이렇게 하면:
- 신입이나 새로운 팀원이 온보딩할 때 즉시 알 수 있다
- 다국어 기능이 필요한 상황에서 "이미 있는 걸 써야 하나 새로 만들까?"를 빠르게 판단할 수 있다
- 코드 리뷰에서 "오, 이 부분은 위젯의 locale-aware 기능으로 대체 가능해" 같은 조언이 가능해진다
- 같은 패턴의 다국어 처리가 팀 전체에서 일관성 있게 유지된다
작은 변경이 쌓이면
개별 개발자들이 작은 기능 하나하나를 문서화하는 게 번거롭게 느껴질 수 있다. 특히 "이미 코드로 존재하는데, 문서까지 써야 하나?" 싶을 수 있다. 하지만 팀이 커질수록 이런 문서화의 가치는 기하급수적으로 커진다.
한 명이 모르는 기능이 문제가 되고, 다섯 명이 모르면 위험이 되고, 열 명이 모르면 그것은 조직의 낭비다. 이번처럼 5분이면 끝날 문서화를 미루다 보면 나중에 비슷한 기능을 여러 번 만들고, 버그도 여러 곳에서 나고, 유지보수도 힘들어진다.
팀을 리드하면서 배운 건, 개발자들의 역량은 그들이 알고 있는 도구만큼만 발휘된다는 것이다. 아무리 좋은 기능을 만들어 놔도 팀이 모르면 쓸 수 없고, 결국 낭비다. 따라서 리더의 역할 중 하나는 팀이 뭘 할 수 있는지 명확히 알려주고, 그걸 문서화하고, 의사결정 과정에서 그 정보를 활용하도록 하는 것이다.
작은 docs 커밋이지만, 그 뒤에는 "팀의 지식을 명확히 하자"는 의도가 있다. 다음에 다국어 기능이 필요한 작업이 들어오면, 누군가 "어? 이거 이미 있다"고 빠르게 지적할 수 있을 것이다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.