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

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 search

Terminology

관련 논문

• ctx – 로컬 머신의 코딩 에이전트 히스토리를 검색하는 CLI 도구

  Claude Code, Cursor, Codex 등 코딩 에이전트가 이전 세션의 논의·결정·실패 시도를 잊지 않도록 SQLite로 인덱싱해 재사용할 수 있게 해주는 오픈소스 CLI 도구다.

• Micro-Agent: Model API 내부 협업으로 Frontier 모델을 이기는 방법 (vLLM Semantic Router)

  vLLM 팀이 단일 모델 API 호출 뒤에서 여러 모델이 협업하는 'Micro-Agent' 개념을 공개했습니다. 별도의 에이전트 코드 없이 라우터 레이어에서 모델 조합을 실행해 GPT-4급 결과를 더 저렴하게 낼 수 있다는 아이디어입니다.

• Ornith-1.0: 에이전틱 코딩을 위한 자기 개선형 오픈소스 모델

  Gemma 4와 Qwen 3.5를 기반으로 파인튜닝한 코딩 특화 오픈소스 모델로, RL(강화학습)을 통해 스캐폴드(에이전트 실행 구조)까지 함께 최적화하는 방식을 주장하지만, 커뮤니티에서는 벤치마크 과최적화에 불과하다는 의심을 받고 있다.

• Tool-Augmented Agent에서의 Entity Binding 실패 분석

  AI 에이전트가 올바른 도구를 선택해도 잘못된 대상에 실행하는 'Entity Binding 실패' 문제를 정의하고, 이를 막는 실행 정책을 평가한 논문.

• Herdr: 터미널에서 여러 AI Agent를 한 번에 관리하는 Agent Multiplexer

  여러 AI 코딩 에이전트(Claude, Codex 등)를 하나의 터미널에서 동시에 실행·관리할 수 있는 Rust 기반 오픈소스 툴로, tmux처럼 세션이 유지되고 SSH로 원격 접속도 가능해 멀티 에이전트 워크플로우를 크게 단순화해준다.

• Ornith-1.0: 스스로 Scaffold를 생성하는 Agentic Coding LLM

  모델이 문제 풀이 전략(scaffold)을 직접 생성하고 개선하는 자기강화 학습 프레임워크를 적용한 오픈소스 코딩 특화 LLM으로, 9B 소형 모델부터 397B 대형 모델까지 라인업을 갖추고 SWE-Bench 등 주요 벤치마크에서 Claude Opus 4.7을 능가하는 성능을 보여줬다.

Related Resources

• SWE-Bench 공식 벤치마크
• SWE-Agent 논문
• OpenHands 플랫폼
• Agentless 논문
• SWE-Gym 데이터셋
• Qwen3 기술 보고서
• DeepSeek-V3 기술 보고서
• SGLang 추론 엔진