9장: 컨텍스트 품질 측정과 개선

interface TaskResult {
  taskId: string;
  taskType: "create" | "modify" | "fix" | "refactor" | "test";
  
  // 성공 여부 판정 기준
  buildPassed: boolean;       // 빌드 성공
  testsPassed: boolean;       // 관련 테스트 통과
  lintPassed: boolean;        // 린트 통과
  humanApproved: boolean;     // 사람의 최종 승인
  
  // 컨텍스트 정보
  contextTokens: number;      // 사용된 컨텍스트 토큰 수
  contextFiles: number;       // 포함된 파일 수
  contextStrategy: string;    // 사용된 컨텍스트 전략
  
  // 효율성
  totalTokens: number;        // 전체 토큰 (입력 + 출력)
  responseTime: number;       // 응답 시간 (ms)
  iterationCount: number;     // 수정 반복 횟수
  cost: number;               // 비용 (USD)
}
 
function calculateSuccessRate(results: TaskResult[]): SuccessMetrics {
  const total = results.length;
  
  return {
    buildSuccessRate: results.filter(r => r.buildPassed).length / total,
    testSuccessRate: results.filter(r => r.testsPassed).length / total,
    fullSuccessRate: results.filter(r => 
      r.buildPassed && r.testsPassed && r.lintPassed
    ).length / total,
    humanApprovalRate: results.filter(r => r.humanApproved).length / total,
    
    // 첫 시도 성공률 (수정 없이 바로 통과)
    firstAttemptRate: results.filter(r => 
      r.buildPassed && r.testsPassed && r.iterationCount === 1
    ).length / total,
  };
}

interface TokenEfficiency {
  // 토큰당 성공률
  successPerToken: number; // 성공률 / 컨텍스트 토큰 수
  
  // 불필요한 토큰 비율
  wasteRatio: number; // 사용되지 않은 컨텍스트 비율 추정
  
  // 비용 효율성
  costPerSuccess: number; // 성공 1건당 비용
  
  // 속도 효율성
  timePerSuccess: number; // 성공 1건당 소요 시간
}
 
function analyzeTokenEfficiency(results: TaskResult[]): TokenEfficiency {
  const successful = results.filter(r => r.humanApproved);
  const failed = results.filter(r => !r.humanApproved);
  
  const avgSuccessTokens = average(successful.map(r => r.contextTokens));
  const avgFailTokens = average(failed.map(r => r.contextTokens));
  
  return {
    successPerToken: successful.length / sum(successful.map(r => r.contextTokens)),
    wasteRatio: estimateWaste(results),
    costPerSuccess: sum(successful.map(r => r.cost)) / successful.length,
    timePerSuccess: sum(successful.map(r => r.responseTime)) / successful.length,
  };
}

interface RelevanceScore {
  // 제공된 파일 중 실제로 참조/수정된 비율
  fileUtilization: number;
  
  // 제공된 코드 라인 중 실제로 관련된 비율
  lineRelevance: number;
  
  // 누락된 컨텍스트 (에이전트가 추가로 탐색한 파일)
  missingContext: string[];
  
  // 불필요했던 컨텍스트 (제공했지만 미사용)
  unusedContext: string[];
}
 
async function evaluateRelevance(
  providedContext: ContextBlock[],
  agentActions: AgentAction[]
): Promise<RelevanceScore> {
  const providedFiles = new Set(providedContext.map(c => c.filePath));
  const accessedFiles = new Set(agentActions
    .filter(a => a.type === "read" || a.type === "edit")
    .map(a => a.filePath));
  
  const utilized = [...providedFiles].filter(f => accessedFiles.has(f));
  const missing = [...accessedFiles].filter(f => !providedFiles.has(f));
  const unused = [...providedFiles].filter(f => !accessedFiles.has(f));
  
  return {
    fileUtilization: utilized.length / providedFiles.size,
    lineRelevance: await calculateLineRelevance(providedContext, agentActions),
    missingContext: missing,
    unusedContext: unused,
  };
}

interface ABTestConfig {
  name: string;
  description: string;
  
  // 비교 대상
  controlStrategy: ContextStrategy;  // 현재 전략
  testStrategy: ContextStrategy;      // 테스트 전략
  
  // 테스트 태스크
  tasks: Task[];
  
  // 반복 횟수 (통계적 유의성)
  repetitions: number;
  
  // 측정 메트릭
  primaryMetric: "successRate" | "firstAttemptRate" | "costPerSuccess";
}
 
async function runABTest(config: ABTestConfig): Promise<ABTestResult> {
  const controlResults: TaskResult[] = [];
  const testResults: TaskResult[] = [];
  
  for (let i = 0; i < config.repetitions; i++) {
    for (const task of config.tasks) {
      // Control: 현재 전략으로 실행
      const controlContext = await config.controlStrategy.build(task);
      const controlResult = await executeWithContext(task, controlContext);
      controlResults.push(controlResult);
      
      // Test: 새 전략으로 실행
      const testContext = await config.testStrategy.build(task);
      const testResult = await executeWithContext(task, testContext);
      testResults.push(testResult);
    }
  }
  
  return {
    control: calculateMetrics(controlResults),
    test: calculateMetrics(testResults),
    improvement: calculateImprovement(controlResults, testResults),
    isSignificant: statisticalTest(controlResults, testResults),
  };
}

interface DriftReport {
  file: string;
  issues: DriftIssue[];
  severity: "low" | "medium" | "high";
  lastUpdated: Date;
  staleDays: number;
}
 
interface DriftIssue {
  type: "stale-path" | "wrong-version" | "missing-module" | "dead-rule";
  description: string;
  evidence: string;
}
 
async function detectDrift(claudeMdPath: string): Promise<DriftReport> {
  const content = await readFile(claudeMdPath);
  const issues: DriftIssue[] = [];
  
  // 1. 경로 유효성 검사
  const mentionedPaths = extractPaths(content);
  for (const path of mentionedPaths) {
    if (!await fileExists(path)) {
      issues.push({
        type: "stale-path",
        description: `경로 '${path}'가 실제로 존재하지 않습니다`,
        evidence: path,
      });
    }
  }
  
  // 2. 패키지 버전 확인
  const mentionedVersions = extractVersions(content);
  const actualVersions = await getPackageVersions();
  for (const [pkg, mentioned] of mentionedVersions) {
    const actual = actualVersions.get(pkg);
    if (actual && actual !== mentioned) {
      issues.push({
        type: "wrong-version",
        description: `${pkg}: 문서 ${mentioned} vs 실제 ${actual}`,
        evidence: `${pkg}@${mentioned} -> ${pkg}@${actual}`,
      });
    }
  }
  
  // 3. 새 모듈 누락 확인
  const documentedModules = extractModules(content);
  const actualModules = await scanModules("src/");
  for (const module of actualModules) {
    if (!documentedModules.has(module)) {
      issues.push({
        type: "missing-module",
        description: `모듈 '${module}'이 문서에 누락되어 있습니다`,
        evidence: module,
      });
    }
  }
  
  // 4. 마지막 수정일 확인
  const lastModified = await getLastModified(claudeMdPath);
  const staleDays = daysSince(lastModified);
  
  return {
    file: claudeMdPath,
    issues,
    severity: issues.length > 5 ? "high" : issues.length > 2 ? "medium" : "low",
    lastUpdated: lastModified,
    staleDays,
  };
}

// CI/CD에 통합하여 주기적으로 실행
async function refreshContextFiles(): Promise<void> {
  const report = await detectDrift("CLAUDE.md");
  
  if (report.severity === "high") {
    // PR 자동 생성
    await createDriftFixPR(report);
  } else if (report.severity === "medium") {
    // Slack/이메일 알림
    await notifyTeam(report);
  }
  
  // 메트릭 기록
  await recordDriftMetrics({
    file: report.file,
    issueCount: report.issues.length,
    staleDays: report.staleDays,
    timestamp: new Date(),
  });
}