본문으로 건너뛰기

컨텍스트 엔지니어링: 에이전트에게 무엇을 보여줄까

에이전트의 성능은 모델보다 컨텍스트 구성에 더 크게 좌우됩니다. 컨텍스트 예산, 관련 파일 선정, 압축 전략을 정리합니다.

· 3분 읽기

컨텍스트 엔지니어링: 에이전트에게 무엇을 보여줄까

개요

코딩 에이전트를 쓰면서 같은 모델인데도 어떤 날은 잘하고 어떤 날은 엉뚱한 결과를 내는 경험을 반복했습니다. 원인을 들여다보니 대부분 프롬프트가 아니라 컨텍스트, 즉 모델에게 무엇을 보여주었는가의 문제였습니다. 컨텍스트 윈도우가 커졌다고 해서 “다 넣으면 된다”는 전략이 통하지 않는 이유는 모델의 유효 주의력(attention)이 입력 길이에 따라 희석되고, 비용과 지연시간도 입력에 비례하기 때문입니다. 이 글에서는 컨텍스트를 예산을 다루듯 관리하는 방법을 정리합니다.

컨텍스트는 예산이다

컨텍스트 윈도우를 하나의 예산으로 생각하면 설계가 명확해집니다. 대략 이런 비율로 나눠 쓰고 있습니다.

  • 시스템 프롬프트·도구 정의: 고정 비용. 가능한 한 다이어트.
  • 과제 설명·제약 조건: 짧을수록 좋고, 우선순위가 높은 정보.
  • 코드·문서 등 근거 자료: 회수(retrieval)로 선별.
  • 대화 이력: 길어질수록 압축 대상.
  • 출력 여유: 답을 생성할 공간. 꽉 채우고 시작하면 안 됩니다.

여기서 핵심은 “예산이 크다고 낭비해도 되는 게 아니다”입니다. 관련 없는 파일이 컨텍스트에 들어 있으면 모델은 그것을 근거로 삼아버릴 때가 있습니다. 빈칸이 아니라 오답이 들어가는 쪽이 더 위험합니다.

관련 파일 선정: 정확도와 재현율 사이

코드베이스 질의에서는 후보를 넓게 모으고 정밀하게 좁히는 2단계가 잘 통했습니다.

def select_context(query: str, repo, budget_tokens: int) -> list[str]:
    # 1단계: 넓게 수집 - 파일 경로, 심볼 이름, 임베딩 유사도로 후보 30~50개
    candidates = repo.search(query, top_k=50)

    # 2단계: 좁히기 - 정의부 우선, import 체인 따라가며 예산 안에서 채우기
    selected, used = [], 0
    for chunk in rank_by_relevance(candidates, query):
        cost = count_tokens(chunk)
        if used + cost > budget_tokens:
            continue
        selected.append(chunk)
        used += cost
    return selected

선정할 때 의외로 효과가 컸던 휴리스틱 두 가지입니다. 첫째, 파일 전체보다 관련 함수·클래스 단위로 잘라 넣기. 파일 전체를 넣으면 관련 없는 코드가 함께 들어가 희석이 발생합니다. 둘째, “질문에 언급된 심볼의 정의 위치”를 반드시 포함하기. 모델은 정의를 못 보면 그럴듯하게 지어내는 경향이 있습니다.

컨텍스트 배치도 성능에 영향을 준다

무엇을 넣을지 정했다면 어디에 넣을지도 정해야 합니다. 긴 컨텍스트에서는 시작과 끝 부분의 정보가 상대적으로 잘 활용되는 경향이 보고되어 있어, 저는 지시사항은 앞·뒤에 두고 근거 자료는 중간에 배치합니다. 여러 파일을 넣을 때는 호출 관계의 순서(호출하는 쪽 → 호출되는 쪽)로 배열하면 모델이 흐름을 따라가는 것 같았습니다. 사소해 보이지만, 같은 내용을 순서만 바꿔서 결과 품질이 달라지는 걸 몇 번 확인하고 나서 배치도 설계 요소로 취급하게 됐습니다.

압축 전략: 오래 살아남는 대화 다루기

장기 과제를 하는 에이전트는 대화 이력이 계속 늘어납니다. 이력을 통째로 들고 가면 비용이 선형으로 늘고, 어차피 초반의 잡담 같은 세부 사항은 뒤의 결정에 거의 쓰이지 않습니다. 그래서 주기적으로 요약 압축을 합니다.

압축할 때 지키는 규칙은 “사실은 남기고 과정은 버린다”입니다.

  • 남길 것: 확정된 결정 사항, 파일 경로, 인터페이스 시그니처, 아직 못 끝낸 할 일, 사용자가 명시한 제약.
  • 버릴 것: 시도했다 실패한 경로의 상세(한 줄 요약만), 중간 로그, 이미 해결된 디버깅 과정.
SUMMARIZE_PROMPT = """아래 대화를 작업 수행용 메모로 압축하세요.
반드시 포함: 확정된 결정, 다룬 파일 경로, 함수 시그니처, 남은 할 일, 사용자 제약.
버릴 것: 실패한 시도의 상세 로그, 해결된 디버깅 과정.
형식: 불릿 목록, 500토큰 이내."""

def maybe_compress(history: list, threshold: int) -> list:
    if count_tokens(history) < threshold:
        return history
    return [llm(SUMMARIZE_PROMPT, history[:threshold])] + history[threshold:]

압축은 손실 압축이라는 점을 받아들여야 합니다. 중요한 사실은 원본에서 메모리(파일이나 데이터베이스)로 옮겨두고, 컨텍스트에는 포인터만 남기는 설계가 손실을 줄입니다.

관측: 무엇이 들어갔는지 기록하기

컨텍스트 엔지니어링은 한 번 설계하고 끝나지 않습니다. 저는 매 실행마다 “어떤 청크가 선정되었고 각각 몇 토큰이었는지”를 로그로 남깁니다. 나중에 결과가 이상할 때 어떤 근거를 봤는지 추적할 수 있어야 원인이 컨텍스트인지 모델인지 구분할 수 있습니다. 선정 로직을 고칠 때도 이 로그가 회귀 테스트 역할을 합니다.

마무리

컨텍스트 엔지니어링의 본질은 프롬프트를 잘 쓰는 기교가 아니라, 제한된 예산 안에서 모델이 과제를 해결하는 데 필요한 근거를 최소 비용으로 전달하는 시스템 설계입니다. 예산을 정하고, 선정을 2단계로 하고, 이력을 주기적으로 압축하고, 무엇을 넣었는지 기록하기. 이 네 가지 습관만으로도 같은 모델으로 만들 수 있는 결과의 품질이 눈에 띄게 달라집니다. 모델을 바꾸는 것보다 먼저 시도해볼 가치가 충분합니다.

Related