봇 지침 문서 헤더 체계 통일
목차
pdf2api 프로젝트의 CLAUDE.md 문서 구조를 정리했다. "캐스케이드 헤더"라고 부르는 제목 계층 구조를 보강하고 서버 환경에서 검증했다.
지침 문서가 중요한 이유
각 프로젝트마다 /opt/<repo>/CLAUDE.md 파일이 있다. 이 파일은 단순한 README가 아니라, 해당 프로젝트에서 동작하는 봇들의 동작 규칙 이다. 개발 환경과 서버 환경에서 실행되는 봇이 일관된 지침을 따르려면 이 문서가 명확해야 한다.
실제로 hedvionCorp/ops 의 docs/server-global-CLAUDE.md 를 단일 진실의 원천으로 두고, 각 서버의 CLAUDE.md는 symlink로 연결하는 구조를 갖추고 있다. 그 위에 각 프로젝트별 지침이 계층을 이룬다. 이런 다층 구조에서 헤더 계층이 명확하지 않으면 봇이 어느 레벨의 지침을 먼저 읽어야 할지, 어디서 override가 일어나야 할지 헷갈린다.
캐스케이드 헤더 개선
"캐스케이드(cascade)" 는 원래 폭포처럼 위에서 아래로 흐른다는 의미다. 문서에서 이 개념을 적용하면:
# 최상위 영역 (global instruction)
## 프로젝트 레벨 지침
### 특정 기능/도메인
#### 상세 옵션
이전에는 이 계층이 명확하지 않아서, 문서를 읽는 입장에서 "어느 부분이 필수고 어디서부터 선택사항인가" 를 판단하기 어려웠다. 특히 여러 봇이 같은 문서를 읽을 때 해석의 여지가 생긴다.
이번 작업에서:
- H1 (최상위): 전역 규칙, 모든 봇이 따를 사항
- H2: 프로젝트 또는 봇 특화 설정
- H3: 특정 시나리오·옵션
이렇게 정리하니, 봇의 초기화 코드에서 문서를 파싱하거나, 앞으로 자동화 도구를 만들 때 구조를 예측할 수 있게 됐다.
서버검증의 의미
마지막에 "(서버검증)" 을 명시한 이유가 있다. 개발 환경과 서버 환경은 문서 로드 경로, symlink 구조, 파일 권한이 다를 수 있다. CLAUDE.md가 여러 프로젝트에서 shared instruction으로 동작하니, 실제 서버에서 각 봇이 지침을 올바르게 읽고 해석하는지 직접 확인 했다는 뜻이다.
이런 문서 구조 변경은 "코드는 안 건드렸는데?" 싶을 수 있지만, 실제로는:
- 봇의 초기화 로직이 문서 구조를 가정하고 있을 수 있음
- 앞으로 이 문서를 다른 도구가 읽을 수 있으니 일관성이 필수
- 문서 변경이 실제 동작에 영향을 주는지 확인 필수
회고
코드 커밋만 중요한 게 아니라, 지침 문서 같은 메타 레이어의 품질도 시스템 신뢰도를 좌우한다는 걸 다시 느꼈다. 특히 여러 봇이나 팀이 공유하는 문서는 "이건 이렇게 읽으면 되겠지" 같은 암묵적 이해가 아니라, 명시적이고 일관된 구조가 있어야 한다.
다음부터는 문서 구조 개선할 때도 커밋 단계에서 "이 헤더 계층이 어떤 의도를 가진 건지" 메모해 두고, 실제 환경에서 검증하는 습관을 들이자.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.