Context Engineering — Karpathy's 4 Strategies

#!/usr/bin/env python3
"""context-assistant.py — JIT Retrieval 패턴 구현"""
import os
from pathlib import Path

def calculate_context_health(session_tokens: int) -> dict:
    """현재 세션의 컨텍스트 상태를 평가"""
    total_budget = 200_000  # Claude 기본 컨텍스트 윈도우
    system_overhead = 10_000  # 도구 정의 + 시스템 프롬프트
    available = total_budget - system_overhead
    usage_pct = session_tokens / available * 100
    
    status = 'healthy'
    action = None
    
    if usage_pct > 60:
        status = 'warning'
        action = '서브에이전트로 새 태스크 격리 권장'
    if usage_pct > 80:
        status = 'critical'
        action = '즉시 새 세션 또는 서브에이전트로 전환'
    
    return {
        'usage_pct': round(usage_pct, 1),
        'status': status,
        'action': action,
        'tokens_used': session_tokens,
        'tokens_remaining': available - session_tokens
    }

def build_jit_index(project_dir: str = '.') -> str:
    """프로젝트 문서들에 대한 JIT 인덱스 생성 (CLAUDE.md용)"""
    docs_dir = Path(project_dir) / 'agent_docs'
    if not docs_dir.exists():
        return "# agent_docs/ 없음 — 디렉토리를 생성하고 문서를 추가하세요"
    
    index_lines = ["## More Detail On-Demand",
                   "Claude는 필요할 때만 이 파일들을 읽습니다. 모두 미리 로드하지 마세요.\n"]
    
    for md_file in sorted(docs_dir.glob('*.md')):
        line_count = len(md_file.read_text().split('\n'))
        # 파일명에서 설명 추론
        name = md_file.stem.replace('-', ' ').replace('_', ' ').title()
        rel_path = os.path.relpath(md_file, project_dir)
        index_lines.append(f"- {name}: @{rel_path} ({line_count}줄)")
    
    return '\n'.join(index_lines)

def optimize_prompt_cache_structure(content_sections: list) -> list:
    """
    프롬프트 캐싱 최적화를 위한 섹션 순서 조정.
    정적 내용은 앞, 동적 내용은 뒤.
    """
    static = [s for s in content_sections if not s.get('dynamic', False)]
    dynamic = [s for s in content_sections if s.get('dynamic', False)]
    
    ordered = static + dynamic
    
    total_static_tokens = sum(s.get('estimated_tokens', 0) for s in static)
    total_dynamic_tokens = sum(s.get('estimated_tokens', 0) for s in dynamic)
    cached_savings = total_static_tokens * 0.90  # 캐시 히트 시 ~90% 비용 절감
    
    print(f"정적 컨텐츠: {total_static_tokens:,} 토큰 (캐싱 적용)")
    print(f"동적 컨텐츠: {total_dynamic_tokens:,} 토큰 (캐싱 불가)")
    print(f"예상 캐시 절감: {cached_savings:,.0f} 토큰/세션 (90% 히트 기준)")
    
    return ordered

if __name__ == '__main__':
    # 컨텍스트 상태 평가
    health = calculate_context_health(75_000)
    print("=== 컨텍스트 상태 ===")
    print(f"사용: {health['usage_pct']}% | 상태: {health['status']}")
    if health['action']:
        print(f"권장: {health['action']}")
    
    # JIT 인덱스 생성
    print("\n=== JIT 인덱스 (CLAUDE.md 추가용) ===")
    print(build_jit_index('.'))