먼저 문제가 지시 손실인지, 검색 과부하인지, 잘못된 기억의 누적인지 구분해야 합니다. Agent Skills for Context Engineering은 이를 자동으로 해결하는 라이브러리가 아니라, 실패 유형에 맞는 정보 관리 절차를 고를 수 있게 마크다운 지침을 주제별로 모은 저장소입니다.
저장소는 긴 대화에서 중요한 지시가 중간에 묻히거나 잘못된 정보가 계속 남는 문제를 “프롬프트 한 줄”이 아닌 정보 관리 문제로 봅니다. 컨텍스트가 커져도 모델의 주의력과 호출 비용은 유한하므로, 무엇을 넣고 언제 빼고 어디에 보관할지를 설계해야 한다는 관점입니다.
프롬프트 엔지니어링이 현재 요청을 어떻게 표현할지에 초점을 둔다면, 컨텍스트 엔지니어링은 모델이 답할 때 보게 되는 전체 재료를 다룹니다. 시스템 지침, 도구 정의, 검색 문서, 대화 기록이 모두 대상입니다.
예를 들어 긴 작업에서 검색 로그를 계속 쌓으면 정답 근거보다 실패 기록이 더 많은 공간을 차지할 수 있습니다. 이때 필요한 것은 “더 집중해”라는 문장이 아니라 로그를 요약하고, 결정 사항은 남기고, 필요할 때 원문을 다시 여는 흐름입니다.
저장소가 강조하는 progressive disclosure도 같은 원리입니다. 처음에는 스킬 이름과 설명만 보여 주고, 현재 작업에 필요한 상세 파일만 읽게 해 토큰과 주의력 사용을 줄입니다.
프롬프트를 고치는 일은 여전히 필요하지만, 문제가 정보 배치에 있다면 문장 표현만 바꿔도 효과가 제한됩니다. 시스템 지침이 대화 초반에만 있고 수십 개 도구 출력 뒤에 묻혔다면 핵심 제약을 다시 가까운 위치에 제공하거나 불필요한 출력을 제거해야 합니다. 반대로 필요한 원문이 검색되지 않았다면 요약을 더 잘하는 것보다 retrieval 후보와 근거 연결을 고쳐야 합니다.
컨텍스트를 늘리는 것도 기본 해법이 아닙니다. 더 긴 창은 더 많은 자료를 넣을 수 있게 하지만 오래된 오류, 중복 로그와 서로 충돌하는 지시까지 함께 보존합니다. 모델이 볼 수 있는 양과 실제로 중요한 항목을 안정적으로 사용하는 능력을 분리해 평가해야 합니다.
먼저 실패가 발생한 작업의 입력 흐름을 다시 구성합니다. 시작할 때 분명했던 제약이 마지막 답에서 빠졌다면 지시 손실, 정답 문서가 저장소에 있지만 후보에 없었다면 검색 문제, 이미 고친 사실이 다음 세션에서 다시 나타났다면 기억 오염으로 분류할 수 있습니다. 한 사례에 여러 원인이 겹칠 수 있으므로 모델의 최종 답만 보고 이름을 붙이지 않습니다.
지시 손실은 핵심 제약을 중간과 끝에서 직접 물어 재현할 수 있습니다. 검색 과부하는 후보 문서 수를 줄이거나 정답 근거를 직접 제공했을 때 결과가 회복되는지 봅니다. 기억 오염은 새 세션과 기존 세션을 비교하고 저장된 요약, 메모리 파일을 열어 잘못된 정보가 어느 단계에서 들어갔는지 확인합니다.
진단 결과를 수치로 남기면 스킬 적용 우선순위가 선명해집니다. 제약 누락 건수, 정답 근거가 상위 후보에 든 비율, 오래된 기억을 사용한 답변 수를 별도로 기록합니다. 모든 실패를 “컨텍스트 품질”이라는 하나의 점수로 합치면 적용한 절차가 어떤 문제를 고쳤는지 알기 어렵습니다.
저장소의 문서는 목적에 따라 세 묶음으로 볼 수 있습니다.
context-fundamentals, context-degradation, context-compression은 중간 내용 소실과 오염, 요약 문제를 다룹니다.multi-agent-patterns, memory-systems, tool-design은 여러 에이전트와 장기 기억, 도구 스키마 설계를 다룹니다.context-optimization, evaluation은 토큰 사용과 LLM-as-a-Judge를 포함한 평가 기준을 정리합니다.모두 한꺼번에 넣는 것은 저장소의 취지와 어긋납니다. 지시 망각이 문제라면 degradation과 compression부터, 여러 작업자가 같은 정보를 중복해서 읽는다면 multi-agent pattern부터 보는 식으로 실패 유형에 맞춰 선택하는 편이 낫습니다.
스킬 설명을 선택 규칙으로 쓰고 전체 문서는 실제 문제가 생겼을 때만 불러오는 것이 progressive disclosure의 출발점입니다. 스킬 파일 자체가 길다면 그 내용을 매 요청에 고정으로 넣는 순간 새로운 컨텍스트 과부하가 됩니다. 작업 시작 시 필요한 이름과 역할만 보여 주고, 선택된 스킬의 세부 절차와 관련 원문을 순서대로 여는 구조가 맞는지 확인합니다.
두 스킬이 모두 필요해 보여도 한 번에 적용하면 효과를 분리하기 어렵습니다. 예를 들어 압축 규칙을 바꾸고 동시에 멀티 에이전트 역할도 나누면 토큰 감소가 요약 때문인지 역할 분담 때문인지 알 수 없습니다. 기준 작업을 정하고 가장 큰 실패 원인 하나부터 바꾼 뒤, 개선과 새 오류를 측정해 다음 스킬로 넘어갑니다.
좋은 압축은 단순히 글자 수가 짧은 요약이 아니라 다음 행동에 필요한 상태를 보존합니다. 사용자가 확정한 요구사항, 완료된 단계, 아직 해결되지 않은 오류, 근거 파일과 다시 열 경로를 구분해 남깁니다. 탐색 과정의 모든 실패 로그는 줄일 수 있지만 실패가 알려 준 제약이나 재시도 금지 조건은 결과 상태에 포함해야 합니다.
요약에는 관찰된 사실과 모델의 추측을 같은 문장으로 섞지 않는 편이 좋습니다. “테스트가 실패했다”는 사실과 “데이터베이스 연결 때문일 수 있다”는 가설을 나누면 다음 작업자가 추측을 확정 사실로 기억하는 문제를 줄일 수 있습니다. 수치, 코드, 인용처럼 정확성이 중요한 항목은 압축본에 재작성하기보다 원문 위치를 연결하고 필요할 때 다시 읽게 합니다.
압축 품질은 요약문을 사람이 읽고 자연스럽다고 평가하는 것만으로 부족합니다. 압축 전후에 같은 후속 작업을 수행해 제약 준수, 결정 재질문, 원문 재검색 횟수와 잘못 이어 간 단계가 변했는지 봅니다. 토큰은 줄었지만 중요한 예외를 잃어 재작업이 늘었다면 총비용은 오히려 커진 것입니다.
이 프로젝트는 Python 패키지가 아니므로 설치만으로 에이전트의 기억이 바뀌지 않습니다. Claude Code, Cursor, LangChain, AutoGen처럼 커스텀 지침이나 문서 참조를 지원하는 환경에서 필요한 스킬 파일을 읽도록 연결해야 합니다.
적용 전후에는 같은 장기 과제를 반복해 다음을 비교할 수 있습니다.
문서를 읽었다는 사실과 행동이 개선됐다는 사실은 다릅니다. 평가 스킬도 모델이 스스로 채점했다고 끝내지 말고, 사람이 확인할 기준과 실패 사례를 함께 남겨야 합니다.
평가 과제는 짧은 정답 문제보다 실제로 문제가 생기던 길이와 도구 수를 유지해야 합니다. 작업마다 정보 순서만 조금 바꾸고 고정된 제약을 끝까지 지키는지 시험하면 특정 문구 암기를 줄일 수 있습니다. 모델, 온도, 도구 권한이 바뀌면 컨텍스트 절차 외의 효과가 섞이므로 비교 조건을 기록합니다.
평균 결과와 함께 가장 나쁜 사례도 봐야 합니다. 열 번 중 아홉 번은 비용이 줄었지만 한 번 중요한 삭제 금지 지침을 잃었다면 고위험 업무에 적용하기 어렵습니다. 실패를 자동 복구할 수 있는지, 사람이 어느 시점에 개입할 수 있는지도 평가 항목에 넣습니다.
장기 기억에는 반복해서 필요한 안정된 선호와 결정만 남기고, 일회성 추측과 만료되는 상태는 수명을 제한하는 편이 좋습니다. “이번 테스트 서버가 느리다”는 관찰이 영구 사실로 남으면 다음 달에도 잘못된 판단을 유도할 수 있습니다. 기억마다 출처, 생성 시점, 적용 범위와 수정 주체를 연결해야 고칠 수 있습니다.
사용자가 기억을 정정했을 때 검색 색인과 요약 캐시도 함께 갱신되는지 확인합니다. 화면의 메모리 파일만 바뀌고 검색 결과가 이전 표현을 반환하면 오류가 계속됩니다. 삭제 시험은 원문 기억, 파생 요약, 임베딩과 백업에서 같은 정보가 다시 나오지 않는지까지 포함합니다.
컨텍스트 압축은 정보를 공짜로 줄이지 않습니다. 요약 과정에서 예외 조건이나 수치가 사라질 수 있고, 잘못된 요약이 장기 기억에 들어가면 이후 대화 전체를 오염시킬 수 있습니다. 멀티 에이전트 구조도 역할이 겹치면 토큰과 조정 비용만 늘어납니다.
따라서 중요한 원문에는 다시 접근할 경로를 남기고, 결정과 추측을 분리하며, 압축본에 출처를 연결해야 합니다. 특정 플랫폼의 스킬 형식과 호환성도 저장소의 README에서 확인해야 합니다.
이 저장소의 가장 실용적인 용도는 에이전트에게 “기억력이 좋아지는 파일”을 장착하는 것이 아닙니다. 현재 시스템이 지시 손실, 검색 과부하, 메모리 오염 중 어디에서 실패하는지 이름을 붙이고, 그 문제에 맞는 정보 흐름을 작게 시험하는 체크리스트로 쓰는 것입니다.
적용을 끝내는 기준도 정해야 합니다. 새 스킬이 제약 누락을 줄였지만 토큰과 지연이 크게 늘었다면 모든 작업에 상시 적용하기보다 긴 과제에서만 불러올 수 있습니다. 효과가 없거나 새 실패가 늘면 추가 지침을 덧붙이기 전에 변경을 되돌리고 원래 진단이 맞았는지 다시 확인합니다.
결국 컨텍스트 엔지니어링은 문서 수집이 아니라 정보 수명 주기를 설계하는 일입니다. 현재 요청에 필요한 재료, 세션 동안 유지할 결정, 장기 보관할 기억, 필요할 때 다시 열 원문을 분리할 수 있을 때 이 저장소의 스킬이 실제 절차로 이어집니다.
←→ 키와 좌우 스와이프를 지원합니다. 읽던 페이지는 이 기기에 저장됩니다.