산재된 서비스 설정을 팀 공용 가이드로 정리

docs/hedvion-CLAUDE.md 에 slecs.net 계열 서비스들의 중앙화 지침, 시딩/Caddy 스크립트, slug 맵핑 규칙을 정리했다.

왜 이 문서화가 필요했나

팀이 성장하면서 여러 서비스가 늘어난다. slecs.net 계열만 해도 여러 도메인/환경이 존재했고, 각각의 시딩 스크립트가 어디에 있는지, Caddy 설정을 어디서 수정해야 하는지, 그리고 각 서비스에 할당된 slug ID가 무엇인지 일관되게 문서화된 곳이 없었다. 팀 규모가 작을 땐 "구두 전승"으로 버티지만, 사람이 늘거나 장기 휴가/이직 같은 일이 생기면 순식간에 정보 공백이 생긴다. 누군가 "어, 이 서비스의 초기 데이터 로드 스크립트가 뭐더라?" 물어볼 때마다 확인하는 수고를 줄이고, 신입이나 다른 팀이 맡을 때 혼동 없이 진행할 수 있게 하려면 한 곳에 정리된 지침이 필수다.

중앙화: 분산된 서비스 정보를 한곳에

여러 서브도메인 (slecs, blog-slecs, 등)이 각각 다른 목적·설정을 가지고 있을 때, 이들을 "계열"로 묶고 공통 원칙을 정의하는 것이 중요하다. 예를 들어:

이런 식으로 테이블화해서 문서에 넣으면, 새로운 팀원이나 자동화 스크립트가 참고할 수 있는 단일 소스 오브 트루스(single source of truth)가 된다. 각 서비스마다 따로 문서/위키를 찾아다닐 필요가 없다.

시딩과 Caddy 스크립트 지침화

팀 가이드 문서에 명시할 내용들:

• 시딩 스크립트 위치 및 실행 방법: "어느 환경에서는 어떻게 시드를 초기화하는가"
• Caddy 설정의 계층구조: 리버스 프록시 규칙이 서비스별로 어떻게 적용되는가
• 배포 순서와 의존성: 만약 blog-slecs가 slecs의 데이터에 의존한다면, 시딩 순서가 중요하다

이렇게 문서화하면 CI/CD 파이프라인을 구성할 때도, 온보딩 체크리스트를 만들 때도, "공식 방법"을 언급할 수 있다.

지침화가 만드는 효과

단순해 보이지만, 이런 문서화는:

1. 의사결정의 일관성: 다음 번에 slug 할당이나 서비스 추가가 필요할 때 "규칙이 있으니 이렇게 하자"고 말할 수 있다
2. 장애 추적 용이: "slecs가 안 떴는데?" 물을 때 가이드 문서의 slug 맵을 보고 빠르게 어느 환경·서비스를 확인해야 하는지 알 수 있다
3. 인수인계 효율화: 누군가 이 담당자를 넘겨받을 때 문서 한두 장이면 전체 구조를 이해할 수 있다

팀 리딩 관점의 회고

이 작업은 코드 라인 추가도 없고, 배포 자동화도 아니지만, 팀이 더 빠르게 움직일 수 있게 만드는 "기반"을 다지는 일이었다. 처음엔 "문서화는 나중에 해도 되지 않나" 생각하기 쉽지만, 실제로는 첫 번째 서비스가 잘 작동할 때가 지침화 최고의 타이밍이다. 규칙이 정해지지 않은 상태에서 자유롭게 진행하다가 나중에 억지로 정리하려 하면, 이미 산재된 설정들을 역으로 역산해야 한다. 반대로 초기 단계에 "이건 이렇게 관리한다"고 박아두면, 다음 서비스는 그 틀을 따르기만 하면 되고, 자동화도 쉬워진다. 앞으로 또 다른 서브도메인이 추가될 때마다 이 지침을 참고하면, 일관된 구조를 유지할 수 있을 것.

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

• 사무의자 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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