에이전트의 컨텍스트를 필요한 시점에 구성하기

에이전트 작업에서는 초기 지침뿐 아니라 파일 본문, 도구 결과와 이전 판단도 다음 호출의 입력에 포함됩니다. 어떤 자료를 먼저 제공하고 어떤 자료를 필요할 때 읽을지 정해야 합니다.

컨텍스트 엔지니어링은 어떤 정보를 유지하고, 언제 불러오며, 무엇을 줄일지 설계하는 작업입니다. Anthropic의 컨텍스트 엔지니어링 가이드는 지침, 도구 결과, 필요한 시점의 자료 조회, 긴 작업의 상태 보존을 함께 다룹니다. 이 글에서는 코드 수정 작업의 예시로 각 정보를 제공할 시점을 구분합니다.

행동을 판단할 수 있는 지침

시스템 지침에는 에이전트가 수행할 작업과 따라야 할 조건을 적습니다. 지침이 지나치게 추상적이면 에이전트는 어떤 행동을 선택해야 할지 판단하기 어렵고, 모든 예외를 나열하면 어느 조건을 우선해야 할지 파악하기 어렵습니다.

“변경한 API의 성공 응답과 인증 실패 응답을 기존 검사로 확인한다”는 지침에는 실행할 일이 드러납니다. 검사할 API와 환경에 맞춰 명령을 선택할 수 있도록 판단 기준과 고정할 값을 나눠 적습니다.

직접 만든 정렬 조사 예시입니다. 그림에는 API 응답의 정상 순서와 화면에서 다시 정렬한 순서의 차이, 다음에 조사할 화면의 정렬 함수·테스트를 표시했습니다.

다음 호출에 필요한 도구 결과

에이전트가 검색할 때마다 저장소의 모든 파일을 반환할 필요는 없습니다. 우선 관련 파일과 위치를 찾고, 실제 수정 전에 필요한 본문을 읽으면 됩니다. 검색 결과의 짧은 조각만으로 구현하면 조건을 놓칠 수 있으므로 탐색과 확인을 구분합니다.

도구를 만드는 개발자는 비슷한 이름의 도구가 다른 조건으로 작동한다면 설명에 선택 기준을 적습니다. 오류 응답에는 원인과 재시도 가능한 조건을 넣어 에이전트가 다음 호출에서 바꿀 부분을 알 수 있게 합니다.

필요할 때 돌아가 읽는 자료

새로운 질문이 생길 때마다 자료를 처음부터 찾지 않도록, 돌아갈 위치는 남겨둘 수 있습니다. 파일 경로, 검색 조건, 자료 식별자를 보존하면 필요한 시점에 내용을 읽을 수 있습니다. 호출 결과에서는 파일의 존재와 접근 가능 여부를 확인합니다.

예를 들어 인증 오류를 수정한다면 현재 증상과 관련 라우트부터 확인하고, 인증 설정이 필요한 시점에 해당 파일을 읽습니다. 프로젝트의 전체 설계 문서를 먼저 읽는 것이 항상 도움이 되는 것은 아닙니다. 현재 문제를 판단할 수 있는 최소 자료에서 시작해 근거가 부족할 때 범위를 넓힙니다.

긴 작업에서 보존할 상태

대화가 길어지면 이전 내용을 압축하거나 별도 작업 기록에 남길 수 있습니다. 이때 보존할 것은 실행 내역 전체보다 목표, 승인된 범위, 결정 이유, 실패 원인, 검증 결과, 남은 작업입니다.

목표: 검색 결과의 잘못된 정렬 수정
확인: API 응답 순서는 정상, 화면에서 다시 정렬함
결정: 화면의 정렬 조건 수정
검증: 날짜가 같은 결과의 순서는 아직 확인 전
다음: 기존 검색 테스트에서 동일 날짜 사례 확인

정렬 오류 조사를 이어가기 위한 상태 기록의 예시입니다. 다음 세션의 에이전트는 화면의 정렬 조건부터 읽고 동일 날짜 사례를 검사할 수 있습니다. 요약에서 판단 근거가 빠졌다면 원문과 실행 결과를 다시 읽습니다.

별도 조사 결과의 전달 범위

작업을 나누면 각 작업자가 별도 맥락에서 조사할 수 있습니다. 그러나 결과를 통합하는 쪽에는 여전히 근거와 결론이 필요합니다. 하위 작업자가 전체 로그를 돌려주면 통합 단계의 입력이 다시 커질 수 있습니다.

조사 결과에는 확인한 파일과 위치, 결론, 불확실한 점, 필요한 다음 행동을 담으면 됩니다. 별도 작업자를 사용한다고 중복 조사나 충돌이 자동으로 사라지는 것은 아닙니다. 실제로 독립된 작업인지와 사용할 권한을 먼저 판단합니다.

기록을 압축한 뒤에는 이 상태만 읽고 다음 작업을 고를 수 있는지 살펴봅니다. 예시의 “API 응답 순서는 정상”과 “동일 날짜 사례는 미검증”이 빠지면 다음 세션은 완료한 조사를 반복하거나 남은 검사를 놓칠 수 있습니다.

각 호출에 전달할 정보는 다음 판단을 기준으로 선택합니다. 현재 증상과 확인한 근거는 함께 제공하고, 추가 자료는 다시 읽을 수 있는 위치를 남깁니다. 요약에 의존한 판단이 틀렸다면 원문으로 돌아가 누락된 조건을 확인합니다.