사이트별 보트 설정을 캐스케이드로 조직

CLAUDE.md 설정 파일의 캐스케이드 구조를 endpoint2cost 사이트에 추가했다. 여러 보트/프로젝트가 전역 규칙을 상속하면서 각 사이트만의 추가 규칙을 가질 수 있게 정리한 작업이다.

왜 캐스케이드 구조가 필요했나

여러 개의 보트와 서비스가 동시에 돌아가는 환경에서 각각이 가져야 할 규칙은 두 가지로 나뉜다:

• 공통 규칙: 모든 보트가 따르는 기본 원칙 (출력 형식, 보안, 토큰 비용 원칙)
• 사이트 고유 규칙: 특정 서비스가 필요로 하는 추가 지침 (특정 API 사용법, 도메인 지식, 승인 프로세스)

이전엔 이 두 수준이 분리되지 않거나 불명확했을 것 같다. 공통 규칙이 전역에 정의되지만, 각 서비스별 추가 사항을 어디에 둘지, 어떻게 로드할지가 체계적이지 않았다. 결국 보트가 필요한 규칙을 전부 받지 못하거나, 중복 정의되면서 유지보수가 어려워지는 악순환이 생긴다.

캐스케이드 구조 설계

CLAUDE.md 파일을 다음과 같이 계층화했다:

각 보트가 실행될 때 전역 규칙을 먼저 로드한 뒤, 현재 사이트의 CLAUDE.md를 추가로 로드하는 방식이다. 예를 들어 endpoint2cost 사이트라면:

# endpoint2cost 서비스 규칙 (사이트별 CLAUDE.md)

- 출력은 JSON/텍스트만. HTML 생성 금지.
- 비용 관련 계산은 소수점 2자리 정확도 필수.
- 외부 API 호출 시 timeout = 3초.
- 비용 정산 과정에서는 감사 로그 필수.
(+ 전역 규칙도 자동으로 상속됨)

보트는 "이 보트가 endpoint2cost에서 실행되고 있다"는 걸 알 때 자동으로 필요한 모든 규칙을 받는다.

설계 선택과 고려사항

이 구조를 적용할 때 염두에 둔 원칙들:

• DRY 원칙: 공통 규칙을 한 곳에만 정의. 수정 시 모든 보트에 자동 반영.
• 명확한 우선순위: 상위 규칙이 하위를 덮어쓰지 않고 "확장"하는 방식. 전역이 정의한 핵심 원칙은 하위에서 깨지 않는다.
• 토큰 비용 최적화: 각 보트 호출마다 CLAUDE.md를 로드하는데, 계층을 명확히 하면 필요한 부분만 로드 가능하다.
• 서버 검증: 로컬에서 작성한 규칙이 실제 서버에서 캐스케이드되는지 확인. 심볼링크나 파일 경로 오류를 미연에 방지.

회고: 설정 문서화의 가치

이 작업을 하면서 느낀 점 몇 가지다.

첫째, 규칙을 코드화하는 것의 중요성. 보트의 동작을 지시하는 규칙이 산재되어 있거나 불명확하면, 시간이 지날수록 보트들이 다르게 동작하기 시작한다. CLAUDE.md 같은 설정 파일에 명시적으로 정의함으로써 "단일 진실 공급원"을 만들 수 있다. 규칙을 구두로 전달하는 것과 문서로 남기는 것은 하늘과 땅 차이다.

둘째, 계층 구조의 필요성. 팀이 작을 때는 공통 규칙 하나면 충분하지만, 여러 서비스와 보트가 늘어나면 상황이 달라진다. 각 도메인의 고유성을 존중하면서도 기본 원칙을 지키려면, 단순한 상하관계가 아니라 "상속과 확장"의 구조가 필요하다.

셋째, 문서도 코드다. 설정 파일을 코드처럼 관리하면 (버전 관리, 리뷰, 배포) 규칙 변경의 영향을 추적하고 롤백할 수 있다. endpoint2cost 사이트에 CLAUDE.md를 추가하면서 "이 규칙이 실제로 어떻게 로드되는가"를 서버에서 직접 검증한 것도 이런 이유에서다.

마지막으로, 이런 캐스케이드 패턴은 CLAUDE.md만의 문제가 아니다. 환경 설정, 로깅 규칙, 보안 정책, API 문서 같은 여러 곳에 적용할 수 있다. 한 번 구조를 잘 만들어두면 새로운 사이트나 프로젝트를 추가할 때 확장성이 훨씬 좋아진다. 설정 관리의 복잡도가 기하급수적으로 증가하지 않는 구조를 만드는 게 장기적으로는 팀 생산성에 가장 큰 영향을 미친다.

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

• 사무용모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 책상조명 쿠팡에서 보기 →

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