외부도메인 인벤토리 등록으로 운영 일관성 확보
목차
새로운 외부도메인을 docs 에 인벤토리로 등록했다. 팀이 서로 다른 서비스/도메인들을 다룰 때마다 일관된 설정과 지침을 참고할 수 있도록 하려는 의도였다.
왜 인벤토리 등록이 필요했나
규모가 자라면서 여러 외부도메인을 다루게 된다. 각 도메인마다 서로 다른 세팅, 인증 방식, API 권한이 있기 마련이다. 이런 정보를 문서화하지 않으면 팀원마다 다르게 이해하거나, 나중에 새로 합류한 사람이 헤맬 수밖에 없다. "이 도메인은 뭐였지?", "권한이 뭐였더라?" 같은 질문이 반복되면 효율이 떨어진다. 그래서 "인벤토리"라는 개념으로 중앙에서 관리하는 것이 필요했다.
CLAUDE.md 에 등록한다는 의미
CLAUDE.md 는 단순한 README 같은 문서가 아니다. 각 서비스/봇별로 떨어져 있으면서도 일관된 지침을 제공하는 파일이다. 사용자 지침에서 "각 봇 디렉토리의 CLAUDE.md 에 둔다"고 명시한 것처럼, 이 구조는 계층적이면서도 분산되어 있다. docs 레벨의 hedvion-CLAUDE.md 에 외부도메인을 등록한다는 것은, 전사 레벨에서 "이 도메인들은 이렇게 다뤄야 한다"는 기준을 명시하는 것이다. 즉, 단순 기록이 아니라 팀의 규칙을 정하는 행위다.
온보딩 패턴과 일관성 유지
신규 도메인이 LIVE 될 때마다 설정 가이드를 문서화하는 것은 흔한 작업인데, 흩어진 위키나 이메일로 관리하면 곧 stale 정보가 된다. 하지만 코드베이스 안의 docs 에 CLAUDE.md 형태로 두면:
- 다른 지침들과 함께 버전 관리된다
- 코드 리뷰 프로세스를 거친다
- 새 팀원이 온보딩될 때 같은 자료를 보게 된다
- 이 변경이 언제, 누가 했는지 git history 에 남는다
이번 commit 도 그 연장선이다. kpopdex.com 같은 외부도메인이 2026-06-18 부터 LIVE 되는 시점에, docs 에 정식으로 등록함으로써 "이제부터 이 도메인은 이렇게 다룬다"는 선언을 한 것이다.
배운 점과 앞으로
초기엔 "도메인 추가? 그냥 팀에 말하면 되지" 정도로 생각했다. 하지만 팀이 커지고, 외부 서비스가 늘어나면서 문서화의 필요성이 명확해졌다. 특히 온보딩/오프보딩 시점에 "이게 뭐였더라?" 하는 상황이 줄어든다. 또한 docs 라는 중앙 위치에 모아두니 여러 팀이 cross-reference 할 때도 한 곳만 보면 된다. 다음에도 비슷한 상황에선 주저 없이 같은 방식으로 처리할 것 같다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.