7장: 컨텍스트 격리와 멀티에이전트 설계

interface AgentContext {
  // 공유 컨텍스트: 모든 에이전트에 공통
  shared: {
    projectRules: string;      // CLAUDE.md
    projectStructure: string;  // 트리 요약
    conventions: string;       // 핵심 컨벤션
  };
  
  // 전용 컨텍스트: 에이전트별 특화
  dedicated: {
    role: string;              // 에이전트 역할 정의
    relevantCode: string[];    // 역할 관련 코드
    tools: ToolDefinition[];   // 사용 가능한 도구
    examples: string[];        // 역할 관련 예시
  };
}
 
function buildAgentContext(
  role: "coder" | "tester" | "reviewer",
  task: Task,
  project: ProjectInfo
): AgentContext {
  const shared = {
    projectRules: readCLAUDEmd(project.root),
    projectStructure: generateTreeSummary(project.root, 1),
    conventions: extractCoreConventions(project),
  };
  
  switch (role) {
    case "coder":
      return {
        shared,
        dedicated: {
          role: "코드를 작성하고 수정하는 역할입니다.",
          relevantCode: selectCodeForCoding(task),
          tools: [fileWrite, fileRead, terminalRun, grep],
          examples: findSimilarImplementations(task),
        },
      };
    
    case "tester":
      return {
        shared,
        dedicated: {
          role: "테스트를 작성하고 실행하는 역할입니다.",
          relevantCode: selectCodeForTesting(task),
          tools: [fileWrite, fileRead, testRun],
          examples: findExistingTestPatterns(task),
        },
      };
    
    case "reviewer":
      return {
        shared,
        dedicated: {
          role: "코드를 리뷰하고 개선사항을 제안하는 역할입니다.",
          relevantCode: selectCodeForReview(task),
          tools: [fileRead, grep, gitDiff],
          examples: findReviewStandards(project),
        },
      };
  }
}

interface MessageFilter {
  // 에이전트 간 메시지 전달 시 필터링
  filterForRecipient(
    message: AgentMessage,
    recipient: AgentRole
  ): AgentMessage | null;
}
 
class ContextFirewall implements MessageFilter {
  private allowedChannels: Map<string, Set<AgentRole>>;
  
  filterForRecipient(
    message: AgentMessage,
    recipient: AgentRole
  ): AgentMessage | null {
    // 1. 채널 허용 여부 확인
    const channel = `${message.sender}->${recipient}`;
    if (!this.isChannelAllowed(channel)) {
      return null;
    }
    
    // 2. 메시지 유형 필터링
    if (message.type === "intermediate-result" && recipient !== "orchestrator") {
      return null; // 중간 결과는 오케스트레이터만 수신
    }
    
    // 3. 민감 정보 제거
    return this.sanitize(message, recipient);
  }
  
  private sanitize(message: AgentMessage, recipient: AgentRole): AgentMessage {
    // 수신자 역할에 불필요한 정보 제거
    const sanitized = { ...message };
    
    if (recipient === "tester") {
      // 테스터에게는 구현 세부사항 대신 인터페이스만 전달
      sanitized.content = extractInterfaces(message.content);
    }
    
    return sanitized;
  }
  
  private isChannelAllowed(channel: string): boolean {
    // 허용된 통신 채널만 통과
    return this.allowedChannels.has(channel);
  }
}

interface SubagentBrief {
  // 1. 명확한 역할 정의
  role: string;
  
  // 2. 구체적인 작업 지시
  task: {
    description: string;
    acceptanceCriteria: string[];
    constraints: string[];
  };
  
  // 3. 필요한 최소 컨텍스트
  context: {
    projectRules: string;    // CLAUDE.md (자동 로드)
    relevantFiles: string[]; // 작업에 필요한 파일 목록
    examples: string[];      // 유사 작업 예시
  };
  
  // 4. 사용 가능한 도구 제한
  allowedTools: string[];
  
  // 5. 결과 포맷 지정
  expectedOutput: {
    format: string;
    deliverables: string[];
  };
}

[메인 에이전트 -> 서브에이전트]
 
역할: src/auth/ 모듈의 단위 테스트 작성자
 
작업:
- src/auth/middleware.ts의 verifyToken 함수에 대한 단위 테스트 작성
- 기존 테스트 패턴을 따를 것 (src/auth/__tests__/ 참조)
- 엣지 케이스: 만료된 토큰, 잘못된 형식, 빈 토큰
 
완료 기준:
- 모든 테스트가 pnpm test 통과
- 커버리지 80% 이상
- 기존 테스트와 일관된 스타일
 
참조 파일:
- src/auth/middleware.ts (테스트 대상)
- src/auth/types.ts (타입 정의)
- src/auth/__tests__/jwt.test.ts (테스트 패턴 예시)

interface AgentMessage {
  from: AgentId;
  to: AgentId;
  type: "request" | "response" | "notification";
  
  // 핵심만 포함 (전체 컨텍스트가 아닌 결과물만)
  payload: {
    summary: string;       // 한 줄 요약
    artifacts?: string[];  // 생성/수정된 파일 경로
    decisions?: string[];  // 내린 결정사항
    blockers?: string[];   // 차단 요소
  };
}