아이콘 라이브러리 통일, 문서에 명시하다

CLAUDE.md에 아이콘 정책을 명시하는 커밋을 했다. 팀이 쓸 프로젝트 지침서에 아이콘 라이브러리 룰을 추가한 것인데, 한두 줄 추가지만 팀 효율성과 일관성 측면에서 꽤 의미 있는 작업이었다.

배경: 아이콘 선택에서 자꾸 튀는 일관성

프로젝트를 진행하면서 UI 컴포넌트에 아이콘을 붙여야 하는 순간이 자주 온다. 버튼의 액션 아이콘, 네비게이션 바의 메뉴 아이콘, 폼의 상태 표시 아이콘, 에러 메시지의 경고 아이콘 등등. 그런데 팀원들이 아이콘을 선택할 때 제각각이었다. 어떤 라이브러리를 써야 하는지, 어떤 스타일의 아이콘이 우리 디자인 시스템과 맞는지 명확한 기준이 없었다.

코드리뷰할 때 이런 피드백이 자주 나왔다:
- "아, 이 아이콘 라이브러리는 우리가 안 쓰는데?"
- "이 아이콘 스타일이 다른 곳이랑 좀 안 맞는데요."
- "아이콘 선택 기준이 있나요?"

팀원 입장에서도, 리뷰어 입장에서도 불편했다. 개발자는 "뭘 쓰는 게 맞지?" 하면서 시간을 낭비하고, 리뷰어는 매번 같은 지적을 반복해야 했다. 새로 온 팀원이 온보딩될 때도 이런 질문이 꼭 나왔다. 사소해 보이지만 누적되면 팀 효율성에 영향을 준다.

CLAUDE.md에 아이콘 정책 명시

결국 팀 내 논의를 거쳐 Iconoir를 현재 표준 아이콘 라이브러리로 삼고, 이를 CLAUDE.md에 명시하기로 했다.

# 아이콘 = 오픈소스 SVG(Iconoir 현 사용)

모든 UI 컴포넌트의 아이콘은 Iconoir를 사용한다.
다른 라이브러리가 필요한 경우는 팀 리뷰를 거쳐 결정한다.

말 그대로 한두 줄이지만, 이 간단한 명시가 코드리뷰에서 불필요한 논쟁을 없앤다. 이제 모든 팀원과 새 온보더들이 일관되게 같은 라이브러리를 참고한다. "아이콘은 뭘 써요?" 질문도 문서를 보면 답이 나온다.

팀 지침 문서화의 힘

이런 작은 규칙들이 모여서 팀 문화와 개발 생산성을 만든다는 걸 다시 한 번 느꼈다.

문서에 명시된 규칙이 있으면 몇 가지가 달라진다:

1. 온보딩이 빨라진다 — 새 팀원이 궁금한 게 있으면 문서를 먼저 본다. "누구에게 물어봐야 하나" 하는 시간 낭비가 줄어든다. 특히 리모트 팀에서는 이게 정말 중요하다.

2. 코드리뷰 효율성이 올라간다 — 리뷰어는 개인 의견이 아니라 "공식 규칙"을 근거로 피드백한다. 훨씬 명확하고, 감정적 충돌도 줄어든다. "제 생각엔 이게 낫다"는 톤이 아니라 "이게 규칙이다"는 톤이 되니까.

3. 일관성이 자동으로 보장된다 — 모두가 같은 기준을 따르니까 UI는 일관되고, 새 개발자도 같은 관례를 빠르게 학습한다. 복잡한 설명 없이.

4. 의사결정이 기록된다 — Iconoir를 선택한 이유, 다른 옵션을 배제한 이유 등이 나중에 필요하면 팀 내 논의 기록으로 남아 있다. 6개월 뒤 "왜 이걸 쓰기로 했더라?" 하는 질문에 근거를 가지고 대답할 수 있다.

마무리: 작은 규칙, 큰 효과

이 커밋은 어떻게 보면 아주 작은 변경이다. CLAUDE.md에 한두 줄 추가했을 뿐이다. 하지만 경험상 이런 규칙이 명시되지 않으면 계속 같은 질문이 반복되고, 일관성이 떨어지고, 리뷰 의견이 흔들린다.

팀을 리드하면서 배운 점 중 하나는, 기술적 결정뿐 아니라 "누가 뭘 하는지" 같은 프로세스 규칙도 문서에 남기는 게 팀의 확장성을 결정한다는 것이다. 한 명이 모든 걸 기억할 순 없고, 팀이 커질수록 문서가 팀의 유일한 단일진실이 된다.

다음번에 아이콘이 필요할 때, 누군가는 Iconoir를 열고, 누군가는 CLAUDE.md를 참고할 거다. 그리고 팀의 UI는 더 일관되고, 리뷰는 더 명확해질 것이다.

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

• 사무의자 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →
• 커피머신 쿠팡에서 보기 →

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