SHERLOC: Code Repair Agent를 위한 구조화된 Diagnostic Localization 프레임워크

TL;DR Highlight

버그 위치만 알려주는 게 아니라 '왜, 어떻게 고쳐야 하는지'까지 진단 리포트를 생성해서 코드 수정 에이전트의 성능을 높이는 training-free 프레임워크

Who Should Read

SWE-Bench 수준의 저장소 레벨 버그 수정 파이프라인을 구축하는 AI 엔지니어, 또는 LLM 기반 코드 에이전트에서 localization 비용과 정확도를 동시에 개선하고 싶은 개발자

Core Mechanics

기존 LLM 코드 수정 에이전트는 전체 인터랙션의 평균 48%(18.5턴, 320k 토큰)를 버그 위치 찾기에 소비하는데, SHERLOC은 이 localization 단계를 별도 모듈로 분리해서 효율화한다.
SHERLOC은 파인튜닝, 강화학습, 멀티에이전트 없이 단일 reasoning LLM + 4개 도구(파일 보기, 코드 검색, 저장소 트리, import 그래프)만으로 SWE-Bench Lite 84.33% accuracy@1, SWE-Bench Verified 81.27% recall@1을 달성했다.
버그 파일 경로만 반환하는 게 아니라 5개 필드(위치 설명, 근본 원인, 해결 아이디어, 의존성, 테스트 영향)로 구성된 structured diagnostic finding을 함께 출력해서 downstream 수정 에이전트에 주입한다.
Qwen3-235B 기준 약 30B 파라미터 모델인 Qwen3-30B도 SWE-Bench Verified에서 75.07% recall@1을 기록해서, 파인튜닝된 ToolTrain-32B(68.03%)보다 7pp 높고 non-finetuned 32B 베이스라인 대비 최대 18.3pp 앞선다.
SHERLOC findings를 SWE-Agent, OpenHands 두 수정 프레임워크에 주입하면 5개 모델 평균 +5.95pp resolve rate 향상과 localization 토큰 36.7%, 전체 토큰 23.1% 절감이 동시에 달성된다.
모델 능력에 따라 최적 개입 방식이 다름: 약한 모델(Qwen3-Coder-30B 등)은 모든 findings를 주입할 때 최대 +12pp 향상, 강한 모델(MiniMax-M2.5)은 GPT-5.2 judge 기반 quality filtering(≥4.0 점수)을 적용해야 오히려 성능이 올라간다.
Self-recovery 메커니즘(컨텍스트 잘라내기, 반복 도구 호출 감지, 잘못된 tool call 복구, final-turn 강제 합성)이 모두 성능에 기여하며, View File 도구 제거 시 -7pp F1, final-turn prompt 제거 시 -5pp F1 하락이 발생한다.

Evidence

SWE-Bench Lite에서 Qwen3-235B 기준 84.33% accuracy@1로, 이전 SOTA인 OrcaLoca(Claude 3.5 Sonnet, 83.33%)와 SWERank(파인튜닝된 Qwen2.5-32B, 83.21%)를 모두 능가했다.
SWE-Bench Verified에서 81.27% recall@1로 이전 SOTA RepoSearcher/ToolTrain-32B-FT(68.03%) 대비 13.2pp 향상, 30B 모델(Qwen3-30B)도 75.07%로 동급 파인튜닝 베이스라인 대비 +7pp.
5개 repair 모델 × 2개 프레임워크 10개 조합 모두에서 resolve rate가 올랐으며 평균 +5.95pp, 가장 큰 폭은 Qwen3-Next-80B/OpenHands에서 38.6% → 50.4%로 +11.8pp.
GPT-5.2 judge 품질 점수와 실제 버그 수정 성공 간 Pearson r=0.45(p<0.001), Very High 품질(>4.0) findings는 75.9% resolve, Low 품질(≤2.0)은 20.0% resolve로 55pp 이상 차이났다.

How to Apply

자체 코드 수정 에이전트 파이프라인에 SHERLOC을 localization 전처리 단계로 붙이고, 출력된 5필드 diagnostic finding을 repair 에이전트 프롬프트 앞에 주입하면 된다. 에이전트 모델이 약할수록(hit@1이 SHERLOC의 0.88보다 낮을수록) 효과가 크다.
강한 repair 모델(이미 hit@1이 높은 경우)을 사용 중이라면 모든 findings를 주입하면 오히려 역효과가 날 수 있으니, LLM-as-judge로 finding 품질을 1~5점으로 채점하고 4.0 이상인 경우에만 주입하는 quality filter를 추가해야 한다.
비용 절감이 목표라면 accuracy 향상 없이도 SHERLOC만으로 localization 토큰을 9~66% 줄일 수 있다. Qwen3-Coder-480B/SWE-Agent 조합 기준 localization 토큰이 188.9k → 64.6k(-66%)로 줄면서 resolve rate는 동일하게 유지됐다.

Code Example

snippet

# SHERLOC의 핵심 프롬프트 구조 및 tool call 패턴

SYSTEM_PROMPT = """
You are a bug-localization assistant.
Primary Goal: Locate every file and precise line-number range that must be edited.
Never propose code changes. Return locations only after inspecting enough source code.

Interaction protocol:
(1) Read the Problem Description.
(2) First response must be a tool call, never locations.
(3) Keep issuing tool calls until fully confident.
(4) Only then reply with a <locations> block.

Available tools:
- view_file(path, view_range=[start, end]): 파일 내용 확인
- codebase_search(query): 저장소 전체 리터럴 검색
- repo_tree(): 저장소 파일 구조 확인
- connected_tree(file=None): import 의존성 확인
"""

# 최종 출력 포맷 (findings + locations)
FINAL_OUTPUT_FORMAT = """
<findings>
- Location explanation: [왜 이 위치가 수정되어야 하는지]
- Root cause: [버그의 근본 원인]
- Solution idea: [코드 없이 수정 방향 설명]
- Dependencies: [관련 모듈/파일 의존성]
- Testing impact: [테스트 수정 필요 사항]
</findings>

<locations>
- file: django/db/models/base.py, start: 1750, end: 1751
</locations>
"""

# Quality judge 프롬프트 (findings 품질 평가)
JUDGE_PROMPT = """
You are evaluating the quality of a bug localization analysis.

## Issue Description
{problem_statement}

## Ground Truth Patch
{gt_patch}

## Finding to Evaluate
{finding}

## Predicted Locations
{locations}

Rate on 1-5 scale:
1. Root Cause Correctness
2. Location Accuracy  
3. Solution Actionability

Respond in JSON:
{"root_cause": <1-5>, "location_accuracy": <1-5>, "solution_actionability": <1-5>, "reasoning": "<brief>"}
"""

# quality filter 적용 (threshold >= 4.0이면 findings 주입, 아니면 baseline)
def apply_sherloc_findings(finding, judge_score, threshold=4.0):
    composite = (judge_score['root_cause'] + 
                 judge_score['location_accuracy'] + 
                 judge_score['solution_actionability']) / 3
    if composite >= threshold:
        return f"Use these diagnostic findings:\n{finding}"
    else:
        return ""  # fallback to agent's own search

Terminology

SWE-BenchGitHub에 올라온 실제 버그 리포트와 수정 PR로 만든 벤치마크. LLM이 실제 오픈소스 저장소 버그를 자동으로 고칠 수 있는지 테스트하는 시험지.

accuracy@1 / recall@1상위 1개 예측 결과가 정답과 맞을 확률. '첫 번째 추측이 맞을 확률'로 이해하면 쉽다.

fault localization코드에서 버그가 있는 파일/함수/라인을 찾아내는 과정. 수리 전에 '어디가 고장났는지' 진단하는 단계.

resolve rate에이전트가 생성한 패치가 실제 테스트를 통과하는 비율. '버그를 제대로 고친 비율'.

LLM-as-judge다른 LLM의 출력 품질을 평가하는 데 LLM을 심판으로 사용하는 방법. 사람 대신 AI가 채점하는 것.

training-free별도의 파인튜닝이나 강화학습 없이 기존 모델을 그대로 사용하는 방식. 추가 학습 비용 없이 바로 쓸 수 있다는 의미.

quality filteringLLM이 생성한 결과물을 품질 기준으로 걸러내는 과정. 낮은 품질의 결과는 사용하지 않고 fallback으로 대체하는 안전장치.

structured diagnostic finding버그 위치뿐 아니라 근본 원인, 해결 방향 등 5가지 필드를 포함한 구조화된 진단 리포트. 단순 파일 경로가 아닌 '의사 진단서' 같은 것.

Related Resources

Original Abstract (Expand)

LLM agents solve repository-level coding tasks through multi-turn tool use, but utilize half their budget on locating faults before editing. Dedicated localization frameworks have emerged, yet are still evaluated as file retrieval rather than actionable diagnosis, producing locations without the diagnostic context a repair agent needs. We introduce SHERLOC (Structured Hypothesis-driven Exploration and Reasoning for Localization), a training-free framework pairing a reasoning LLM with compact repository tools and self-recovery, without fine-tuning or multi-agent orchestration. SHERLOC reaches state-of-the-art localization across model scales: 84.33% accuracy@1 on SWE-Bench Lite and 81.27% recall@1 on SWE-Bench Verified; at ~30B parameters, it matches or outperforms other agentic methods. Injecting our locations and diagnostic findings into repair agents yields, on average, +5.95 pp resolve rate on SWE-Bench Verified while cutting localization and total tokens by 36.7% and 23.1%.