CLAUDE.md: Claude Code를 위한 손실 없는 6개 레이어

Claude.md 시스템 설정: Claude 코드에서 흔들림 없는 컨텍스트를 위한 6단계 구조

Claude Code는 매 세션을 처음부터 시작합니다: 프로젝트 지식 없음, 서버 세부 정보 없음, 이전 수정 사항 없음. 이로 인해 반복 설명이 발생하고 위험도 커집니다—프로덕션 데이터 삭제부터 리포지토리에 비밀 푸시까지. 582줄짜리 CLAUDE.md 시스템이 6단계로 이를 해결합니다: 규칙부터 자동 훅까지. 각 단계는 실제 사고에서 진화했습니다.

구조를 만든 사고 사례

세 가지 실수가 접근 방식을 정의했습니다:

• 로컬호스트를 통한 SNI 프록시. 에이전트가 127.0.0.1을 실제 IP로 바꿔 업로드를 망쳤습니다. 근본 원인: 그 특정 값의 중요성을 파악하지 못함.
• Fail2ban 잠금. 1분 내 여러 SSH 로그인이 무차별 대입 공격으로 오인되어 모델 훈련이 중단됐습니다.
• 데이터셋 삭제. "필터" 명령이 파일을 이동하는 대신 삭제했습니다.

배운 교훈: 변경 전에 현재 값을 분석하는 규칙, 단일 SSH 터널 강제, 삭제 시 명시적 확인 요구.

6단계 구조

1단계: 규칙 (9개 파일)

상황에 맞게 로드: SSH 규칙은 텍스트 작업에 방해 안 함, 디버그 규칙은 스타일 가이드 생략.

2단계: 메모리 (78개 파일)

[[filename]]로 178개 상호 참조 지식 그래프. 핵심 파일은 항상 컨텍스트에, 주제별 파일은 필요 시 로드. 인프라, 수정, 함정 커버.

3단계: 핸드오프

세션 요약: 목표, 성과, 실패, 다음 단계. 예시:

## 세션 목표
컬러 체커: CNN 스윕 + 확산 모델.

## 완료
- CNN 베이스라인: 중앙값 1.99도 (11M 파라미터)
- 스윕: crop128(3.17), bs16(2.04)
- 확산: 5/50 에포크, 손실 0.827

## 실패한 부분
- EfficientNet-B0: 해시 불일치
- lr=3e-4: 클리핑 없인 NaN

## 다음 작업
확산 추론 + 시각 자료.

4일간 27개 핸드오프로 막다른 골목 재탐색 방지. 구독 간 호환.

4단계: 연대기

결정 타임라인: 마일스톤당 3-7줄. 핸드오프를 보완하는 전체 이야기.

5단계: 훅

이벤트(SessionStart, Stop, PreToolUse)로 트리거되는 자동 Python 스크립트. 모델 메모리 독립.

핸드오프 훅 예시:

# remind_handoff.py (Stop 훅)
age = session_age_minutes()
if age < 15 or fresh_handoff_exists():
    return
print(json.dumps({
    "decision": "block",
    "reason": f"세션 {int(age)}분, 핸드오프 기록 없음."
}))

6단계: 스킬 (16개 키트)

트리거 기반 가이드: "GPU 멈춤 시 이거 사용"처럼 모호함 대신.

훅 vs 규칙: 실행 보장

긴 세션에서 프롬프트 규칙 잊힘. 훅은 기계적으로 실행. 시작 훅은 CLAUDE.md 링크 검증, 종료 훅은 핸드오프 유도.

공급망 방어: 한 줄 설정

.npmrc에:

min-release-age=7

7일 미만 패키지 차단. axios 1.14.1 공격(Sapphire Sleet, 2026년 3월 31일, 3시간 창구) 막음. Python 대응 uv.toml:

exclude-newer = "7 days"

37개 연구 논문 원칙

규칙으로 압축:

• 증명 루프. 자기 확인 금지: 외부 증명(신규 세션 테스트) 요구.
• 구조화 추론. 형식: 사실 → 추적 → 결론 → 검증 가설. 패치 정확도: 78% → 93%.
• 결정론적 오케스트레이션. 고정 작업(테스트, 린팅)은 쉘 스크립트.
• 레드 라인. 강제 금지: "확인 없인 삭제 금지", 특정 사고 연계.

기타: 생성자-평가자, 다중 에이전트 분해, 에이전트 보안.

지표와 자동 업데이트

• 78 메모리 파일, 178 링크.
• 4일간 27 핸드오프.
• 96.9% KV-캐시 적중률 (83 세션).

설정 자체 검증: SessionStart 훅이 편집 후 링크 확인.

주요 교훈:

• 핸드오프와 메모리로 세션 간 컨텍스트 손실 방지.
• 훅으로 핵심 작업 보장.
• 공급망 보호: .npmrc / uv.toml에 min-release-age=7.
• 구조화 추론으로 디버그 정확도 93% 향상.
• 레드 라인으로 프로덕션 위험 대폭 줄임.

최소 스택: 결정론적 오케스트레이션 + 구조화 추론 + 공급망 방어 + 핸드오프.

리포: github.com/AnastasiyaW/claude-code-config (MIT).

— Editorial Team