본문으로 건너뛰기
Kreath Archive
TechProjectsBooksAbout
TechProjectsBooksAbout

내비게이션

  • Tech
  • Projects
  • Books
  • About
  • Tags

카테고리

  • AI / ML
  • 웹 개발
  • 프로그래밍
  • 개발 도구

연결

  • GitHub
  • Email
  • RSS
© 2026 Kreath Archive. All rights reserved.Built with Next.js + MDX
홈TechProjectsBooksAbout
//
  1. 홈
  2. 테크
  3. 4장: 컨텍스트 선택과 검색 전략
2026년 3월 14일·AI / ML·

4장: 컨텍스트 선택과 검색 전략

코드베이스에서 관련 파일을 정밀하게 선택하는 기법을 다룹니다. @-멘션 시스템, RAG 기반 코드 검색, 의존성 그래프 추적, 변경 영향 분석을 분석합니다.

16분549자9개 섹션
aiai-agentclaude-codellm
공유
context-engineering4 / 10
12345678910
이전3장: CLAUDE.md와 AGENTS.md 고급 전략다음5장: 컨텍스트 압축과 정보 밀도 최적화

이 장에서 배우는 것

  • 컨텍스트 선택이 중요한 이유: 정밀도와 재현율의 균형
  • 명시적 선택: @-멘션과 수동 파일 지정
  • 암묵적 선택: 자동 컨텍스트 수집 메커니즘
  • RAG 기반 코드 검색의 원리와 한계
  • 의존성 그래프 추적과 변경 영향 분석
  • 선택 품질 측정 방법

왜 선택이 가장 중요한 전략인가

컨텍스트 엔지니어링의 5가지 전략 중 선택(Selection)이 가장 근본적입니다. 아무리 정교한 압축이나 정렬 기법을 적용하더라도, 애초에 잘못된 정보를 선택했다면 결과는 좋을 수 없습니다.

선택의 품질은 두 가지 축으로 평가합니다.

메트릭정의위험
정밀도(Precision)선택한 파일 중 실제로 관련 있는 비율낮으면 노이즈 증가
재현율(Recall)관련 있는 전체 파일 중 실제로 선택한 비율낮으면 핵심 정보 누락

이상적인 선택은 높은 정밀도와 높은 재현율을 동시에 달성하는 것이지만, 현실에서는 트레이드오프가 존재합니다. 너무 많이 선택하면 노이즈가 증가하고, 너무 적게 선택하면 필요한 정보가 빠집니다.

명시적 선택: 사용자가 직접 지정

@-멘션 시스템

현대적 AI 코딩 도구들은 @-멘션 시스템을 통해 사용자가 직접 컨텍스트를 지정할 수 있게 합니다.

@-멘션 예시
text
@src/auth/middleware.ts 이 미들웨어에 rate limiting을 추가해주세요.
@src/auth/ 디렉토리의 패턴을 참고해서 작성해주세요.
@types/auth.d.ts 이 타입 정의를 사용해야 합니다.

도구별 @-멘션 지원 범위는 다음과 같습니다.

도구파일 멘션디렉토리 멘션심볼 멘션URL 멘션
Claude Code지원지원부분 지원MCP 통해 가능
Cursor지원지원지원지원
GitHub Copilot지원지원 (@workspace)지원부분 지원

태그 기반 컨텍스트

일부 도구는 코드 내 태그를 통해 컨텍스트를 선택할 수 있습니다.

src/auth/middleware.ts
typescript
// @context: 인증 미들웨어의 핵심 로직
// @related: src/auth/jwt.ts, src/auth/types.ts
// @pattern: Express middleware chain
 
export function verifyToken(req: Request, res: Response, next: NextFunction) {
  const token = extractBearerToken(req.headers.authorization);
  if (!token) {
    return res.status(401).json({ error: "Token required" });
  }
  // ...
}
Info

명시적 선택은 정밀도가 높지만, 사용자가 관련 파일을 모두 알고 있어야 한다는 제약이 있습니다. 복잡한 코드베이스에서는 사용자 자신도 어떤 파일이 관련 있는지 모를 수 있으며, 이때 암묵적 선택이 보완 역할을 합니다.

암묵적 선택: 자동 컨텍스트 수집

에이전트가 자동으로 관련 컨텍스트를 수집하는 방식입니다.

열린 파일 기반 선택

가장 단순한 형태로, 현재 에디터에서 열려 있는 파일들을 컨텍스트에 포함합니다.

open-files-context.ts
typescript
interface OpenFileContext {
  // 현재 활성 파일 (가장 높은 우선순위)
  activeFile: FileContent;
  
  // 열린 탭의 파일들 (최근 접근 순)
  openTabs: FileContent[];
  
  // 최근 수정한 파일들
  recentlyModified: FileContent[];
}

Import 추적 기반 선택

현재 파일의 import 문을 분석하여 의존하는 파일들을 자동으로 포함합니다.

import-tracing.ts
typescript
async function traceImports(filePath: string, depth: number = 2): Promise<string[]> {
  const content = await readFile(filePath);
  const imports = parseImportStatements(content);
  
  const resolved: string[] = [];
  for (const imp of imports) {
    const resolvedPath = resolveImportPath(imp, filePath);
    resolved.push(resolvedPath);
    
    // 재귀적 추적 (depth 제한)
    if (depth > 1) {
      const nested = await traceImports(resolvedPath, depth - 1);
      resolved.push(...nested);
    }
  }
  
  return [...new Set(resolved)]; // 중복 제거
}

변경 기반 선택

Git 히스토리를 분석하여 함께 변경되는 경향이 있는 파일들을 포함합니다.

change-based-selection.ts
typescript
async function findCoChangedFiles(
  filePath: string,
  lookback: number = 100
): Promise<FileCorrelation[]> {
  // 최근 N개 커밋에서 함께 변경된 파일 분석
  const commits = await getCommitsContaining(filePath, lookback);
  const coChanges = new Map<string, number>();
  
  for (const commit of commits) {
    const files = await getCommitFiles(commit);
    for (const file of files) {
      if (file !== filePath) {
        coChanges.set(file, (coChanges.get(file) ?? 0) + 1);
      }
    }
  }
  
  // 동시 변경 빈도가 높은 순으로 정렬
  return [...coChanges.entries()]
    .map(([file, count]) => ({ file, correlation: count / commits.length }))
    .sort((a, b) => b.correlation - a.correlation);
}

RAG 기반 코드 검색

RAG(Retrieval-Augmented Generation) 기반 코드 검색은 사용자의 자연어 질의를 코드베이스의 관련 부분과 매칭하는 기법입니다.

동작 원리

코드 청킹 전략

코드를 벡터 인덱스에 저장하기 위해서는 적절한 단위로 분할해야 합니다.

청킹 전략설명장점단점
파일 단위전체 파일을 하나의 청크로맥락 보존큰 파일에서 노이즈
함수 단위함수/메서드별 분할정밀한 매칭함수 간 관계 손실
클래스 단위클래스 전체를 하나로캡슐화 보존크기 불균형
슬라이딩 윈도우고정 크기 + 겹침균일한 크기의미 경계 무시
AST 기반구문 트리 구조 활용의미 단위 보존구현 복잡
ast-based-chunking.ts
typescript
function chunkByAST(sourceCode: string): CodeChunk[] {
  const ast = parse(sourceCode);
  const chunks: CodeChunk[] = [];
  
  // 최상위 선언 단위로 분할
  for (const node of ast.body) {
    switch (node.type) {
      case "FunctionDeclaration":
      case "ClassDeclaration":
      case "ExportNamedDeclaration":
      case "ExportDefaultDeclaration":
        chunks.push({
          content: sourceCode.slice(node.start, node.end),
          type: node.type,
          name: getNodeName(node),
          startLine: node.loc.start.line,
          endLine: node.loc.end.line,
        });
        break;
    }
  }
  
  return chunks;
}

RAG의 한계

RAG 기반 검색은 효과적이지만 한계도 있습니다.

  • 의미적 간극: "인증 로직"을 검색해도 verifyToken이라는 이름의 함수를 찾지 못할 수 있습니다
  • 관계 파악 부족: 파일 간의 의존 관계나 호출 관계를 포착하지 못합니다
  • 컨텍스트 의존성: 동일한 코드라도 어떤 맥락에서 검색하느냐에 따라 관련도가 달라집니다

의존성 그래프 추적

코드의 구조적 관계를 활용한 선택 전략입니다.

의존성 그래프를 활용하면 두 가지 방향의 탐색이 가능합니다.

하향식(Downstream): "이 파일이 의존하는 것은 무엇인가?" -- import하는 모듈, 사용하는 타입을 추적합니다.

상향식(Upstream): "이 파일에 의존하는 것은 무엇인가?" -- 이 파일을 import하는 모듈, 이 파일의 함수를 호출하는 코드를 추적합니다.

dependency-graph-selection.ts
typescript
async function selectByDependencyGraph(
  targetFile: string,
  direction: "downstream" | "upstream" | "both",
  maxDepth: number = 2
): Promise<string[]> {
  const graph = await buildDependencyGraph();
  const selected = new Set<string>();
  
  function traverse(file: string, depth: number) {
    if (depth > maxDepth || selected.has(file)) return;
    selected.add(file);
    
    if (direction === "downstream" || direction === "both") {
      for (const dep of graph.getDependencies(file)) {
        traverse(dep, depth + 1);
      }
    }
    
    if (direction === "upstream" || direction === "both") {
      for (const dep of graph.getDependents(file)) {
        traverse(dep, depth + 1);
      }
    }
  }
  
  traverse(targetFile, 0);
  return [...selected];
}

변경 영향 분석

특정 변경이 미치는 영향 범위를 분석하여 관련 파일을 선택하는 기법입니다.

impact-analysis.ts
typescript
interface ImpactAnalysis {
  // 직접 영향: 변경된 파일을 직접 참조하는 파일
  directImpact: string[];
  
  // 간접 영향: 직접 영향 파일을 참조하는 파일
  indirectImpact: string[];
  
  // 테스트 영향: 변경으로 인해 실행해야 하는 테스트
  affectedTests: string[];
  
  // 타입 영향: 변경된 타입을 사용하는 파일
  typeImpact: string[];
}
 
async function analyzeImpact(changedFiles: string[]): Promise<ImpactAnalysis> {
  const graph = await buildDependencyGraph();
  
  const directImpact = new Set<string>();
  const indirectImpact = new Set<string>();
  
  // 1단계: 직접 영향
  for (const file of changedFiles) {
    for (const dependent of graph.getDependents(file)) {
      directImpact.add(dependent);
    }
  }
  
  // 2단계: 간접 영향
  for (const file of directImpact) {
    for (const dependent of graph.getDependents(file)) {
      if (!directImpact.has(dependent) && !changedFiles.includes(dependent)) {
        indirectImpact.add(dependent);
      }
    }
  }
  
  // 3단계: 영향받는 테스트 식별
  const affectedTests = await findAffectedTests([
    ...changedFiles,
    ...directImpact,
  ]);
  
  return {
    directImpact: [...directImpact],
    indirectImpact: [...indirectImpact],
    affectedTests,
    typeImpact: await findTypeImpact(changedFiles),
  };
}
Warning

변경 영향 분석은 정적 분석의 한계를 가집니다. 동적 임포트, 리플렉션, 문자열 기반 참조 등은 정적 분석으로 추적하기 어렵습니다. 완벽한 분석보다는 "충분히 좋은" 분석을 목표로 하고, 놓친 부분은 테스트로 보완하는 것이 현실적입니다.

선택 전략의 조합

실전에서는 단일 전략이 아닌, 여러 전략을 조합합니다.

각 전략의 결과를 병합할 때, 여러 전략에서 동시에 선택된 파일에 더 높은 관련도 점수를 부여합니다. 명시적으로 멘션된 파일, Import로 연결된 파일, RAG로 검색된 파일이 모두 같은 파일을 가리킨다면, 그 파일은 컨텍스트에 반드시 포함되어야 합니다.


요약

컨텍스트 선택은 5가지 전략 중 가장 근본적인 전략입니다. 명시적 선택(@-멘션, 수동 지정)과 암묵적 선택(Import 추적, RAG 검색, 변경 기반 분석, 의존성 그래프)을 조합하여 정밀도와 재현율의 균형을 맞춥니다.

핵심은 필요한 정보를 빠짐없이 포함하되, 불필요한 정보는 철저히 배제하는 것입니다. 이를 위해 의존성 그래프 추적과 변경 영향 분석이 특히 효과적이며, 여러 선택 전략의 결과를 병합하여 신뢰도를 높이는 앙상블 접근이 권장됩니다.

다음 장에서는 선택한 정보를 효율적으로 줄이는 컨텍스트 압축 전략을 다룹니다. 토큰 한계와 비용을 최적화하면서 핵심 의미를 보존하는 코드 요약, 인터페이스 추출, 트리 구조 압축 등의 기법을 살펴봅니다.

이 글이 도움이 되셨나요?

관련 주제 더 보기

#ai#ai-agent#claude-code#llm

관련 글

AI / ML

5장: 컨텍스트 압축과 정보 밀도 최적화

토큰 한계와 비용을 최적화하면서 핵심 의미를 보존하는 컨텍스트 압축 기법을 다룹니다. 코드 요약, 인터페이스 추출, 트리 구조 압축 등을 분석합니다.

2026년 3월 16일·15분
AI / ML

3장: CLAUDE.md와 AGENTS.md 고급 전략

CLAUDE.md와 AGENTS.md 컨텍스트 파일의 설계 원칙, 효과적인 구조화 방법, 컨텍스트 블로트의 위험성과 대응 전략을 심층 분석합니다.

2026년 3월 12일·16분
AI / ML

6장: 컨텍스트 정렬과 포맷 최적화

어텐션 메커니즘과 위치 편향을 이해하고, 정보 배치 전략과 XML/마크다운/JSON 포맷 비교를 통해 컨텍스트 구조를 최적화합니다.

2026년 3월 18일·15분
이전 글3장: CLAUDE.md와 AGENTS.md 고급 전략
다음 글5장: 컨텍스트 압축과 정보 밀도 최적화

댓글

목차

약 16분 남음
  • 이 장에서 배우는 것
  • 왜 선택이 가장 중요한 전략인가
  • 명시적 선택: 사용자가 직접 지정
    • @-멘션 시스템
    • 태그 기반 컨텍스트
  • 암묵적 선택: 자동 컨텍스트 수집
    • 열린 파일 기반 선택
    • Import 추적 기반 선택
    • 변경 기반 선택
  • RAG 기반 코드 검색
    • 동작 원리
    • 코드 청킹 전략
    • RAG의 한계
  • 의존성 그래프 추적
  • 변경 영향 분석
  • 선택 전략의 조합
  • 요약