에이전트에게 더 많은 토큰은 필요하지 않다. 필요한 것은 잘못된 파일의 개수를 줄이는 것이다.

버그 수정을 맡긴 에이전트가 실패했습니다. 본능적인 반응은 전체 레포지토리를 컨텍스트에 붙여넣는 것입니다. 200K 창문(window)이 있으니, 사용하세요.

두 번의 실행 후에도 여전히 잘못된 모듈을 수정합니다. 코드를 읽지 못해서가 아니라, 한 번에 50개의 파일을 읽고 있었기 때문에 중요한 파일이 그 더미 속에서 사라진 것입니다.

컨텍스트가 많다고 해서 좋은 컨텍스트는 아니다

대규모 컨텍스트 창문은 우리가 에이전트에게 _줄 수 있는 것_을 바꿨습니다. 하지만 에이전트가 그것을 _사용하는 방식_은 바꾸지 못했습니다. 모델은 여전히 최근 토큰과 구조적으로 유사한 패턴에 가중치를 부여하며—관련 없는 40개의 파일을 넣으면, 신호 대 잡음비(signal-to-noise ratio)가 무너집니다.

실제 사례에서 이를 볼 수 있습니다: 에이전트에게 프로젝트의 전체 node_modules와 세 개의 핵심 파일만 주어도, 코드를 분석하기보다 라이브러리 패턴 매칭을 시작합니다. 제안하는 수정 사항은 일반적인 의미에서는 작동하지만, 사용자의 특정 버그에는 작동하지 않습니다.

병목 현상은 _모델이 파일을 볼 수 있는가_에서 _모델이 어떤 파일이 중요한지 판단할 수 있는가_로 바뀌었습니다.

실제로 제공해야 할 것들

많은 시행착오 끝에, 일관되게 효과를 보는 세트는 사람들이 예상하는 것보다 작습니다:

• 전체 서브시스템이 아니라, 버그나 기능과 직접 관련된 3~5개의 파일.
• 정확한 에러 출력 — 스택 트레이스(stack trace), 실패한 단언문(failing assertion), 또는 잘못된 것처럼 보이는 네트워크 응답.
• 모듈이 무엇을 _하는지_가 아니라, 모듈이 무엇을 위해 존재하는지를 설명하는 README나 설계 노트 하나.

그게 전부입니다. 주변 코드 30개는 도움이 되기보다 오히려 해가 되는 경우가 많습니다.

테스트: 만약 에이전트가 이 세 가지 정보만으로 버그를 해결할 수 없다면, 문제는 컨텍스트 크기가 아니라 아직 문제의 경계(boundary)를 격리하지 못했다는 것입니다. 더 많은 파일은 그것을 고치지 못합니다. 문제를 좁히는 것이 할 일입니다.

위치를 얻는 단 하나의 파일로서의 명세서

버그가 API 경계에 닿을 때, 가장 효과적인 파일은 계약 자체입니다. 즉, 사후에 작성된 마크다운 문서가 아니라 OpenAPI 스펙입니다. 이 스펙이 엔드포인트가 실제로 무엇을 하는지 알려주며, 에이전트는 그 변화를 기계적인 기준에 맞춰 재확인할 수 있습니다.

이것이 우리가 로컬 OAS 파일 주변으로 Powerduck을 구축한 이유 중 하나입니다. 이 파일은 코드가 변경되어도 정확성을 유지하는 유일한 컨텍스트 조각이며, 에이전트는 사람이 올바른 섹션을 붙여넣기를 기다리는 대신 MCP를 통해 직접 이를 질의할 수 있습니다. 이는 '여기 20개 파일 있어, 행운을 빌어'라는 상황을 '계약은 여기, 실패하는 요청은 여기, 시작해'로 대체합니다.

직관에 반하는 부분

컨텍스트가 적으면 위험하게 느껴집니다. 에이전트가 중요한 것을 놓치면 어쩌죠?

하지만 그 위험은 모든 것을 쏟아부을 때 이미 존재합니다. 에이전트는 항상 무언가를 놓칩니다. 문제는 그것이 중요한 것인지, 그리고 당신이 그것을 놓치지 않았는지 확인할 수 있는지 여부입니다.

파일 세 개에 계약서 하나가 실제로 검토할 수 있는 세트입니다. 모호한 '괜찮아 보여'라는 말과 함께 파일 40개는 그렇지 않습니다.

다음번에 에이전트가 잘못된 것을 얻었을 때, 더 많은 코드를 붙여넣기 전에 물어보세요. 올바른 세 개의 파일을 받았는지, 아니면 틀린 50개의 파일을 받았는지요?