컨텍스트 하네스란 무엇인가
큰 코드베이스에서 AI 에이전트가 엉뚱한 파일을 건드리는 이유는 모델 자체의 성능 문제가 아닙니다. 너무 적거나 반대로 너무 많은 정보, 즉 관련 없는 파일, 오래된 대화, 실패한 가설 등이 섞여 작업의 초점이 흐려졌기 때문입니다.
컨텍스트 하네스(Context Harness)는 에이전트가 목적의식을 잃지 않게 필요한 정보는 충분히 제공하되, 필요 없는 정보는 차단하여 '올바른 첫 번째 행동'을 유도하는 설계 방법입니다. 단순히 프롬프트에 지시를 나열하는 것을 넘어, 정보를 구조화하여 제공하는 것이 핵심입니다.
컨텍스트 설계의 4가지 핵심 요소
무작정 정보를 던져주는 대신, 컨텍스트를 다음 4가지 영역으로 명확히 구분하여 제공해야 에이전트가 정보의 우선순위를 파악할 수 있습니다.
- Instruction (지시 및 규칙): 에이전트가 어떻게 행동해야 하는지에 대한 규칙입니다. 예를 들어 "테스트 없이 완료를 선언하지 말 것", "API 응답 스키마를 임의로 바꾸지 말 것", "비즈니스 로직을 직접 작성하지 말 것"과 같은 지시가 해당합니다.
- Context (배경 정보): 현재 작업을 이해하는 데 필요한 배경입니다. 프로젝트 구조, 관련 파일 위치, 현재 브랜치, 사용 중인 프레임워크 및 런타임 환경 등을 포함합니다.
- Evidence (관찰 자료): 현재 발생한 문제를 보여주는 구체적인 근거입니다. 실패한 테스트 아웃풋, Stack trace, Docker 빌드 에러, CI 로그 등이 여기에 속합니다.
- State (상태 및 진행 기록): 지금까지 진행된 작업의 기록입니다. 이미 시도한 해결책, 실패한 가설, 변경된 파일 목록, 서브 에이전트의 결과 등을 명시하여 에이전트가 같은 실수를 반복하지 않도록 합니다.
효율적인 컨텍스트 패킹과 작업 흐름
전체 프로젝트를 통째로 에이전트에게 던지는 것은 비효율적입니다. 에이전트가 작업할 수 있는 '작업면'만 잘라서 제공해야 하며, 이를 컨텍스트 팩(Context Pack)이라고 부릅니다.
예를 들어 단순히 "로그인 버그 고쳐줘"라고 요청하는 대신, "현재 API 로그인에서 500 에러가 발생하고 있으며 관련 로그는 아래와 같다. 인증 관련 파일 후보는 A, B, C에 있으니 먼저 원인 후보를 3개 이하로 좁힌 다음에 수정할 파일을 제안해라"와 같이 작업면을 좁혀주는 것이 좋습니다.
이러한 요청을 바탕으로 에이전트는 다음과 같은 이상적인 작업 흐름을 따라야 합니다.
- 탐색 (Explore): 관련 파일과 코드를 분석하여 상황을 파악합니다.
- 계획 (Plan): 문제의 원인을 특정하고 수정 방안을 수립합니다.
- 수정 (Edit): 계획에 따라 코드를 변경합니다.
- 검증 (Verify): 변경 후 문제가 해결되었는지 테스트합니다.
지시와 제약의 분리: 실행 하네스로의 이관
컨텍스트 윈도우는 무한하지 않은 희소 자원이며, 시간이 지남에 따라 정보가 압축되면서 세부 내용이 손실될 수 있습니다. 따라서 지시 사항과 물리적 제약을 명확히 분리해야 합니다.
CLAUDE.md나 Auto Memory에 규칙을 적어두는 것은 에이전트가 '더 잘 따를 수 있도록' 배경지식을 제공하는 역할을 할 뿐, 행동을 물리적으로 강제하지는 못합니다. 반복되는 아키텍처 규칙은 문서화하되, 이것만으로 모든 방어가 가능하다고 믿어서는 안 됩니다.
절대로 위반해서는 안 되는 규칙, 예를 들어 수정 금지 영역 등은 단순 텍스트 지시에만 의존해서는 안 됩니다. Permissions나 Hooks와 같은 기계적인 실행 하네스(Execution Harness) 영역으로 옮겨 시스템적으로 차단해야 합니다.
에이전트가 엉뚱한 행동을 할 때 해결법
에이전트가 잘못된 수정안을 내놓거나 헤맬 때, 흔히 하는 실수는 설명을 더 덧붙이거나 구조 없이 더 많은 정보를 프롬프트에 우겨넣는 것입니다. 이는 오히려 상황을 악화시킵니다.
컨텍스트 재설계
정보를 더 주는 대신, 관련 있는 파일과 없는 파일을 다시 나누고 수정 금지 범위를 명확히 설정해야 합니다.
새 세션 열기
이미 대화 흐름이 오염되어 잘못된 가설이 대화 기록에 쌓였다면, 에이전트는 이를 기정사실로 받아들이고 더 정교한 오답을 만들어낼 위험이 있습니다. 이때는 미련을 버리고 현재 가설을 폐기한 뒤, 깨끗한 상태의 새로운 세션을 여는 것이 가장 효과적인 해결책입니다.