iterative-retrieval

iterative-retrieval 개요

iterative-retrieval 스킬은 에이전트 작업에서 흔히 말하는 “컨텍스트 문제”를 풀기 위한 워크플로 패턴입니다. 서브에이전트가 처음에는 알아야 할 정보를 충분히 갖지 못한 상태로 시작하지만, 점차 필요한 파일, 용어, 패턴을 좁혀 가며 정답에 접근하는 방식입니다. 특히 워크플로 디자이너, 코드베이스 탐색자, 그리고 1차 검색만으로는 보통 정보가 부족한 iterative-retrieval for Workflow Automation을 구축하는 사람에게 적합합니다.

사용자가 실제로 궁금해하는 건 이론보다도, 이 스킬이 에이전트가 흔한 두 가지 실패를 피하도록 돕는지입니다. 즉, 너무 많은 컨텍스트를 보내 예산을 소진하는 경우와, 너무 적은 컨텍스트를 보내다 작업이 멈추는 경우입니다. iterative-retrieval의 핵심 가치는 발견 과정을 한 번의 추측이 아니라 반복 루프로 바꿔 준다는 데 있습니다.

iterative-retrieval이 해결하는 문제

이 스킬은 사전에 알 수 없는 코드베이스 전용 컨텍스트가 필요한 작업에 사용합니다. 예를 들면 구현 패턴을 찾거나, 관련 파일을 식별하거나, 첫 검색 이후 검색어를 더 정교하게 다듬는 경우입니다. 특히 에이전트가 사람의 직접적인 안내 없이 큰 repo를 해석해야 할 때 유용합니다.

iterative-retrieval이 다른 점

“둘러보고 판단해라”라는 일반적인 프롬프트와 달리, iterative-retrieval은 구체적인 검색 루프를 제공합니다. 디스패치하고, 평가하고, 다듬고, 반복하는 흐름입니다. 덕분에 서브에이전트를 오케스트레이션하기가 쉬워집니다. 특히 넓고 잡음 많은 덤프보다 예측 가능한 컨텍스트 증가가 필요한 프로세스라면 더 그렇습니다.

가장 잘 맞는 사용 사례

이 스킬은 아키텍처 탐색, RAG 스타일의 코드 탐색, 그리고 첫 검색이 의도적으로 불완전한 멀티에이전트 워크플로에 잘 맞습니다. 반대로 답이 이미 로컬에 있거나, repo가 매우 작거나, 정확한 파일 목록을 미리 제공할 수 있다면 효용이 떨어집니다.

iterative-retrieval 스킬 사용 방법

설치하고 활성화하기

스킬 매니저에서 제공하는 설치 경로를 사용한 뒤, 에이전트 워크플로를 skills/iterative-retrieval/SKILL.md로 연결하세요. 이 repo에서 일반적인 iterative-retrieval 설치 패턴은 다음과 같습니다:

npx skills add affaan-m/everything-claude-code --skill iterative-retrieval

가장 좋은 결과를 내려면, 이미 관련 파일을 직접 다 골라 놓은 뒤가 아니라 컨텍스트를 찾아야 하는 작업일 때 호출하세요.

막연한 목표를 쓸 수 있는 프롬프트로 바꾸기

이 스킬은 프롬프트에 목표, 범위, 종료 기준이 함께 들어 있을 때 가장 잘 작동합니다. 좋은 입력 예시는 다음과 같습니다:

• 목표: “인증 흐름을 찾아서 토큰 갱신이 어디서 처리되는지 설명해줘.”
• 범위: “테스트는 제외하고 프로덕션 코드만 검색해줘.”
• 제약: “각 검색 패스는 몇 개 파일 이내로 유지해줘.”
• 성공 조건: “확신을 갖고 답할 수 있는 최소 파일 집합을 반환해줘.”

iterative-retrieval usage는 모델에게 한 번의 모호한 요청으로 repo 전체를 추론하게 만드는 일이 아니라, 컨텍스트를 점점 정교하게 만드는 과정이라는 점이 중요합니다.

먼저 읽어야 할 파일

먼저 SKILL.md를 읽고, 그다음 repo가 제공하는 지원 문서를 확인하세요. 이 repo에서는 실무상 진입점이 여전히 SKILL.md입니다. 설치 과정에서 스킬 본문만 복사된다면 그것이 기준 소스입니다. 그다음에는, 환경에 존재한다면 주변의 워크플로 문서도 검토해서 루프를 자신의 오케스트레이션 규칙에 맞추세요.

검색 루프를 실제로 돌리기

좋은 워크플로는 이렇습니다. 좁은 범위로 검색을 보내고, 반환된 컨텍스트가 충분한지 평가한 다음, 부족했던 부분을 바탕으로 다음 검색을 더 구체화하고, 에이전트가 행동할 만큼 증거가 쌓일 때까지 반복합니다. 핵심은 매 패스에서 새로 발견한 용어를 다음 검색에 반영하는 것이지, 같은 질의를 말만 바꿔 반복하는 것이 아닙니다.

iterative-retrieval 스킬 FAQ

iterative-retrieval은 큰 코드베이스에서만 쓰나요?

아닙니다. 규모도 중요하지만, 진짜 기준은 불확실성입니다. 읽기 전에 어떤 파일이 중요할지 에이전트가 예측할 수 없다면, 중간 규모 repo에서도 iterative-retrieval이 도움이 됩니다.

언제는 쓰지 말아야 하나요?

작업 범위가 이미 명확하고, 관련 파일이 알려져 있으며, 고정 입력만으로 처리할 수 있다면 iterative-retrieval을 쓰지 마세요. 그런 경우에는 루프가 답변 품질을 높이지 못한 채 오버헤드만 늘립니다.

일반 프롬프트보다 더 나은가요?

발견 작업에서는 그렇습니다. 일반 프롬프트는 모델이 처음부터 올바른 컨텍스트를 맞힐 수 있다고 가정하는 경우가 많습니다. iterative-retrieval 가이드는 부분 결과를 읽은 뒤 프롬프트가 적응해야 하고, 최종 답변이 그 적응에 달려 있을 때 더 적합합니다.

초보자도 쓰기 쉬운가요?

네, 루프를 문자 그대로 따르면 그렇습니다. 가장 큰 학습 난도는 문법이 아니라, 첫 검색을 얼마나 작게 시작해야 유용하면서도 충분히 넓게 잡아 적절한 용어를 드러낼 수 있는지 판단하는 데 있습니다.

iterative-retrieval 스킬 개선 방법

첫 패스의 목표를 더 날카롭게 잡기

품질 향상의 가장 큰 요인은 초기 프레이밍입니다. “관련 코드를 찾아줘” 대신, 구체적인 동작, 하위 시스템, 의사결정 지점을 요구하세요. 이미 아는 것, 추정하는 것, 유용한 단서가 무엇인지도 함께 넣으세요. 그러면 iterative-retrieval usage가 훨씬 효율적입니다.

흔한 실패 모드를 점검하기

가장 흔한 실패는 과도한 검색입니다. 에이전트가 너무 많은 파일을 가져와 놓고 결과에서 학습하지 못한 채 멈추는 경우입니다. 반대 실패는 검색 부족입니다. 다음 검색어를 찾을 만큼 컨텍스트가 모자라는 상태입니다. 첫 패스에서 너무 일반적인 파일만 나온다면, 검색 범위를 넓히기보다 용어, 호출 지점, 진입점을 요청하며 정교하게 좁히세요.

추측이 아니라 증거로 반복하기

첫 출력 이후에는 파일명, 함수명, 오류 메시지, 낯선 용어처럼 가장 정보가 많은 항목만 되돌려 주세요. 새로운 증거 없이 “다시 봐줘”라고만 요청하지 마세요. iterative-retrieval for Workflow Automation에서 가장 큰 개선은 이 증거 루프를 오케스트레이션에 내장해서, 매 패스마다 검색 공간이 실제로 바뀌도록 만드는 것입니다.

저장소 규칙에 맞춰 적용하기

환경에 네이밍 규칙, 폴더 경계, 에이전트 인계 규칙이 있다면 첫 검색 전에 프롬프트에 미리 반영하세요. 이 스킬은 모든 코드베이스를 일반적인 검색 문제로 취급하지 않고, 저장소의 실제 구조를 존중할 때 가장 강력합니다.