에이전트 실패 로그 300개를 분석했습니다. 문제는 프롬프트가 아니었습니다.

에이전트 실패 로그 300개. 2주에 걸쳐 하나하나 읽으면서 근본 원인별로 태그를 달았습니다. 결과는 예상 밖이었습니다. 프롬프트 문제는 약 12%에 불과했습니다. 나머지는 전부 context가 오염되거나, 넘쳐흐르거나, 아예 없는 경우였습니다. 모델을 바꿔도 소용없었고, 도구를 교체해도 마찬가지였습니다. 패턴은 매번 동일했습니다.

저는 context engineering을 꽤 오래 연구해왔는데, Agent Skills for Context Engineering이라는 오픈소스 프로젝트가 등장해 GitHub 스타 1만 개를 빠르게 돌파했다는 소식을 들었을 때 바로 주목했습니다. MIT 라이선스로 공개된 이 프로젝트는 Muratcan Koylan이라는 context engineer가 만들었고, 베이징대학교 AI 연구실 논문에도 인용된 바 있습니다. 마지막 부분이 바로 제가 직접 클론하게 된 계기였습니다.

작은 context window가 더 정확합니다

저는 토큰을 많이 넣을수록 좋다고 생각했습니다. 틀렸습니다. 이 스킬셋이 가르쳐주는 첫 번째 원칙은 “정보의 양이 아니라 정보 밀도”입니다.

context가 길어질수록 모델은 중간 내용을 놓치기 시작합니다. 이른바 U-curve 효과입니다. 모델은 앞부분과 뒷부분은 잘 읽지만 그 사이는 대충 훑어봅니다. 직접 실험해봤습니다. context를 128K 토큰으로 채운 뒤, 동일한 정보를 32K로 압축했습니다. 압축된 버전이 정확도 점수에서 더 높게 나왔습니다.

처리 비용은 토큰 수에 선형으로 비례하지 않고 지수적으로 증가합니다. context를 절반으로 줄이자 응답 지연이 40~60% 단축됐습니다. prefix caching을 사용하더라도 긴 입력은 여전히 비쌉니다. 한 줄 요약: 주어진 토큰 예산 안에 얼마나 유용한 정보를 압축하느냐가 핵심입니다.

도구 설명이 에이전트 성능의 80%를 결정합니다

프롬프트를 완벽하게 작성해도 도구 설명이 엉성하면 에이전트는 잘못된 도구를 선택합니다. 이 스킬셋은 이를 명확하게 표현합니다. “도구는 사람이 아닌 LLM이 읽는 계약서다.” 저희 팀이 MCP 서버를 구축할 때 이 가이드를 따라 도구 설명을 전면 재작성했더니 도구 선택 오류가 눈에 띄게 줄었습니다.

각 도구 설명에는 언제 사용하는지, 무엇을 반환하는지가 명시되어야 합니다. 두 도구의 기능이 겹치면 사람도 헷갈리지만 에이전트는 더 심하게 혼란스러워합니다. 좁은 도구 여러 개보다 포괄적인 도구 하나가 대개 낫습니다. 그리고 에러 메시지는 무엇이 잘못됐는지만 알려주는 것이 아니라 다음에 무엇을 해야 하는지도 알려줘야 합니다.

멀티 에이전트 시스템은 에이전트보다 아키텍처가 먼저입니다

에이전트를 여러 개 띄워놓고 알아서 협업하기를 기대하는 건 희망 사항일 뿐입니다. 이 레포지토리는 세 가지 패턴을 명확하게 정의합니다. 오케스트레이터가 하위 에이전트를 지휘하는 방식, 에이전트들이 동등하게 소통하는 P2P 방식, 그리고 계층적 위임 체인 방식입니다.

세 가지를 모두 프로덕션에서 시도해본 결과, 오케스트레이터 패턴이 가장 예측 가능하고 디버깅하기도 쉬웠습니다. 하위 에이전트는 파일 시스템을 통해 결과를 전달했습니다. P2P 모델은 창의적인 작업에는 효과적이었지만 무한 루프 위험이 있었습니다. 구조화된 쿼리에는 vector search보다 공유 파일이 더 실용적이었습니다. 실제로 운영해보면 에이전트 3개가 안정성의 한계였습니다.

Vector search만으로는 메모리를 처리할 수 없습니다

Vector search는 “고객 X가 날짜 Z에 상품 Y를 구매했다”는 정보는 쉽게 찾습니다. 하지만 “상품 Y를 구매한 고객들이 함께 구매한 것은?”에는 답하지 못합니다. 관계형 정보는 임베딩 과정에서 사라집니다.

이 스킬셋은 4계층 메모리 아키텍처를 제안합니다. context window 내부의 working memory, 세션 내 short-term memory, 세션 간 long-term memory, 그리고 아카이브로서의 permanent memory입니다. 제가 테스트한 것 중 가장 실용적인 패턴은 파일 시스템을 메모리로 활용하는 방식이었습니다. 임베딩 쿼리 대신 ls와 grep으로 context를 탐색합니다. 도구 결과를 스크래치패드 파일에 저장했더니 context window 공간을 상당히 절약할 수 있었습니다.

평가(Evaluation)는 가장 저평가된 에이전트 스킬입니다

거의 건너뛸 뻔한 섹션이었는데, 결국 가장 가치 있는 내용이었습니다. 이 레포지토리에는 LLM을 심사위원으로 활용하는 TypeScript evaluation 프레임워크가 포함되어 있습니다. 채점 기준(rubric)도 자동으로 생성해줍니다.

인상적이었던 것은 position-bias 완화 방식이었습니다. 두 응답을 나란히 비교할 때, 프레임워크는 순서를 바꿔서 두 번 평가합니다. 이는 먼저 제시된 답변을 더 좋게 평가하는 경향을 상쇄합니다. 직접 점수 매기기와 쌍별 비교를 모두 지원합니다. evaluation 파이프라인을 구축하고 나서야 프롬프트 변경이 실제로 성능을 개선했는지 추측이 아닌 측정으로 확인할 수 있게 됐습니다.

다만 이 레포지토리가 해결하지 못한 부분이 하나 있습니다. 평가 기준은 여전히 사람의 교정이 필요합니다. 자동 생성된 rubric은 합리적인 출발점을 제공했지만, 결과를 신뢰하기까지 제 도메인에 맞게 채점 비중을 직접 조정해야 했습니다.

에이전트가 틀린 결과를 냈다면, 모델을 탓하기 전에 먼저 context를 확인해보세요. 레포지토리는 여기에 있습니다.