IT

에이전트 성능의 80%는 모델이 아니라 '맥락'에 있다: GitHub 1만 스타 스킬셋 정복기

메타인지 월드 2026. 2. 27. 08:51
반응형

에이전트 성능의 80%는 모델이 아니라 '맥락'에 있다: GitHub 1만 스타 스킬셋 정복기

최근 GitHub에서 뜨거운 반응을 얻고 있는 [Agent Skills for Context Engineering] 저장소를 뜯어봤습니다. 300개가 넘는 에이전트 실패 로그를 분석한 결과, 범인은 모델의 지능이 아니라 '오염되고 무질서한 맥락(Context)'이었습니다.

단순히 프롬프트를 고치는 수준을 넘어, 에이전트의 작업 환경을 혁명적으로 개선하는 5가지 핵심 원리와 실전 구축법을 공유합니다.

💡 1. 5가지 핵심 원칙: "지능보다 환경이 먼저다"

① 정보 밀도의 법칙: 뚱뚱한 서류보다 요약 포스트잇

토큰을 많이 넣는다고 좋은 게 아닙니다. AI도 사람처럼 중간 내용을 흘리는 'U자 커브' 현상을 겪습니다. 128K를 꽉 채우기보다 핵심만 압축한 32K가 훨씬 정확합니다. 양보다 밀도가 생명입니다.

② 도구는 '계약서'다: 모호한 지시는 사고의 원인

외부 MCP 도구 설명이 "검색 도구"처럼 짧으면 안 됩니다. "언제 호출하는지", "어떤 형태의 값을 주는지"를 법조문처럼 명확히 적어야 합니다. 도구 설명만 고쳐도 도구 선택 실패율이 80% 감소합니다.

③ 계층형 메모리 구조: 뇌의 저장 방식을 따라라

모든 걸 벡터 DB에 때려 넣지 마세요.

  • 작업 기억: 지금 대화 중인 핵심 정보.
  • 단기/장기 메모리: 세션 간의 기록.
  • 영구 기록: 파일 기반의 아카이브. 이렇게 층을 나눠야 에이전트가 "고객이 어제 말한 취향"을 정확히 기억합니다.

④ 총괄 에이전트(Orchestrator) 체제: 사공이 많으면 배가 산으로 간다

에이전트 여러 개를 그냥 풀어놓으면 서로 수다만 떱니다. 한 명의 매니저 에이전트가 하위 에이전트에게 업무를 배분하고 결과를 수집하는 '중앙 통제 방식'이 가장 예측 가능하고 디버깅도 쉽습니다.

⑤ 순서 뒤집기 평가: AI의 편견을 역이용하라

AI는 두 답변 중 앞에 있는 것을 더 좋게 평가하는 '위치 편향'이 있습니다. 답변 A와 B의 순서를 바꿔서 두 번 평가하는 시스템을 구축하세요. 이 간단한 과정이 에이전트의 품질을 객관적으로 보장합니다.

🛠 2. 실전 구축: 내 맥북에 '지능형 책상' 이식하기

Step 1. 공용 공구함(Global Skills) 설정

여러 프로젝트에서 돌려 쓸 핵심 로직을 한곳에 클론합니다.

git clone https://github.com/m-koylan/agent-skills.git ~/tools/agent-skills

Step 2. 심볼릭 링크로 '투명 통로' 만들기

프로젝트마다 코드를 복사할 필요 없습니다. 링크만 걸어주면 용량은 0이면서 최신 기능은 그대로 쓸 수 있습니다.

ln -s ~/tools/agent-skills/src ./agent-skills-core

Step 3. Claude를 '컨텍스트 마스터'로 만들기 (MCP)

이 깃허브의 유틸리티들을 Claude가 스스로 호출하게 만듭니다.

  • optimize_context: 대화가 길어지면 스스로 내용을 압축.
  • search_json_memory: 무거운 DB 대신 JSON 파일에서 관계 검색.

적용 방법

🟢 레벨 1: "코드 작성 없이 원칙만 적용하겠다" (Step 1만 활용)

가장 빠르게 적용하는 방법입니다. 깃허브의 가이드라인(Markdown 파일들)만 읽고 내 에이전트의 프롬프트와 도구 설명을 직접 수정하는 단계입니다.

  • 방법: 깃허브 클론 후 docs/ 폴더의 규칙들을 내 메모장에 요약해두고, 코딩할 때 '참고서'로 씁니다.
  • 효과: 도구 선택 정확도가 즉시 올라가고 에이전트의 답변 품질이 눈에 띄게 개선됩니다.

🟡 레벨 2: "내 프로젝트 코드에 직접 녹여내겠다" (Step 1 + 2 활용)

가장 실용적인 단계입니다. 깃허브의 **유틸리티 함수(압축, 메모리 검색 등)**를 내 프로젝트에 연결해서 실제로 작동하게 만드는 것입니다.

  • 방법: 심볼릭 링크를 걸어 내 코드에서 import { summarize } ... 처럼 깃허브의 기능을 직접 호출합니다.
  • 효과: 대화 로그가 길어질 때 자동으로 요약되거나, JSON 파일로 메모리를 관리하는 기능을 내 앱에 구현할 수 있습니다.

🔴 레벨 3: "Claude에게 관리 권한을 위임하겠다" (Step 1 + 2 + 3 모두 수행)

최종 완성형입니다. 내가 일일이 코드로 "압축해!", "검색해!"라고 시키는 게 아니라, Claude가 상황을 보고 "맥락이 복잡하니 제가 이 툴(MCP)을 써서 정리하겠습니다"라고 스스로 판단하게 합니다.

  • 방법: 깃허브 로직을 MCP 서버로 감싸서 Claude 설정에 등록합니다.
  • 효과: 어떤 프로젝트를 하든 Claude가 항상 '맥락 엔지니어링 도구'를 장착한 상태가 됩니다.

💡 추천하는 진행 순서

처음부터 3단계를 다 하려면 지칠 수 있으니, 아래 순서를 권장합니다.

  1. 일단 Step 1 + 2: 깃허브를 클론하고, 내 프로젝트에 심볼릭 링크를 걸어보세요. 그리고 가장 필요한 함수(예: 맥락 압축) 하나만 내 코드에 적용해 봅니다.
  2. 효과를 보면 Step 3: "오, 진짜 똑똑해지는데?"라는 확신이 들 때, 그 함수들을 MCP 서버로 묶어 Claude에게 정식 도구로 쥐여주면 됩니다.

 

🎯 결론: 모델 탓을 하기 전에 맥락을 먼저 청소하세요

에이전트가 자꾸 헛소리를 하나요? 모델을 업그레이드하기 전에 이 저장소의 원칙대로 맥락 엔지니어링을 시작해 보세요.

"에이전트의 실력은 당신이 설계한 책상의 청결도에 비례합니다."

🔗 관련 링크

 

반응형