신규 사이트 온보딩 절차 한곳에서 관리하기
목차
신규 사이트를 로칭할 때마다 여러 문서를 뒤적거려야 했다. 인증 정책은 어디? 콘텐츠 제약은? SEO 체크는? 배포 절차는? 담당자마다 다르게 이해하고, 누군가는 중요한 단계를 빼먹고, 나중에 "어라, 이걸 왜 안 했지?" 하는 일이 반복됐다. 이번에 신규 사이트 온보딩 체크리스트를 단일 문서(SSOT)로 정리해서 모든 관점을 한곳에서 관리하도록 만들었다.
SSOT가 필요했던 이유
온보딩 정보가 여러 곳에 흩어져 있었다. 헤드빗 전역 지침은 ops 저장소의 hedvion-CLAUDE.md에, 사이트별 세부사항은 각 프로젝트의 CLAUDE.md에, 배포 과정은 별도 인프라 문서에... 이렇게 분산되면:
- 누락 위험: "혹시 이 단계 빠뜨렸나?" 하면서 문서들을 일일이 확인해야 함
- 일관성 문제: 같은 정보가 여러 곳에 있으면 버전이 달라질 수 있음
- 온보딩 담당자 교체 시 혼란: 새 담당자가 모든 문서를 알아야 온보딩을 제대로 할 수 있음
SSOT(Single Source of Truth) 원칙은 이걸 해결한다. 한 가지 정보는 한 곳에만 정의하고, 다른 곳은 거기를 참조하는 방식이다. 이렇게 하면 변경이 생겼을 때 한 곳만 수정하면 되고, 다른 문서들은 자동으로 최신 상태를 따르게 된다.
추가한 문서 구조
NEW-SITE-ONBOARDING.md는 체크리스트 중심으로 설계했다. 신규 사이트 로칭 전에 거쳐야 할 단계들을 순서대로 나열하되, 각 항목에서:
- 무엇을 할지 (단계)
- 참조 문서 (어디를 봐야 하는지)
- 누가 담당하는지 (팀/역할)
- 완료 기준 (언제 끝났다고 할 수 있는지)
를 명확히 했다. 예를 들어 "콘텐츠 정책 확인" 같은 항목이 있다면 sites-detail.md를 직접 링크하고, "이 항목은 수정한다면 ops 저장소에서 commit 후 반영" 같은 식으로 문서 간 관계도 명시했다.
hedvion-CLAUDE.md와의 연계도 중요했다. 이 파일이 "단일진실 = ops의 server-global-CLAUDE.md로의 symlink" 같은 일반 규칙을 정의하는 곳이라면, NEW-SITE-ONBOARDING.md는 구체적인 액션 리스트로서 보완한다. "이런 원칙이 있으니, 신규 사이트 온보딩할 때는 이 순서대로 이 문서들을 확인하세요"라는 식의 구체성을 더한 것이다.
팀에게 주는 변화
체크리스트화의 가장 큰 효과는 의사결정 부담 감소다. 온보딩 담당자가 "다음 단계가 뭐지?" 하고 판단하지 않아도 리스트를 따라가면 된다. 이는 특히 온보딩이 자주 발생하지 않을 때, 또는 담당자가 바뀔 때 가치가 크다. 새 담당자도 문서를 읽는 것만으로 process를 이해할 수 있다.
또한 체크 항목의 누락 방지라는 실질적 효과도 있다. 수동으로 기억하려는 것보다 체크리스트를 마킹하면서 진행하는 게 실수를 훨씬 줄인다. 이건 aviation, medical 같은 고위험 산업에서 오래 검증된 방식이다.
마지막으로 이 문서는 프로세스 개선의 계기가 된다. "온보딩 단계가 너무 많아 보이네", "이건 자동화할 수 있지 않을까", "이 두 단계는 순서를 바꿔야겠다" 같은 피드백이 더 쉽게 나온다. 체계화되지 않은 업무는 개선점을 발견하기도 어렵다.
이번 작업에서 배운 점
문서는 의도가 명확해야 한다. NEW-SITE-ONBOARDING.md가 단순 체크리스트가 아니라 "왜 이 순서인가", "이 항목의 의존성은 뭔가" 같은 맥락까지 담아야 한다. 체크박스만 있고 설명이 없으면 담당자가 "이걸 왜 하는데?" 하고 물어본다.
또한 문서 간 링크 관계를 명시하는 게 중요했다. "hedvion-CLAUDE.md를 보세요"라고만 하면 담당자가 그 파일을 열어서 관련 부분을 찾아야 한다. 차라리 "hedvion-CLAUDE.md의 'auth-policy' 섹션"처럼 정확한 위치를 가리켜주는 게 낫다.
마지막으로, SSOT 문서 자체도 유지보수가 필요하다는 교훈을 얻었다. 한 번 만들어두면 끝이 아니라, 온보딩 과정에서 "어, 이 단계 명시 안 돼 있네" 같은 피드백이 계속 들어올 테니 주기적으로 갱신해야 한다. 문서는 살아 있는 것이다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.