팀 탐색 기능 정책을 공식 문서에 기록하다

CLAUDE.md에 팀/그룹 발견(discover_groups) 기능의 강화 사항을 문서로 남겼다. 개발 코드는 한 줄도 짜지 않은 작업이지만, 팀 리딩 입장에서는 꽤 중요한 일이었다.

팀 규모가 커질 때 문서화가 필요한 이유

프로젝트 초기에는 모든 게 구두로 통한다. 팀원 3명이 슬랙에서 "어, 이 기능은 이렇게 쓰는 거야" 하고 넘어간다. 하지만 팀이 5명, 10명으로 늘어나면 다르다.

새로 온 팀원이 "우리 팀에서는 그룹 조회를 어떻게 처리하는 게 표준인가요?"라고 물었을 때, 매번 입으로 설명할 수는 없다. 그리고 6개월 전에 정한 정책을 누군가는 까먹고, 누군가는 다르게 이해하고 있을 가능성이 높다. 그게 버그로, 보안 이슈로, 불필요한 토론으로 반복된다.

discover_groups 기능도 비슷했다. 이것이 언제 어떤 조건에서 호출돼야 하는지, 어떤 접근 권한이 필요한지, 캐싱은 어떻게 할지 같은 세부사항들이 아직 팀 내에 흩어져 있었다. 일부는 코드 리뷰에서 논의되고, 일부는 테스트에만 남아 있고, 일부는 누군가의 머리속에만 있었다.

CLAUDE.md에 기록하는 것의 의미

우리 팀에서 CLAUDE.md는 단순한 노트가 아니다. 이건 "이 프로젝트/팀에서의 단일 진실(single source of truth)" 역할을 한다.

• 온보딩: 신입이 들어오면 CLAUDE.md를 먼저 읽게 된다. 여기서 팀 문화, 코드 스타일, 정책들을 한눈에 파악할 수 있다.
• 의사결정: "우리 방식이 뭐였더라?"라고 할 때 CLAUDE.md를 참고한다. 일관성을 유지하는 기초.
• 감시 장치: "요구사항과 현실이 어긋난다"는 걸 파악하기 위해서도, 문서가 있어야 비교 대상이 된다.

discover_groups 기능을 CLAUDE.md에 추가한다는 건, 이 기능과 관련된 의사결정들을 팀 전체가 볼 수 있는 공간으로 끌어올리는 것이다.

발견(discovery) 기능이 중요한 이유

팀, 그룹, 사용자 간의 "탐색" 기능은 보안과 UX가 만나는 지점이다.

• 접근 제어: 누가 어떤 그룹을 볼 수 있는가? 관리자만? 같은 팀 멤버? 전체 공개?
• 성능: 그룹 리스트가 커질 때 쿼리를 어떻게 최적화할 건가?
• 캐싱: 팀 구조는 자주 바뀌지 않으니 캐시를 써도 되지 않을까?

이런 각각의 작은 결정들이 모여서 시스템의 안정성과 확장성을 결정한다. 그리고 이 결정들을 일관되게 유지하려면 문서화가 필수다.

회고: 문서화도 기술 부채를 줄이는 일이다

처음엔 "docs 업데이트는 우선순위 낮은 작업 아닌가?"라고 생각했을 수도 있다. 하지만 팀 리딩을 하다 보니 깨달았다.

문서화 안 한 기능 = 매번 같은 설명을 반복하는 비용

코드 리뷰에서 "왜 이렇게 했어요?"라는 질문이 반복되는 건, 그 의도가 문서화되지 않았다는 신호다. 그걸 방치하면:
- 리뷰어도 매번 배경을 다시 이해해야 함
- 구현자도 매번 "맞나?" 하고 고민함
- 신입은 "표준이 뭔가요?" 하고 물음

CLAUDE.md에 discover_groups의 정책을 명시함으로써, 이런 반복 비용을 줄였다. 다음 번에 비슷한 기능을 만들 때는 "어, CLAUDE.md에 보면 우리 팀의 패턴이 있네"라고 참고할 수 있다.

팀이 스케일링되는 과정에서 문서화는 코드보다 먼저 필요할 때가 있다. 왜냐하면 문서는 개발자들의 시간을 절약해주는 가장 비용-효율적인 도구이기 때문이다.

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

• 모니터 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 노이즈캔슬링헤드폰 쿠팡에서 보기 →

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