일기 slecs

공통 설정 한 번에 관리하는 계층 구조 도입

목차

namecert 사이트에 CLAUDE.md의 캐스케이드 설정을 추가했다. 간단한 문서화 작업처럼 보이지만, 실은 여러 사이트를 운영하는 팀이라면 반복하게 될 설정 관리 문제를 정면으로 푼 것이다.

CLAUDE.md의 계층화 필요성

우리 팀은 여러 사이트와 서비스를 동시에 운영 중이다. 각 사이트마다 Claude 봇과 에이전트가 실행되고, 각각 고유한 지침(CLAUDE.md)이 필요하다. 하지만 문제는 공통으로 따라야 할 규칙이 곳곳에 중복된다는 것이었다.

예를 들면:
- 모든 사이트가 지켜야 할 공통 출력 포맷
- 모든 봇에서 금지해야 할 보안 사항
- 공사(公社) 시스템의 통일된 규칙

이런 규칙들이 각 CLAUDE.md에 독립적으로 박혀 있으면, 나중에 공통 규칙을 수정할 때마다 모든 파일을 일일이 찾아다니며 변경해야 한다. 팀이 커질수록 이 작업은 실수와 불일치의 원인이 된다.

캐스케이드 구조의 작동 원리

캐스케이드(Cascade)는 쉽게 말해 상위 설정이 하위 설정에 자동으로 적용되는 구조다. 코드의 상속이나 CSS 스타일시트와 같은 개념이다.

이번 변경으로:
1. 서버 레벨에 공통 CLAUDE.md 배치 → 모든 봇이 이를 기본으로 로드
2. 각 사이트별 CLAUDE.md에서 공통 부분 제거
3. 사이트 고유 규칙만 추가로 작성

실제 동작 흐름은 대략 이렇다:

[서버 공통 규칙] (캐시되지 않는 메시지 금지, 날짜 기준, 보안 규칙)
         ↓ 상속
[namecert 사이트별 규칙] (사이트 고유 봇 설정)
         ↓ 최종 적용
    봇 실행 시 공통 + 사이트 규칙 병합

이렇게 하면 공통 규칙을 한 곳에서만 관리해도 모든 사이트가 자동으로 따른다.

실제 효과와 회고

  • 유지보수 효율: 공통 규칙 한 줄 수정 = 모든 사이트 자동 반영
  • 일관성 보장: "이 사이트는 다른 규칙을 따르나?" 같은 혼란 제거
  • 신규 사이트 온보딩: 새 사이트 추가할 때 공통부 복붙 불필요
  • 검증 단계: "서버검증"으로 실제 캐스케이드가 작동하는지 확인함

이런 구조를 구축하는 게 언뜻 별 것 아닌 것처럼 보이지만, 일반화와 추상화의 중요성을 다시 한 번 느꼈다. 초기에 각 사이트가 독립적으로 CLAUDE.md를 관리할 때는 괜찮지만, 규모가 커지면 공통점을 뽑아내고 계층화하는 작업이 필수다. 코드 리뷰할 때 "중복이 보이면 추상화할 신호"라고 팀원들한테 자주 말하는데, 문서화 영역에도 정확히 똑같이 적용된다.

다음은 namecert 외 다른 사이트들도 이 구조를 따르도록 점진적으로 마이그레이션할 차례다.

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

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

이어보기

댓글 0

첫 댓글 달아줘.