일하는 ai

08. CLAUDE.md 컨텍스트 재설계

7 min read

-

한 줄 결론: CLAUDE.md를 무조건 지우라는 뜻이 아니라, 항상 필요한 최소 규칙만 남기고 나머지는 작업별 Skill로 분리하라는 신호에 가깝습니다.

안내: 본문은 생성형 AI를 활용해 구조화했으며, 영상 내용·논문 요지·공식 문서를 교차 확인해 정리했습니다.

맥락 보완

영상 제목은 강하게 “CLAUDE.md 지워”라고 말하지만, 실제 핵심은 더 정교합니다.

  • 긴 컨텍스트 파일이 항상 성능을 높여주지는 않는다
  • 오히려 불필요한 탐색·툴 사용·토큰 비용을 늘릴 수 있다
  • 그렇다고 컨텍스트 파일 자체가 무의미하다는 뜻은 아니다

즉, 문제는 파일 존재 여부보다 컨텍스트 설계 방식입니다.

핵심 요약

  1. 논문 요지: 리포지토리 컨텍스트 파일이 항상 성능 개선으로 이어지지 않았다.
  2. 실무 해석: 범용 규칙을 장문으로 한 파일에 몰아넣으면 오히려 산만해질 수 있다.
  3. 권장 구조: CLAUDE.md 최소 핵심 + 작업별 Skill/Reference 지연 로딩이 더 안정적이다.

🧠 칠판 치트시트

  • “컨텍스트 많이 넣기” = “성능 상승”은 아니다.
  • 상시 컨텍스트는 짧게, 작업 컨텍스트는 필요할 때만.
  • 금지/예외 규칙을 장문으로 넣으면 탐색 비용이 커진다.
  • 핵심은 삭제가 아니라 분리(Always-on vs On-demand)다.

용어/비유 설명

  • Always-on 컨텍스트: 매 요청마다 항상 같이 따라붙는 지침
  • On-demand 컨텍스트: 특정 작업에서만 불러오는 지침
  • 비유하면, 여행 가방에 모든 계절 옷을 항상 넣고 다니는 게 아니라, 오늘 목적지에 맞는 옷만 꺼내는 방식입니다.

MECE 정리 (개념/원인/대응/실행)

  • 개념: 컨텍스트 설계는 “양”이 아니라 “정확한 주입 시점”의 문제다.
  • 원인: 단일 장문 파일에 규칙/예외/레퍼런스가 혼재되어 모델 탐색 범위가 과도하게 커짐.
  • 대응: 상시 규칙 최소화 + 작업별 Skill 분리 + 검증 루프 도입.
  • 실행: 아래 체크리스트 순서대로 리팩터링하고, 전/후 지표(성공률/툴사용량/응답시간) 비교.
flowchart LR
A[문제 인지: 장문 CLAUDE.md] --> B[원인 분해: 상시 컨텍스트 과다]
B --> C[대응 선택: 최소 코어 + Skill 분리]
C --> D[실행/검증: 성능·비용·정확도 비교]

영상의 핵심 해석 (실무 버전)

1) “지워라”의 본뜻

  • 왜 필요한가: 자극적 제목과 실무 메시지를 분리해서 읽어야 오해를 줄임
  • 실전 적용:
    • CLAUDE.md를 전면 삭제 대신 핵심 10~30줄만 유지
    • 프로젝트 공통 규칙(보안/출력형식/금지사항)만 남김
  • 실패 신호: 파일이 길수록 예외 규정이 늘고, 실제 작업 품질은 흔들림
  • 10초 체크: “이 문장이 매 요청마다 필요한가?”라고 질문했을 때 Yes가 아닌 문장 제거

2) 논문 결과를 그대로 복붙 해석하면 위험

  • 왜 필요한가: 벤치 결과와 내 프로젝트 환경은 다를 수 있음
  • 실전 적용:
    • 우리 저장소에서 전/후 A/B 테스트
    • 지표: 성공률, 평균 툴 사용 횟수, 완료 시간, 토큰 비용
  • 실패 신호: 논문 결론을 맥락 없이 정책으로 바로 고정
  • 10초 체크: 우리 데이터 기준 비교표가 1장 이상 있는가?
  • 참고 링크: arXiv 2602.11988

3) 정답은 “무컨텍스트”가 아니라 “적시 컨텍스트”

  • 왜 필요한가: 복잡 작업은 여전히 구조화된 지침이 필요함
  • 실전 적용:
    • 상시 파일: 원칙만
    • 작업 파일: Skill/Reference로 분리
    • 실행 후 반드시 검증 루프(실행→검증→수정→재검증)
  • 실패 신호: 같은 오류가 반복되고, 수정 비용이 누적됨
  • 10초 체크: 실패한 작업에서 어떤 규칙을 어디로 이동할지 1줄로 설명 가능한가?

추천 운영 구조 (지금 바로 적용)

  1. CLAUDE.md에는 아래만 유지
    • 보안 금지선
    • 응답 톤/포맷
    • 공통 출력 규칙
  2. 스킬 단위로 분리
    • 작업 트리거는 description
    • 실행 절차/체크리스트는 SKILL.md body
  3. 참조 자료는 references/로 분리
    • 필요할 때만 로딩되게 설계

공식 참고:

적용 체크리스트

  • CLAUDE.md에서 “항상 필요한 문장”만 남겼다
  • 작업 지침은 Skill 단위로 분리했다
  • 장문 설명은 references 파일로 이동했다
  • 복잡 작업에 검증 루프(MUST)를 넣었다
  • 리팩터링 전/후 지표를 기록했다(성공률/툴사용/시간/비용)

다음 읽기

그래프 뷰

백링크