SHERLOC: Structured Diagnostic Localization for Code Repair Agents
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
# 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 searchTerminology
Related Papers
RubyLLM: A Ruby framework for all major AI providers
OpenAI, Claude, Gemini 등 주요 AI 프로바이더를 단일 인터페이스로 통합한 Ruby 프레임워크로, Rails 통합과 에이전트 기능까지 지원해 Ruby 개발자가 AI 기능을 빠르게 붙일 수 있다.
Qwen-AgentWorld: Language World Models for General Agents
Alibaba Qwen 팀이 AI 에이전트가 행동 결과를 미리 시뮬레이션할 수 있는 'Language World Model'을 공개했다. 에이전트 훈련과 실행 경로 검증에 새로운 패러다임을 제시하는 연구다.
Show HN: peerd – AI agent harness that runs entirely in your browser
백엔드 서버 없이 Chrome/Firefox 확장 프로그램으로만 동작하는 AI 에이전트 실행 환경으로, 브라우저 탭을 직접 조작하고 WASM Linux VM까지 구동할 수 있어 프라이버시와 보안을 동시에 챙길 수 있다.
SAFARI: Scaling Long Horizon Agentic Fault Attribution via Active Investigation
수백만 토큰 넘는 에이전트 실행 로그에서 버그 발생 지점을 찾아내는 도구 기반 진단 프레임워크
Self-Compacting Language Model Agents
LLM 에이전트가 스스로 '지금 요약해도 되는지'를 판단하는 rubric을 추가하면, 파인튜닝 없이도 고정 주기 요약보다 정확도는 높고 비용은 30~70% 낮아진다.
Show HN: Oak – Git alternative designed for agents
AI 에이전트가 코드 작업을 더 효율적으로 수행할 수 있도록 설계된 새로운 버전 관리 시스템(VCS)으로, lazy mount, JSON-first CLI, 멀티 레포 에이전트 워크스페이스 등을 제공한다. 다만 커뮤니티에서는 Git 대비 실질적 우위가 충분히 증명되지 않았다는 회의적 반응이 많다.
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%.