컨텍스트 엔지니어링 (Context Engineering)이란 무엇인가?

프롬프트 엔지니어링 (Prompt engineering)은 더 잘 질문하는 것에 관한 것입니다.

컨텍스트 엔지니어링 (Context engineering)은 모델이 작업하는 동안 무엇을 알게 할지 결정하는 것에 관한 것입니다.

이는 작은 변화처럼 들릴 수 있지만, AI로 구축하는 방식 자체를 바꿉니다. 프롬프트는 단일 응답을 돕는 데 유용할 수 있습니다. 하지만 모델이 도구 (tools), 파일 (files), 메모리 (memory), 테스트 (tests), 재시도 (retries), 그리고 실제 작업의 여러 단계에 걸쳐 작동해야 할 때는 컨텍스트 엔지니어링 (Context engineering)이 필요합니다.

대부분의 에이전트 (agent) 실패는 프롬프트 내의 문장 하나가 잘못되어 발생하는 것이 아닙니다. 모델이 잘못된 작업 세트 (working set)를 보고 있을 때 발생합니다. 즉, 너무 많은 히스토리 (history), 누락된 파일 (missing files), 오래된 결정 (stale decisions), 거대한 로그 (huge logs), 과거의 실패한 시도 (old failed attempts), 또는 현재 단계와 더 이상 일치하지 않는 지침 (instructions) 등이 원인입니다.

컨텍스트 윈도우 (context window)는 서류 보관함이 아닙니다. 그것은 작업대 (workbench)입니다. 모든 것을 작업대 위에 쌓아두면 유용한 부분들이 파묻히게 됩니다.

짧은 정의

컨텍스트 엔지니어링 (Context engineering)은 AI 시스템이 각 단계에서 받는 정보를 선택, 형성, 저장, 검색, 압축 및 격리하는 관행입니다.

여기에는 다음이 포함됩니다:

• 사용자 요청 (user request)
• 시스템 지침 (system instructions)
• 관련 파일 (relevant files)
• 검색된 문서 (retrieved documentation)
• 예시 (examples)
• 도구 정의 (tool definitions)
• 도구 결과 (tool results)
• 메모리 (memory)
• 이전 결정 (previous decisions)
• 오류 노트 (error notes)
• 수락 기준 (acceptance criteria)
• 현재 작업 상태 (the current task state)

목표는 컨텍스트를 최대화하는 것이 아닙니다. 목표는 모델에게 다음 행동을 위한 올바른 컨텍스트를 제공하는 것입니다.

때로는 더 많은 정보를 추가하는 것을 의미합니다. 때로는 정보를 제거하는 것을 의미합니다. 때로는 다음 단계에서 깨끗하게 검색할 수 있도록 채팅 외부(outside the chat)에 정보를 작성하는 것을 의미하기도 합니다.

이것이 왜 실제적인 문제가 되었는가

초기 프롬프트 엔지니어링 (prompt engineering)은 주로 단일 호출 (single calls)을 다루었습니다: 이 이메일을 작성하라, 이 문서를 요약하라, 이 함수를 생성하라, 이 오류를 설명하라.

에이전트 (Agents)는 다릅니다.

에이전트 (Agents)는 계획을 세우고, 도구 (tools)를 호출하며, 파일을 검사하고, 수정하고, 명령어를 실행하고, 실패를 읽고, 재시도하며, 최종 답변을 준비할 수 있습니다. 이는 긴 컨텍스트 (context)의 흔적을 만들어냅니다. 그중 일부는 유용하지만, 일부는 노이즈 (noise)입니다. 어떤 것은 5분 전에는 유용했을지 모르지만 지금은 해로울 수도 있습니다.

코딩 에이전트 (Coding agents)를 보면 이를 쉽게 확인할 수 있습니다.

중간 규모의 기능을 작업하는 에이전트를 상상해 보십시오. 에이전트는 티켓 (ticket)으로 시작하여, 리포지토리 (repo)를 스캔하고, 계획을 초안하고, 몇 개의 파일을 수정하고, 테스트를 실행하고, 오류를 마주하고, 오류를 패치하고, 더 많은 테스트를 실행하고, 두 번째 문제를 발견한 다음, 다시 시도합니다.

만약 모든 단계가 전체 대화 기록 (transcript)을 계속 상속받는다면, 모델은 다음과 같은 것들을 계속 들고 다니게 됩니다:

• 오래된 계획들
• 버려진 접근 방식들
• 수정된 오류로부터 발생한 스택 트레이스 (stack traces)
• 더 이상 디스크와 일치하지 않는 파일 내용들
• 시도의 특정 분기에서만 관련이 있었던 도구 출력값
• 모델의 추측과 뒤섞인 사용자의 수정 사항

시간이 지나면, 에이전트는 더 이상 깔끔한 작업을 해결하는 것이 아니라, 작업에 더해 이전 모든 시도의 침전물 (sediment)을 함께 해결하게 됩니다.

이것이 바로 컨텍스트 부패 (context rot)입니다.

더 큰 컨텍스트 윈도우 (context windows)가 그 자체로 문제를 해결하지는 않습니다

더 큰 컨텍스트 윈도우 (context window)는 모델에게 더 많은 공간을 제공합니다. 하지만 무엇이 그 공간에 속해야 하는지를 결정해주지는 않습니다.

이것이 중요한 이유는 에이전트의 컨텍스트가 단순히 "더 많은 텍스트"가 아니기 때문입니다. 그것은 지시 사항, 증거, 상태 (state), 그리고 도구 접근 권한 (tool access)이 결합된 살아있는 묶음입니다. 잘못된 컨텍스트는 정답이 기술적으로 윈도우 어딘가에 있더라도 모델을 잘못된 행동으로 끌어들일 수 있습니다.

인간의 업무에서도 동일한 현상을 볼 수 있습니다. 개발자에게 현재 티켓, 대상 파일, 그리고 가장 최근에 실패한 테스트를 주면 그들은 집중할 수 있습니다. 하지만 그들에게 지난 한 주간의 모든 슬랙 (Slack) 메시지, 모든 오래된 브랜치 (branch), 모든 실패한 패치, 그리고 모든 로그를 준다면, 그들은 코드를 작성하기 전에 고고학 (archaeology) 작업을 먼저 수행해야 합니다.

모델도 판단력이 더 부족할 뿐, 동일한 문제를 겪고 있습니다.

컨텍스트 엔지니어링 (Context engineering) vs 프롬프트 엔지니어링 (Prompt engineering)

프롬프트 엔지니어링 (Prompt engineering)은 다음과 같이 질문합니다:

• 요청을 어떻게 표현해야 하는가?
• 모델이 어떤 역할을 수행해야 하는가?
• 어떤 예시를 포함해야 하는가?
• 어떤 출력 형식 (output format)을 원하는가?

컨텍스트 엔지니어링 (Context engineering)은 다음과 같이 질문합니다:

• 이 단계에서 무엇을 알아야 하는가?
• 채팅 외부의 어디에 무엇을 저장해야 하는가?
• 지금 무엇을 검색 (retrieve)해야 하는가?
• 무엇을 요약 (summarize)해야 하는가?
• 이 단계에서 무엇을 숨겨야 하는가?
• 어떤 도구 (tool) 결과가 유지할 가치가 있는가?
• 에이전트 (agent)가 언제 새로 시작해야 하는가?
• 어떤 아티팩트 (artifact)가 진실의 근원 (source of truth)인가?

둘 다 중요합니다. 좋은 프롬프팅 (prompting)은 여전히 도움이 됩니다. 하지만 시스템이 메모리 (memory), 도구 (tools), 파일 (files), 그리고 여러 단계 (multiple steps)를 갖게 되면, 프롬프트는 환경의 일부분일 뿐입니다.

네 가지 실질적인 움직임

컨텍스트 엔지니어링을 생각하는 유용한 방법은 다음과 같습니다: 작성 (write), 선택 (select), 압축 (compress), 격리 (isolate).

1. 중요한 상태 (state)를 기록하기

대화 기록 (conversation transcript)만을 유일한 메모리로 의존하지 마세요.

중요한 상태를 내구성이 있는 아티팩트 (durable artifacts)에 기록하세요:

• 요구사항 (requirements)
• 결정 사항 (decisions)
• 계획 (plans)
• 수락 기준 (acceptance criteria)
• 구현 노트 (implementation notes)
• 테스트 결과 (test results)
• 실패 요약 (failure summaries)
• 리뷰 노트 (review notes)

이렇게 하면 시스템에 채팅 기록보다 더 깔끔한 무언가를 제공할 수 있습니다. 이후 단계에서는 이를 생성하는 과정에서 발생한 모든 잘못된 시작 (false start)들을 끌고 올 필요 없이, 현재의 PRD나 최신 실패 노트를 불러올 수 있습니다.

코딩 에이전트 (coding agents)의 경우, 파일, 사양 (specs), 테스트 보고서 (test reports)를 긴 모델 대화 기록보다 검토하기가 더 쉽기 때문에 이것이 특히 유용합니다.

2. 지금 중요한 것만 선택하기

각 단계는 가장 작으면서도 유용한 작업 세트 (working set)를 전달받아야 합니다.

에이전트가 계획을 세우고 있다면, 티켓 (ticket), 리포지토리 구조 (repo structure), 관련 파일, 그리고 사용자 제약 사항 (user constraints)이 필요할 수 있습니다.

만약 에이전트가 하나의 작은 작업만 편집하고 있다면, 다음 항목들만 필요할 수 있습니다:

• 활성 작업 (active task)
• 대상 파일 (target files)
• 수락 기준 (acceptance criteria)
• 지난 실패로부터 얻은 간결한 노트 (compact note)
• 작업을 검증하기 위해 실행해야 할 명령 (command)

모델은 단순히 이전에 발생했다는 이유만으로 모든 계획 초안이나 모든 오래된 도구 호출 (tool call)을 가질 필요가 없습니다.

선택(Selection)은 많은 에이전트 시스템이 실패하는 지점입니다. 이들은 너무 많은 정보를 검색하거나, 잘못된 것을 검색하거나, 혹은 모든 이전 컨텍스트 (context)를 똑같이 중요한 것으로 취급합니다.

3. 노이즈가 있는 정보 압축하기 (Compress noisy information)

어떤 정보는 살아남아야 하지만, 전체 형태 그대로일 필요는 없습니다.

2,000줄짜리 테스트 로그에는 단 하나의 유용한 사실이 포함되어 있을 수 있습니다. 예를 들어, 모킹(mocked)된 사용자에게 이메일 주소가 없어서 하나의 어설션 (assertion)이 실패했다는 사실 말입니다. 재시도 (retry) 시에는 로그 전체가 필요하지 않습니다. 실패에 대한 메모가 필요할 뿐입니다.

훌륭한 압축은 지저분한 컨텍스트를 유용한 작업 메모리 (working memory)로 변환합니다:

이전 시도가 실패했습니다. 이유는 비밀번호 재설정 테스트가 이메일이 없는 사용자를 생성하기 때문입니다.
다시 실행하기 전에 픽스처 (fixture)를 업데이트하거나 이메일 접근을 방어하세요:
npm test -- password-reset

나쁜 압축은 중요한 세부 사항을 숨깁니다:

테스트 실패. 다시 시도하세요.

핵심은 모든 것을 요약하는 것이 아닙니다. 핵심은 다음 행동을 변화시키는 요소를 보존하는 것입니다.

4. 단계 격리하기 (Isolate phases)

계획 (planning), 코딩 (coding), 재시도 (retrying), 테스트 (testing), 그리고 리뷰 (reviewing)는 모두 동일한 컨텍스트 형태를 공유해서는 안 됩니다.

플래너 (planner)는 넓은 컨텍스트로부터 이득을 얻습니다. 코더 (coder)는 좁은 컨텍스트로부터 이득을 얻습니다. 리뷰어 (reviewer)는 최종 디프 (diff), 요구사항, 그리고 검증 결과로부터 이득을 얻습니다. 재시도는 종로 깨끗한 세션과 하나의 압축된 실패 메모리가 더해졌을 때 종종 이득을 얻습니다.

이것이 많은 사람들이 놓치는 부분입니다. 컨텍스트 엔지니어링 (context engineering)은 단순히 검색 (retrieval)만이 아닙니다. 어떤 정보가 경계를 넘지 않아야 하는지를 결정하는 것이기도 합니다.

나쁜 컨텍스트의 모습

나쁜 컨텍스트는 보통 처음에는 편리하게 느껴집니다:

모델에게 모든 것을 다 주세요.
채팅 전체를 유지하세요.
전체 로그를 붙여넣으세요.
...

그렇게 하면 잠시는 작동합니다. 그러다 에이전트가 이상한 선택을 하기 시작합니다.

그렇게 하면 잠시는 작동합니다. 그러다 에이전트가 이상한 선택을 하기 시작합니다.

[이번 청크]
오래된 파일 덤프가 여전히 기록(transcript)에 남아있기 때문에 잘못된 파일을 수정합니다. 실패했던 시도가 근처에 남아있기 때문에 같은 아이디어를 반복합니다. 거대한 도구 결과(tool result)가 실제 작업을 초점에서 밀어냈기 때문에 승인 기준을 잊습니다. 계획 초안을 마치 승인된 것처럼 취급합니다.

모델이 게을러진 것이 아닙니다. 작업 집합(working set)이 오염된 것입니다.

좋은 컨텍스트란 무엇인가

좋은 컨텍스트는 가장 좋은 방식으로 지루합니다.

명시적입니다:

Current phase: implementation
Active task: add empty-state copy to the media manager
Target files:
...

범위가 좁습니다:

Do not modify campaign logic.
Do not change media upload behavior.
Do not run full end-to-end tests.

유용한 실패 정보만 전달합니다:

Last attempt broke keyboard focus because the empty-state container replaced the upload button.
Keep the upload button outside the conditional empty-state block.

이러한 종류의 컨텍스트는 모델이 잘못된 방향으로 즉흥적으로 행동할 여지를 줄여줍니다.

컨텍스트 엔지니어링은 단순히 RAG가 아니다

검색 증강 생성(Retrieval augmented generation, RAG)은 컨텍스트 엔지니어링 안에 있는 하나의 기술일 뿐입니다. 이는 시스템이 문서(docs), 파일, 메모리(memories), 또는 데이터베이스에서 관련 정보를 가져오는 데 도움을 줍니다.

하지만 컨텍스트 엔지니어링은 더 광범위합니다.

도구 설계(tool design), 메모리 설계, 아티팩트 설계, 단계 경계(phase boundaries), 재시도 동작(retry behavior), 인간 승인 게이트(human approval gates), 그리고 도구 결과의 형태까지 포함합니다.

예를 들어, 50개의 도구를 가진 에이전트는 모든 도구 정의가 항상 로드된다면 성능이 떨어질 수 있습니다. 시스템은 현재 단계에 어떤 도구가 속하는지 결정해야 합니다. 파일, 예시(examples), 메모리, 이전 메시지에 대해서도 마찬가지입니다.

RAG는 질문합니다: 무엇을 가져와야 하는가?

컨텍스트 엔지니어링은 질문합니다: 이 모델이 무엇을 알아야 하고, 무엇을 할 수 있도록 허용되어야 하며, 그 후에 무엇이 살아남아야 하는가?

에이전트 빌더를 위한 체크리스트

진지한 에이전트 워크플로우를 구축하기 전에 다음 질문을 해보세요:

• 해당 작업의 신뢰할 수 있는 원천(Source of Truth)은 무엇인가?
• 단계 사이에 어떤 결과물(Artifacts)이 유지되어야 하는가?
• 어떤 이전 메시지들을 폐기해야 하는가?
• 이 단계에서 가장 작고 유용한 컨텍스트(Context)는 무엇인가?
• 모델이 지금 당장 어떤 도구(Tools)를 확인해야 하는가?
• 대규모 도구 결과물은 어떻게 저장되어야 하는가?
• 시도가 실패한 후에는 어떤 일이 일어나야 하는가?
• 실행 전에 사람이 계획을 검토할 수 있는가?
• 병합(Merge) 전에 사람이 최종 차이(Diff)를 검토할 수 있는가?

만약 이 질문들 중 대부분에 대한 답이 "채팅에 들어 있다"라면, 그 시스템은 취약합니다.

LoopTroop이 컨텍스트 엔지니어링을 적용하는 방식

LoopTroop은 AI 코딩의 이러한 문제, 즉 모든 단계가 하나의 끝없는 채팅 안에 머물 때 긴 작업이 점점 더 악화되는 문제를 중심으로 구축되었습니다.

LoopTroop은 로컬 Git 저장소에서 코딩 티켓(Coding tickets)을 실행하기 위한 로컬 오픈 소스 GUI 앱입니다. 모든 코딩 에이전트를 대체하려는 것이 아닙니다. 이는 계획(Planning), 분할(Splitting), 실행(Execution), 재시도(Retries), 로그(Logs), 검토 결과물(Review artifacts), 그리고 사람의 승인(Human approval)과 같은 더 긴 작업 과정을 관리하는 오케스트레이션 계층(Orchestration layer)입니다.

관련된 구성 요소는 다음과 같습니다:

• 계획을 위한 LLM Council
• 지속 가능한 사양(Specs)으로서의 PRD
• 작은 구현 단위인 Beads
• 실행 계층으로서의 OpenCode
• 격리된 저장소 작업을 위한 Git worktrees
• 실패하거나 멈춘 Beads를 위한 Ralph Loop 재시도
• 중요한 전환 전의 인간 게이트(Human gates)

중요한 컨텍스트 엔지니어링(Context engineering) 전략은 각 단계가 서로 다른 작업 세트(Working set)를 갖게 된다는 점입니다.

Council은 넓은 관점에서 계획을 살펴보고 비교할 수 있습니다. PRD는 신뢰할 수 있는 원천(Source of truth)이 됩니다. Beads는 큰 작업을 수락 기준(Acceptance criteria)과 검증 명령(Validation commands)을 가진 더 작은 단위로 변환합니다. 실행 단계는 프로젝트 전체 이력 대신 한 번에 하나의 Bead만 전달받습니다. 만약 Bead가 실패하면, Ralph Loop는 간결한 노트를 저장하고, 시도를 초기화하며, 오염된 세션(Polluted session)을 그대로 끌고 가는 대신 새로운 컨텍스트(Fresh context)로 재시도합니다.

그것이 바로 컨텍스트 엔지니어링 (Context Engineering)의 실질적인 버전입니다. 즉, 유용한 상태 (Useful state)는 유지하고, 노이즈 (Noise)는 버리며, 각 단계에서 모델에게 깨끗한 작업 (Clean job)을 부여하는 것입니다.

작은 수정 사항의 경우, 직접적인 채팅 (Direct chat)이나 에디터 에이전트 (Editor agent)만으로도 충분한 경우가 많습니다. 하지만 여러 파일을 수정하거나 여러 번의 재시도 (Retries)가 필요한 더 큰 티켓 (Tickets)의 경우, 컨텍스트 엔지니어링이야말로 에이전트의 검토 가능성 (Reviewability)을 유지해 주는 핵심 요소입니다.