컨텍스트 엔지니어링 대 프롬프트 엔지니어링: 에이전트 실패 진단 방법

에이전트가 API를 통합하는 데 실패했습니다. 누군가가 프롬프트를 다시 작성하고 재실행하자 성공합니다. 일주일 후, 동일한 방식으로 실패했고, 그 원인이 지침(instruction) 때문인지, 오래된 문서 페이지 때문인지, 노이즈가 많은 도구 결과 때문인지, 아니면 에이전트가 사용 방법을 모르는 도구 때문인지를 아무도 말할 수 없습니다.

프롬프트 엔지니어링은 지침을 작성하고 구성하는 것입니다. 컨텍스트 엔지니어링은 에이전트가 행동할 때 보는 모든 것(지침, 메시지 기록, 검색된 증거, 도구 정의 및 결과, 참고 자료, 상태)을 관리하는 것입니다. Anthropic은 컨텍스트 엔지니어링을 "LLM 추론 과정 동안 최적의 토큰(정보) 세트를 큐레이션하고 유지하기 위한 전략들의 집합"으로 정의하고, 프롬프트 엔지니어링을 "최적의 결과를 얻기 위해 LLM 지침을 작성하고 구성하는 방법들"로 정의합니다.

두 가지는 겹치는 부분이 있으며, 어느 한쪽이 다른 쪽을 대체하지 않습니다. 에이전트가 실패했을 때 더 넓은 시야를 갖는 것이 유용합니다: 모델과 작업을 고정시키고 컨텍스트 요인 중 하나를 변경한 다음, 반복 실행의 트레이스(traces)와 비교하여 결과를 판단하는 것입니다. 이 절차는 Anthropic의 평가 지침, Google의 에이전트 프레임워크 설계, 그리고 트레이스를 재현하는 실무자들의 조언을 조합하여 작성된 본 기사의 자체 방법론입니다.

요약 (TL;DR)

프롬프트 엔지니어링은 지침을 형성합니다. 컨텍스트 엔지니어링은 지침을 포함하여 에이전트가 보는 모든 것을 관리합니다.
모델과 작업을 고정시키고 한 번에 하나의 컨텍스트 요인만 변경하여 실패를 진단하세요.
실행하기 전에 성공 기준을 정의하고, 모든 트레이스를 보관하며, 깨끗한 환경에서 여러 번의 시도를 수행하세요.
컨텍스트 탓을 하기 전에 모델 제한, 권한 문제, 런타임 오류, 작업 모호성을 배제하세요.

에이전트가 행동할 때 보는 것

Anthropic의 문서에 따르면 요청의 모든 내용이 컨텍스트 창(context window)에 포함됩니다. 여기에는 시스템 프롬프트(system prompt), messages 내의 모든 메시지(도구 결과, 이미지 및 문서를 포함), 그리고 도구 정의가 포함됩니다. [LangChain]은 컨텍스트를 지침(instructions), 지식(knowledge), 도구(tools)로 분류합니다. Anthropic이 2026년 7월 24일에 발표한 [Claude 5 가이드라인]에서는 다음과 같이 추가했습니다: "프롬프트와 달리, 컨텍스트는 여러 요청에 걸쳐 일반적으로 사용되므로 그렇게 구체적일 수 없습니다."

이는 검사해야 할 여섯 가지 구성 요소를 제공합니다:

지침(Instructions): 시스템 프롬프트(system prompt), 작업 텍스트(task text), 규칙 파일(rules files).
메시지 및 기록(Messages and history): 이전 대화 턴(turns)과 그 요약본.
검색된 증거(Retrieved evidence): 작업을 수행하는 동안 가져온 문서 페이지와 검색 결과.
도구 설명 및 도구 결과(Tool descriptions and tool results).
참고 자료(Reference material): 사양(specs), 예시, 그리고 미리 제공되는 변경 로그(changelogs).
관련 상태(Relevant state): 메모리(memory), 저장소(repository), 그리고 단계 간에 전달되는 모든 것.

컨텍스트가 정확도를 저하시킬 수 있음

동일한 Anthropic 페이지는 모델에 따라 최대 1M 토큰의 컨텍스트 창을 나열한 후 다음과 같이 말합니다: "더 큰 컨텍스트 창은 모델이 더 복잡하고 긴 프롬프트를 처리할 수 있게 하지만, 컨텍스트가 많다고 해서 무조건 좋은 것은 아닙니다. 토큰 수가 증가함에 따라 정확도(accuracy)와 재현율(recall)이 저하되는데, 이는 _컨텍스트 부패(context rot)_라고 알려진 현상입니다. 따라서 컨텍스트 내부에 무엇을 구성할지 선별하는 것이 사용 가능한 공간의 양만큼이나 중요합니다."

Hangfei Lin은 Google 기술 리더로서 Google Developers Blog에서 ADK 컨텍스트 스택에 대해 글을 쓰면서 다음과 같이 동의합니다: "대형 컨텍스트 창은 컨텍스트 관련 문제에 도움이 되지만, 모든 컨텍스트 관련 문제를 해결하지는 못할 것입니다." 그는 '관련 없는 로그로 가득 찬(flooded) 창은 모델을 산만하게 하여 과거 패턴에 집착하게 만들 수 있다'고 경고합니다. 이름이 지정되고 순서가 정해진 프로세서를 통해 컨텍스트를 구축하는 것은 '컴파일(compilation)' 단계를 관찰 가능하고 테스트할 수 있게 만듭니다.

2025년 7월, Chroma가 이전 세대 LLM 18개를 테스트한 결과 성능은 입력 길이가 증가함에 따라 '점점 더 신뢰하기 어려워지는' 것으로 나타났습니다. 추가 토큰은 에이전트가 무언가를 부족하게 느낄 때 도움이 됩니다. 하지만 노이즈나 모순을 추가할 때는 해롭습니다. 창 안에 무엇이 있었는지에 대해 다음 여섯 가지 질문을 던져보세요:

선택(Selection): 올바른 항목들이 포함되었는가?
신선도(Freshness): API 버전에 맞춰 최신 정보인가?
관련성(Relevance): 각 항목이 이 작업과 관련이 있는가?
충분성(Sufficiency): 빠진 것이 없는가?
충돌(Conflicts): 두 항목이 서로 모순되는가?
타이밍(Timing): 각 항목이 에이전트가 필요로 할 때 도착했는가?

배치(Placement)에 대한 조언은 모델에 따라 다릅니다. Google의 Gemini 장문 컨텍스트 문서에 따르면, 대부분의 경우 특히 장문 컨텍스트를 사용할 때는 쿼리 또는 질문을 프롬프트의 끝(다른 모든 컨텍스트 이후)에 배치하는 것이 성능상 더 좋습니다. OpenAI의 GPT-4.1 프롬프팅 가이드는 장문 컨텍스트를 사용할 경우 '제공된 컨텍스트의 시작과 끝 양쪽에 지침을 배치하는 것이 이상적'이라고 말합니다. Anthropic의 Claude 5 가이드는 이전 Claude 모델들이 때때로 컨텍스트 창의 시작점보다 끝점에서 지침에 더 귀 기울일 가능성이 있다고 언급했습니다. 사용하려는 모델 버전에 맞는 조언을 확인하세요.

이것은 이름만 바뀐 프롬프트 엔지니어링인가요?

Hacker News에서 mentalgear는 다음과 같이 작성했습니다: "지금 그것을 '프롬프트 엔지니어링'이라고 부르든 '컨텍스트 엔지니어링'이라고 부르든 상관없습니다. 비결정론적 공간(non-deterministic space)에서 '작동하는 것'을 찾기 위한 동일한 조작이기 때문입니다." 지지자인 DAIR.ai는 프롬프트 엔지니어링이 "너무 중요해서 이제 컨텍스트 엔지니어링으로 리브랜딩되고 있다"고 작성합니다.

이 부분은 일리가 있습니다. 그 원칙들은 더 넓은 범위로 확장됩니다. Anthropic의 Claude 5 가이드는 "반복하기(repeat yourself)"를 "간단한 도구 설명(simple tool descriptions)"으로 대체하며 다음과 같이 보고합니다: "Claude Opus 5 및 Claude Fable 5와 같은 모델에 대해 Claude Code의 시스템 프롬프트 중 80% 이상을 제거했지만, 코딩 평가에서 측정 가능한 손실은 없었습니다." 이것은 공급업체가 보고한 내부 결과입니다. 해당 게시물은 그 방법을 설명하지 않으며, Claude Code와 특정 모델로 범위가 한정되어 있습니다.

그 양보는 특정 모델에 대한 지침 스캐폴딩(instruction scaffolding)을 다룰 뿐입니다. 오래된 문서 페이지, 서로 모순되는 두 개의 출처, 또는 잡음이 많은 도구 결과물에 대해서는 아무것도 말하지 않습니다. 같은 스레드에서 0xdeafcafe는 "'에이전트 실패'의 상당 부분이 가정, 잘못된 에이전트 결정, 또는 컨텍스트에 숨겨진 비대화(bloat)로 거슬러 올라간다"고 작성했습니다. 지침은 여전히 중요합니다. 에이전트가 읽는 문서, 출처, 도구 결과물 또한 마찬가지입니다.

진행되는 예시: 가상의 웹훅 작업 (The running example: a hypothetical webhook task)

여기서부터 모든 예시는 가상의 것이며 실행된 적이 없습니다. 귀사가 가상의 결제 API인 ExamplePay를 출시한다고 가정해 봅시다. 이의 v3 릴리스는 웹훅 시그니처 헤더 이름을 X-ExamplePay-Signature에서 ExamplePay-Signature로 변경하고, verify_v2() 헬퍼 함수를 사용 중단(deprecated)했습니다. 자체 평가(evals)에서 고객의 코딩 에이전트가 할 것처럼, 샘플 웹훅 핸들러에 ExamplePay 시그니처 검증을 추가하도록 에이전트에게 요청합니다.

첫 실행 전에 트레이스에서 확인할 수 있는 성공 기준을 작성합니다: tests/webhooks의 테스트가 통과해야 합니다; 핸들러는 ExamplePay-Signature를 읽어야 합니다; diff에는 verify_v2() 호출이 없어야 합니다; 에이전트는 완료(done)를 보고하기 전에 테스트를 실행해야 합니다.

모든 실행의 전체 트랜스크립트를 유지합니다. Anthropic의 평가 가이드는 이를 "출력, 도구 호출(tool calls), 추론(reasoning), 중간 결과 등을 포함한 시도의 완전한 기록"으로 정의합니다.

진단 플레이북 (The diagnosis playbook)

소유자(Owners): DevEx 리드가 태스크와 그 기준을 소유합니다. 한 엔지니어가 트라이얼을 실행하고 트레이스를 보관합니다. 에이전트가 검색하는 문서 및 학습 자료를 유지 관리하는 사람이 증거 수정(evidence fixes)을 담당합니다.

입력값(Inputs): 실패한 태스크, 고정된 모델 버전(pinned model version), 전체 트레이스, 각 호출에 전송된 컨텍스트, 그리고 기준입니다.

주기(Cadence): 누군가 프롬프트를 수정하기 전에 태스크가 실패할 때 실행합니다. 모델 버전, 문서 또는 도구가 변경될 때마다 성공 여부 확인을 재실행합니다.

모델 버전, 태스크 텍스트, 도구 세트 및 하네스를 고정하고 기록합니다.
실패가 공정한지 확인합니다. 평가 가이드(evals guide)에서는 "실패는 공정해 보여야 합니다: 에이전트가 무엇을 잘못했는지, 그리고 왜 그랬는지 명확해야 합니다."라고 말합니다.
컨텍스트 외부의 원인을 배제합니다 (다음 섹션 참조).
트레이스를 읽습니다: 에이전트가 무엇을 검색했는지, 어떤 인자(arguments)와 함께 어떤 도구를 호출했는지, 그리고 무엇이 돌아왔는지 확인합니다. Anthropic의 도구 설계 가이드는 "에이전트가 피드백과 응답에서 생략하는 내용이 포함하는 내용보다 더 중요할 때가 많다"고 언급합니다.
하나의 컨텍스트 요소를 지정하고 그것만 변경합니다.
기준에 따라 동일한 환경에서 여러 트라이얼(trials)을 실행하고, 각각은 깨끗한 환경(clean environment)에서 진행합니다.
결과는 워크시트에 기록합니다.

컨텍스트 실패를 다른 모든 것과 분리하기

Tian Pan의 디버깅 분류법(debugging taxonomy)은 '사용자 의도 불명확(Under-specified user intent)', '가드레일 발동(Triggered guardrails)', '지원되지 않는 요청(Unsupported requests)', 그리고 '시스템 오류(System failures)'를 분리하여 다룹니다. 컨텍스트를 수정하기 전에 이 항목들을 확인하세요:

모델 역량(Model capability): 컨텍스트는 정확하고, 최신이며, 충분하고, 깨끗하지만 작업이 여러 시도에 걸쳐 실패하는 경우. 별도의 실험으로 다른 모델을 테스트해 보세요.
권한(Permissions): 에이전트가 필요한 접근 권한이 부족했거나, 가져서는 안 되는 접근 권한을 가졌던 경우.
도구 또는 런타임 오류(Tool or runtime failure): '시스템 오류'에는 '시간 초과(timeouts), API 오류, 에이전트가 올바르게 처리하지 못하는 속도 제한(rate limits)' 등이 포함됩니다. 시스템이나 에이전트의 오류 처리를 수정한 다음 다시 실행해 보세요.
작업 모호성(Task ambiguity): 올바른 결과가 무엇인지 아무도 정의할 수 없는 경우. 작업을 수정하고 새로운 기준선(baseline)을 시작하세요.

동일한 작업에 대한 네 가지 진단 방법

각 사례는 서로 다른 실패 실행에서 시작됩니다. 모델 버전과 환경은 고정되고, 하나의 컨텍스트 요소만 변경됩니다.

1. 불명확한 지침 또는 누락된 성공 기준(Unclear instructions or missing success criteria)

에이전트가 테스트를 실행하지 않고 핸들러를 수정하고 성공을 선언하는 경우입니다. DX는 완료 기준(completion criteria)이 누락된 에이전트는 "실행 루프에 빠지거나, 조기에 중단하거나, 추론한 목표를 기준으로 성공을 선언하는..." 문제를 겪는다고 지적합니다. 변경 사항: 작업 텍스트에 성공 기준을 추가하세요.

HYPOTHETICAL TRACE, NOT EXECUTED
Before
[tool_call]   edit_file webhooks/examplepay.py
...

2. 오래된 버전 또는 API 증거(Stale version or API evidence)

에이전트가 v2 코드를 작성하는 이유는 문서 검색(docs search) 결과에서 v2 페이지를 받았기 때문입니다. DX는 에이전트가 “오래된 지침을 바탕으로 자신 있게 추론한다(reason confidently from stale guidance)”고 경고합니다. 해결책: 문서 드리프트(documentation drift)를 수정하여 문서 소스가 v3 페이지를 제공하도록 합니다. 두 페이지가 모두 나타날 경우, v2는 제거해야 합니다. Drew Breunig은 이를 [컨텍스트 충돌(context clash)]이라고 부르며 다음과 같이 설명합니다: “컨텍스트 내에 새로운 정보와 도구를 축적하는 과정에서 컨텍스트의 다른 정보와 상충되는 부분이 생길 때.”

HYPOTHETICAL TRACE, NOT EXECUTED
Before
[tool_result] ExamplePay API v2: verify X-ExamplePay-Signature with verify_v2()
...

3. 과도한 관련 없는 정보(Excess irrelevant information)

컨텍스트에 v3 페이지, 모든 변경 로그(changelog), 그리고 무관한 청구 재시도 워커의 로그가 포함되어 있습니다. 에이전트는 이 로그들에서 재시도 로직을 복사하는데, 이는 Google이 설명하는 고착화 현상입니다. DX는 관련 없는 자료가 “모델의 주의력(attention)을 두고 경쟁한다”고 말합니다. 해결책: 로그를 제거해야 합니다.

HYPOTHETICAL TRACE, NOT EXECUTED
Before
[assistant]   로그에 서명 불일치로 인한 재시도가 표시됩니다. 백오프(backoff)와 함께 재시도를 추가합니다.
...

4. 누락된 도구 또는 도구 사용 지침(Missing tool or tool-use guidance)

에이전트가 잘못된 인자(argument)로 테스트 도구를 호출하고, 불분명한 오류(opaque error)를 받으며 테스트를 건너뜁니다. Anthropic의 도구 설계 지침은 도구를 “팀의 신규 직원에게 설명하듯이” 설명해야 하며, “불분명한 오류 코드(opaque error codes)” 대신 “실행 가능한 개선 사항(actionable improvements)”을 반환해야 한다고 합니다. 해결책: 도구 정의 하나를 재작성합니다. Claude 5 생성 모델의 경우, Claude 5 지침은 시스템 프롬프트보다는 도구 설명에 도구 사용 방법을 명시하도록 권장합니다. GPT-4.1 가이드 역시 각 도구에 대해 “명확하고 상세한 설명”을 요구합니다.

HYPOTHETICAL TRACE, NOT EXECUTED
Before
[tool_def]    run_tests: "테스트를 실행합니다."  parameter: target
...