관리자 진입 경로를 README와 푸터에 명확히 정리

README와 footer에 관리자 진입 경로를 문서화했다. 단순 UI 텍스트 추가처럼 보이지만, 실제로는 사용자 접근성과 운영 효율성에 닿아 있는 작은 결정들이 연쇄적으로 얽혀 있었다.

왜 관리자 진입을 문서화했는가

처음엔 관리자 진입 경로가 충분히 명확하지 않았다. README에는 일반 사용자 기준 설명만 있었고, footer에는 관리자 링크가 있긴 했지만 문맥 없이 떠 있었다. 그러다 보니 신규 팀원이 들어올 때마다 "어디서 관리자로 로그인 하는데요?"라는 질문이 반복됐다. 운영자들도 마찬가지였다. 초기 온보딩 시간이 불필요하게 늘어났고, 가끔 사용자가 잘못된 경로로 접근하려고 시도하는 상황도 있었다.

이런 불편함은 사소해 보이지만 누적되면 팀 생산성을 깎아먹는다. 특히 관리자 기능처럼 일부 사용자만 쓰는 영역은 "모르고 못 쓰는" 상태가 발생하면, 이미 구현된 기능도 사실상 사장된다.

더 근본적인 문제도 있었다. 관리자 영역과 일반 사용자 영역의 경계가 코드 레벨에서는 명확히 나뉘어 있어도, 문서와 UI에서 그 경계가 흐릿하면 팀 전체가 같은 멘탈 모델을 공유하지 못한다. 신입 개발자가 코드를 볼 때 "이 route가 관리자 전용인가, 아닌가"를 맥락 없이 판단해야 하는 상황이 생긴다. 그 불확실성이 쌓이면 PR 리뷰 때 불필요한 질문이 늘어나고, 가끔은 실수로 일반 사용자 흐름에 관리자 로직이 섞이는 일도 생긴다. 발생하고 나면 버그가 아니라 설계 문제로 번지는 유형이라 더 골치 아프다.

어디에 뭐를 정리했나

세 곳을 동시에 손댔다.

README는 개발자, 운영자, 신규 팀원이 가장 먼저 보는 곳이고, footer는 실제 제품에서 매 페이지마다 노출되는 공간이다. 두 지점을 함께 정리함으로써 "문서상의 설명"과 "실제 UI의 명확성"을 동기화했다.

base.html footer 쪽은 대략 이런 방향으로 정리됐다:

<footer>
  <!-- 일반 사용자 영역 -->
  <nav class="footer-user-links">
    <a href="/">홈</a>
    <a href="/about">소개</a>
  </nav>

  <!-- 관리자 전용 - 권한 있을 때만 노출 -->
  {% if current_user.is_admin %}
  <nav class="footer-admin-links">
    <span class="admin-label">관리</span>
    <a href="/admin">대시보드</a>
    <a href="/admin/users">사용자 관리</a>
  </nav>
  {% endif %}
</footer>

핵심은 관리자 링크를 일반 링크 사이에 묻어두지 않고, 시각적으로 분리된 영역으로 묶는 것이었다. CSS에서도 .footer-admin-links에 별도 색상과 폰트 크기를 적용해서 "이건 다른 맥락의 링크다"라는 신호를 명확히 했다. 조건부 렌더링으로 일반 사용자에게는 아예 노출되지 않도록 한 것도 중요한 포인트인데, 사용할 수 없는 링크를 보여주는 것보다 아예 안 보이는 게 UX 혼란을 덜 만든다.

README는 기존 Getting Started 섹션 아래에 관리자 접근 섹션을 별도로 뺐다. 개발 환경 셋업, 일반 사용자 흐름, 관리자 접근 순서로 읽히도록 배치했고, 관리자 계정 생성 방법이나 권한 설정 방법도 간략히 포함했다. 분량이 길어질 필요는 없었다. 새 팀원이 "아, 여기구나" 하고 파악하는 데 필요한 최소한의 내용이면 충분했다.

한 가지 고민했던 트레이드오프는 footer에 관리자 링크를 노출하는 방식이 맞는가 하는 점이었다. 별도의 /admin 진입점만 두고 거기서 모든 관리 기능을 처리하는 방식도 옵션이었다. Django admin처럼 완전히 분리된 UI를 택하는 프레임워크들이 이 방식을 쓴다. 이번엔 기존 footer 구조를 유지하면서 명확성만 높이는 방향을 선택했다. 구조를 크게 바꾸는 건 범위 밖이었고, 당장의 혼란을 줄이는 게 우선이었으니까.

이 작업이 왜 미뤄지는가, 그리고 왜 미루면 안 되는가

기능 개발이 아니라서 미루기 쉬운 작업이다. PR 티켓에 "관리자 링크 스타일 개선"이라고 올라오면 우선순위가 자꾸 밀린다. 하지만 팀 규모가 커질수록 이런 정리 작업의 투자 대비 효과가 급격히 올라간다.

단순하게 계산해봐도, 1년에 5명이 팀에 합류하는 상황이라면 매 신입마다 "관리자 진입 경로"를 구두로 설명하는 시간이 쌓인다. 5분씩이라고 해도 5명이면 25분, 거기에 질문 주고받는 시간, 잘못된 경로로 접근해서 생기는 혼란까지 합치면 꽤 된다. 처음부터 명확히 적어두면 그 비용이 사라진다.

팀을 리드하면서 더 크게 느끼는 건 "기능은 있는데 아무도 모른다"는 상황이 생각보다 자주 발생한다는 거다. 개발자들은 보통 구현에 집중하고, 그 기능이 실제로 발견 가능한지(discoverable)는 뒤로 미룬다. 관리자 기능처럼 일부 사용자만 쓰는 영역은 더더욱 그렇다. 구현된 기능이 사장되는 건 기술 부채보다 더 나쁜 상황이다. 코드는 나중에 고치면 되지만, 팀 문화에서 "어차피 있어봤자 아무도 모르니까"라는 패턴이 굳어지면 되돌리기가 훨씬 어렵다.

멘토링 관점에서도 마찬가지다. 후배들이 처음 코드를 뜯어볼 때 어디가 관리자 영역이고 어디가 사용자 영역인지 구분이 명확하면 학습 곡선이 훨씬 가파르게 올라간다. 반대로 경계가 흐릿하면 코드를 읽을 때마다 "이게 맞나?"를 확인하는 인지 비용이 계속 발생한다. 그 비용은 티켓이나 PR에 잡히지 않아서 더 위험하다. 측정이 안 되니 개선 대상으로도 안 올라온다.

README 정비가 신규 온보딩 시간 단축 이상의 의미를 가진다는 점도 있다. 팀이 제품을 외부에 설명할 때, 다른 팀과 협업할 때, README가 제품의 첫 얼굴이 된다. 관리자 진입 경로가 명확히 적혀 있으면 협업 상대방이 "이 기능에 어떻게 접근하나요?"를 물어보는 대신 직접 파악할 수 있다. 작은 차이 같지만 외부 사람이 우리 제품을 읽는 방식 자체가 달라진다.

이 작업 자체는 한두 시간이면 끝났다. 언제 할지 고민하는 게 더 오래 걸렸다. 다음에는 이런 문서 개선 작업을 좀 더 주기적으로 챙기면서, 팀 회의 때 "요즘 누가 뭘 못 찾고 있나?"를 조기에 포착하는 루틴을 만들어봐야겠다는 생각이 든다. 사소해 보이는 불편함일수록 보고가 잘 안 올라오고, 팀장은 더 늦게 인지한다. 그게 더 문제다.