컨텍스트 엔지니어링 4전략 (Context Engineering) — 멀티에이전트 시스템에 Write·Select·Compress·Isolate 적용하기

// 모든 문제가 발생하는 순진한 구현
interface Message {
  role: "user" | "assistant";
  content: string;
}
 
async function naiveNewsAgent(articles: string[]): Promise<string> {
  let messages: Message[] = [];
 
  for (const article of articles) {
    // 문제 1: 모든 기사를 순차적으로 컨텍스트에 쌓는다 → Context Rot
    messages.push({ role: "user", content: `이 기사를 요약해줘: ${article}` });
    const summary = await callClaudeWithHistory(messages);
    messages.push({ role: "assistant", content: summary });
    // 200기사 처리 시 컨텍스트 윈도우 초과 → 100번째 기사에서 강제 종료
    // 문제 2: 중단되면 처음부터 재시작 — 진행 상황 없음
    // 문제 3: 단일 스레드 순차 처리 — 처리 속도 느림
  }
 
  return messages[messages.length - 1].content;
}

// [Write] 에이전트 스크래치패드 — 세션 간 상태 영속화
import fs from "fs/promises";
import path from "path";
 
interface ScratchpadEntry {
  step: number;
  timestamp: string;
  action: string;
  result: string;
  notes: string;
}
 
class AgentScratchpad {
  private filePath: string;
  private entries: ScratchpadEntry[] = [];
 
  constructor(taskId: string) {
    this.filePath = path.join("./scratchpad", `${taskId}.json`);
  }
 
  async load(): Promise<void> {
    try {
      const raw = await fs.readFile(this.filePath, "utf-8");
      this.entries = JSON.parse(raw);
      console.log(`[Write] 이전 체크포인트 ${this.entries.length}개 로드 완료`);
    } catch {
      this.entries = []; // 첫 실행이면 빈 상태로 시작
    }
  }
 
  async write(entry: Omit<ScratchpadEntry, "step" | "timestamp">): Promise<void> {
    const newEntry: ScratchpadEntry = {
      step: this.entries.length + 1,
      timestamp: new Date().toISOString(),
      ...entry,
    };
    this.entries.push(newEntry);
    await fs.mkdir(path.dirname(this.filePath), { recursive: true });
    await fs.writeFile(this.filePath, JSON.stringify(this.entries, null, 2));
  }
 
  getSummary(): string {
    return this.entries
      .map((e) => `[Step ${e.step}] ${e.action}: ${e.notes}`)
      .join("\n");
  }
}

// [Select] Contextual Retrieval — 관련 청크만 컨텍스트에 주입
interface NewsChunk {
  id: string;
  content: string;
  contextualDescription: string; // 청크의 문서 내 위치 설명
}
 
class NewsKnowledgeBase {
  private chunks: NewsChunk[] = [];
 
  // 인덱싱 시: 각 청크에 컨텍스트 설명을 prepend (Contextual Retrieval 핵심)
  async indexArticle(articleId: string, fullText: string): Promise<void> {
    const rawChunks = this.splitIntoChunks(fullText, 400);
 
    for (const [i, chunk] of rawChunks.entries()) {
      // 각 청크가 전체 기사에서 어떤 역할을 하는지 설명 생성
      const contextualDescription = await callClaude(
        `다음 기사 "${articleId}" 전체 내용:\n${fullText}\n\n` +
        `아래 청크가 이 기사 내에서 어떤 맥락에 위치하는지 2문장으로 설명하라.\n\n청크: ${chunk}`
      );
 
      this.chunks.push({
        id: `${articleId}-${i}`,
        content: chunk,
        contextualDescription,
      });
    }
  }
 
  // 검색 시: BM25 + 임베딩 하이브리드 검색으로 관련 청크만 선별
  async buildContext(query: string, topK = 5): Promise<string> {
    // 실제 구현에서는 벡터 DB(Pinecone 등)와 BM25 점수를 결합
    const relevant = this.hybridSearch(query, topK);
    // 전체 문서 대신 관련 청크만 주입 → 토큰 절약 + 관련성 집중
    return relevant
      .map((c) => `[배경 정보]\n${c.contextualDescription}\n${c.content}`)
      .join("\n\n");
  }
 
  private hybridSearch(query: string, topK: number): NewsChunk[] {
    // 0.4 * BM25 + 0.6 * 임베딩 유사도 하이브리드 가중치
    return this.chunks.slice(0, topK); // 간략화된 예시
  }
 
  private splitIntoChunks(text: string, maxWords: number): string[] {
    const words = text.split(" ");
    const chunks: string[] = [];
    for (let i = 0; i < words.length; i += maxWords) {
      chunks.push(words.slice(i, i + maxWords).join(" "));
    }
    return chunks;
  }
}

// [Isolate] 서브에이전트 — 독립 컨텍스트에서 좁은 태스크 수행 후 요약만 반환
interface SubTaskResult {
  taskId: string;
  summary: string;
  keyFindings: string[];
}
 
async function runSubAgent(
  taskId: string,
  specificTask: string
): Promise<SubTaskResult> {
  // 서브에이전트는 자신의 태스크 범위만 알고 있다
  // 오케스트레이터의 전체 히스토리는 전혀 전달되지 않는다 (격리)
  const response = await callClaude(
    `[서브태스크 #${taskId}]\n${specificTask}\n\n` +
    `완료 후 반드시 JSON 형식으로 응답하라:\n` +
    `{ "summary": "...", "keyFindings": ["...", "..."] }`
  );
 
  // 오케스트레이터에게는 요약된 결과만 전달 — 세부 컨텍스트는 격리
  const parsed = JSON.parse(extractJson(response));
  return { taskId, ...parsed };
}

// [Compress] 컴팩션 트리거 — 80% 도달 시 히스토리를 요약하고 재시작
const CONTEXT_WINDOW_TOKENS = 200_000;
const COMPACTION_THRESHOLD = 0.80;
 
function estimateTokenCount(messages: Message[]): number {
  return messages.reduce((acc, m) => acc + m.content.length / 4, 0);
}
 
async function compactIfNeeded(
  messages: Message[],
  taskGoal: string
): Promise<Message[]> {
  const usage = estimateTokenCount(messages) / CONTEXT_WINDOW_TOKENS;
 
  if (usage < COMPACTION_THRESHOLD) return messages;
 
  console.log(`[Compress] 컨텍스트 ${Math.round(usage * 100)}% 사용 → 컴팩션 실행`);
 
  const historyText = messages
    .map((m) => `[${m.role}]: ${m.content}`)
    .join("\n");
 
  const summary = await callClaude(
    `태스크 "${taskGoal}"의 대화 히스토리를 다음 형식으로 요약하라:\n` +
    `1. 완료된 작업 (구체적)\n2. 현재 상태 및 미완료 항목\n` +
    `3. 수집된 핵심 사실\n4. 주의해야 할 제약·오류\n\n` +
    `히스토리:\n${historyText}`
  );
 
  // 압축된 단일 메시지로 새 컨텍스트 시작
  return [
    {
      role: "user",
      content: `[이전 작업 요약]\n${summary}\n\n태스크를 이어서 진행하라.`,
    },
  ];
}

// 4전략 통합 오케스트레이터
async function productionNewsAgent(
  taskId: string,
  articleUrls: string[]
): Promise<string> {
  // [Write] 이전 실행 체크포인트 로드
  const scratchpad = new AgentScratchpad(taskId);
  await scratchpad.load();
 
  const knowledgeBase = new NewsKnowledgeBase();
  let messages: Message[] = [];
 
  // [Isolate] 카테고리별 서브에이전트 병렬 실행
  const categories = ["정치", "경제", "기술", "사회"];
  const subResults = await Promise.all(
    categories.map((category) =>
      runSubAgent(
        `${taskId}-${category}`,
        `다음 URL 목록에서 "${category}" 관련 기사만 선별해 핵심 내용을 요약하라:\n` +
        articleUrls.join("\n")
      )
    )
  );
 
  // [Write] 서브에이전트 결과를 스크래치패드에 영속화
  for (const result of subResults) {
    await scratchpad.write({
      action: `카테고리 요약 완료: ${result.taskId}`,
      result: result.summary,
      notes: result.keyFindings.join("; "),
    });
  }
 
  // [Compress] 오케스트레이터 컨텍스트가 임계값 도달 시 자동 압축
  messages.push({
    role: "user",
    content: `카테고리별 요약:\n${scratchpad.getSummary()}`,
  });
  messages = await compactIfNeeded(messages, "일간 뉴스 브리핑 생성");
 
  // [Select] 과거 관련 기사를 지식베이스에서 검색해 컨텍스트 보강
  const currentSummary = subResults.map((r) => r.summary).join(" ");
  const backgroundContext = await knowledgeBase.buildContext(currentSummary);
 
  return await callClaude(
    `[오늘 카테고리 요약]\n${scratchpad.getSummary()}\n\n` +
    `[관련 배경 정보]\n${backgroundContext}\n\n` +
    `위를 통합해 500자 이내의 독자용 데일리 뉴스레터를 작성하라.`
  );
}