암묵지를 살아 있는 팀 컨벤션으로 만드는 법

출처 및 AI 안내: 이 글은 제미니의 개발실무 유튜브를 기반으로 작성되었습니다. gpt-5.6-sol 모델을 사용해 생성·편집했습니다.

한 개발자가 개인 시간까지 써서 팀 컨벤션을 정리했을 때 동료들의 반응은 미지근했다. 시간이 지나 오래 일한 담당자가 갑자기 퇴사했고, 작성자는 이미 다른 팀으로 옮겼으며, 프로젝트가 바쁜 와중에 신규 입사자가 들어왔다. 잊혀 있던 Markdown 파일이 그때 도움이 되는 출발점이 됐다. 완전히 최신은 아니었지만 온보딩에 쓸 언어를 제공했고, 남은 동료가 다시 고쳐 보겠다고 나서게 했다.

사람이 떠날 때 함께 사라질 규칙을 적는다

레이어 책임, 엔티티 사용 방식, 로직을 둘 위치와 레거시에 의도적으로 남긴 타협은 코드만으로 복원하기 어렵다. 이유와 함께 저장소 안에 기록해 코드 변경처럼 리뷰할 수 있게 한다. 도메인 전체를 설명할 필요는 없다. 구전으로만 전해지던 소프트웨어 규칙을 남기면 된다.

완성된 전사 프로그램을 기다릴 필요도 없다. 조직이 열려 있고 규모가 작다면 공통 컨벤션 저장소를 만들 수 있다. 큰 회사라면 팀의 CONVENTION.md, 아키텍처 설명이나 README부터 시작할 수 있다. 변화가 적은 프로젝트는 유지보수 전용 상태와 의존성을 올리지 않는다는 정책을 명시할 수 있다.

코드를 본 뒤 컨벤션의 맥락을 설명한다

신규 입사 첫날 바로 컨벤션 세션을 열지 않았다. 코드와 회사 제약을 조금 경험한 뒤에야 레거시 영역을 왜 유연하게 뒀는지, 왜 컨트롤러 로직을 피하는지, 어떤 엔티티를 핵심 개념으로 쓰는지 이해하기 쉬웠다.

전사 컨벤션은 팀이 덮어쓸 수 있을 만큼 느슨해야 한다. 로컬 합의가 다르다면 팀 저장소에 차이를 남겨 다음 사람이 어느 선택을 따라야 하는지 알게 한다. 중앙 문서는 성숙도와 상황이 다른 프로젝트를 지우는 법이 아니라 기본값이다.

다른 사람이 고칠 때 살아 있는 컨벤션이 된다

한 사람이 모든 저장소를 최신으로 관리할 수는 없다. 자주 바뀌거나 핵심인 프로젝트부터 시작하고 나머지에는 솔직한 관리 한계를 둔다. 빠진 규칙은 동료가 PR로 추가하고 이견은 함께 논의하게 한다. 신규 입사자의 질문은 오래 일한 사람이 빠졌다는 사실조차 잊은 설명을 찾아낸다.

쓱 읽고 끝나는 문서는 살아 있는 지식이 아니다. 팀의 판단이 바뀔 때 함께 고치고, 규칙을 알던 사람이 없어도 실제로 다시 꺼내 쓰는 문서가 컨벤션을 이어 준다.