CodeScout: Contextual Problem Statement Enhancement for Software Agents

이 논문은 코드베이스에 대한 경량화된 사전 탐색을 통해 불충분한 사용자 요청을 포괄적인 문제 진술로 변환하는 'CodeScout'을 제안함으로써, 소프트웨어 에이전트의 실패 패턴을 줄이고 SWEBench-Verified 벤치마크에서 해결률을 20% 향상시켰다고 요약할 수 있습니다.

핵심

코드 스카우트 (CodeScout): AI 프로그래머를 위한 '미리보기' 지도

이 논문은 **"AI 가 코딩 실수를 왜 자주 할까?"**라는 질문에서 시작합니다. 결론은 간단합니다. AI 가 바보가 아니라, 사람이 내린 지시 (문제 설명) 가 너무 막연해서 혼란을 겪는다는 것입니다.

이 문제를 해결하기 위해 제안된 **'코드 스카우트 (CodeScout)'**라는 시스템을 일상적인 비유로 설명해 드리겠습니다.

---

1. 문제 상황: "그냥 고쳐줘"라고만 한다면?

상상해 보세요. 당신이 아주 유명한 **건축 기사 (AI)**를 고용해서 집을 고쳐달라고 했습니다. 그런데 당신이 건네준 메모는 이렇습니다.

"거실 천장 좀 고쳐줘. 뭔가 이상해."

이때 건축 기사는 어떻게 될까요?

1. 혼란: 천장 어디가 이상한지, 왜 이상한지 모릅니다.
2. 헤매기: 천장 전체를 두드리고, 벽을 뚫고, 배관을 확인하며 시간을 낭비합니다.
3. 실패: 결국 "아무것도 고칠 게 없네"라고 말하거나, 엉뚱한 곳을 고쳐서 더 큰 문제를 만듭니다.

이것이 현재 AI 코딩 도구가 겪는 문제입니다. 개발자들이 "버그가 있어"라고만 말하면, AI 는 코드 전체를 뒤지며 헤매다가 (과도한 탐색) 같은 실수를 반복하다가 지쳐버립니다.

2. 해결책: 코드 스카우트 (CodeScout) 의 등장

이때 등장하는 코드 스카우트는 바로 **"현장 조사원"**입니다.

건축 기사 (AI) 가 일을 시작하기 전에, 스카우트가 먼저 현장에 가서 다음과 같은 일을 합니다.

1. 현장 답사: 천장이 왜 무너졌는지, 어떤 재료가 문제인지, 과거에 비슷한 수리가 어떻게 됐는지 코드를 미리 훑어봅니다.
2. 상세한 지도 작성: "거실 천장 3 번 보강재가 부러졌고, 2 층 배관과 연결되어 있으니 여기서 수리하세요"라고 정확한 위치와 방법을 적어줍니다.
3. 주의사항 전달: "여기서 망치로 치면 안 되고, 드라이버로 풀어야 합니다"라고 팁을 줍니다.

이제 건축 기사 (AI) 는 막연한 지시 대신, 정확한 지도를 받고 일을 시작합니다.

3. 코드 스카우트의 핵심 원리: "일단 보고, 그 다음에 행동하라"

논문에서는 이 과정을 3 단계로 나눕니다.

• 1 단계: 어디를 볼지 정하기 (Scoping)
  • "거실 천장"이라는 키워드만 보고, 관련 있는 파일과 함수를 10 개 정도 추려냅니다. (전체 집을 다 뒤지지 않음)
• 2 단계: 자세히 살펴보기 (Analysis)
  • 추려진 10 개 파일의 코드를 자세히 읽어보며, "아, 여기가 문제구나", "이 함수가 원인일 수도 있겠다"라고 분석합니다.
• 3 단계: 완벽한 지시서 만들기 (Synthesis)
  • 원래의 막연한 요청 ("천장 고쳐줘") 에 분석 결과를 합쳐서, AI 가 바로 실행할 수 있는 완벽한 지시서로 바꿉니다.
  • 예: "천장 고쳐줘" → "거실 천장의 3 번 보강재가 부러져서 배관과 연결된 2 층에 영향을 줬어. forms.py 파일의 260 번째 줄을 수정하고, widget 속성을 추가해. 테스트는 이렇게 해봐."

4. 왜 이렇게 하면 좋은가요? (결과)

이 방법을 적용한 결과, 놀라운 변화가 일어났습니다.

• 실패 감소: AI 가 엉뚱한 곳을 헤매는 시간이 줄어듭니다.
• 성공률 향상: 문제를 해결하는 비율이 20% 이상 늘어났습니다.
• 비용 절감: AI 가 더 적은 단계 (예: 21 단계 → 6 단계) 로 문제를 해결합니다.

비유하자면:

• 기존 방식: AI 가 어둠 속에서 손으로 더듬어 가며 21 번이나 실수를 반복하다가 결국 문제를 찾음.
• 코드 스카우트 방식: AI 가 밝은 전등 (정확한 지시서) 을 켜고 6 번 만에 정확하게 문제를 해결함.

5. 요약: 왜 이 연구가 중요한가?

이 논문은 **"AI 의 지능을 높이는 것보다, AI 가 받을 '지시'를 더 잘 만드는 것이 더 중요하다"**는 사실을 증명했습니다.

마치 **명장 (AI)**에게 **정밀한 설계도 (코드 스카우트)**를 주는 것이, 명장에게 "무언가 고쳐줘"라고 막연히 부탁하는 것보다 훨씬 효율적이라는 것입니다.

코드 스카우트는 AI 가 코딩할 때 헤매지 않도록, 미리 현장 조사해서 정확한 지도를 그려주는 똑똑한 조력자입니다. 덕분에 AI 는 더 빠르고 정확하게 소프트웨어를 개발할 수 있게 되었습니다.

기술 요약

1. 문제 정의 (Problem Statement)

현재 AI 기반 코드 보조 도구 (소프트웨어 에이전트) 는 종종 부족하게 정의된 문제 진술 (Underspecified Problem Statements) 로 인해 실패합니다. 개발자가 제출하는 버그 리포트나 요청은 종종 재현 단계, 기술적 세부 사항, 명확한 기대 행동이 누락된 채 간결하고 문맥에 의존적인 형태로 작성됩니다.

• 핵심 병목 현상: 에이전트의 실패는 모델의 추론 능력 부족 때문이 아니라, 입력된 문제 진술의 질이 낮기 때문입니다.
• 실패 패턴: 문맥이 부족한 요청은 에이전트가 다음과 같은 비효율적인 행동을 유발합니다.
  • 과도한 탐색 (Over-exploration): 문제의 근본 원인을 찾기 위해 불필요하게 긴 경로를 탐색하거나 문맥 과부하에 빠집니다.
  • 반복적 시도: 적절한 테스트나 진화 없이 동일한 수정 시도를 반복하는 '고집스러운' 에이전트 행동을 보입니다.
• 결과: 이러한 비수렴적 (non-converging) 행동은 해결률 저하와 계산 비용 증가로 이어집니다.

2. 방법론: CodeScout (Methodology)

저자들은 CodeScout을 제안합니다. 이는 에이전트 실행 전에 수행되는 경량화된 사전 탐색 (Lightweight Pre-exploration) 을 통해 사용자의 모호한 요청을 포괄적이고 실행 가능한 문제 진술로 변환하는 컨텍스트 기반 쿼리 정제 접근법입니다.

CodeScout 은 기존 에이전트 아키텍처를 수정하지 않고 플러그 - 앤 - 플레이 (Plug-and-Play) 방식으로 작동하며, 다음 3 단계 파이프라인으로 구성됩니다.

A. 저장소 지식 그래프 구축 (Repository Knowledge Graph Construction)

• 대상 코드베이스를 분석하여 AST(추상 구문 트리) 방문자를 사용하여 클래스, 함수, 임포트, 변수 선언 등을 추출합니다.
• 코드 엔티티 간의 의미론적 관계를 나타내는 방향성 그래프 $G(R)$을 구성합니다.

B. 고수준 컨텍스트 스코핑 (High-Level Scoping)

• 문제 진술 $P_0$와 저장소 그래프 $G(R)$을 기반으로 LLM 에이전트가 문제 해결에 가장 관련성이 높은 탐색 대상 (Exploration Targets) 을 식별합니다.
• 파일, 클래스, 함수 등 최대 15 개 이내의 타겟을 선정하며, 각 타겟이 왜 관련 있는지 이유를 포함합니다.

C. 세밀한 컨텍스트 분석 및 문제 종합 (Fine-grained Context Analysis & Problem Synthesis)

• 분석: 선정된 각 타겟의 소스 코드를 분석하여 역할 평가, 수정 위치 힌트, 기술적 통찰력, 대안 가설 등을 추출합니다.
• 필터링: 관련성 점수 (Relevance Score) 를 기준으로 노이즈가 포함된 컨텍스트를 필터링합니다.
• 종합 (Synthesis): 원본 문제 진술과 필터링된 통찰력을 결합하여 강화된 문제 진술 (Augmented Problem Statement) 을 생성합니다. 이는 다음 섹션을 포함합니다:
  • 향상된 이슈 설명 (Enhanced Issue Description)
  • 재현 단계 (Reproduction Steps) 및 기대 행동
  • 탐색 힌트 (Exploration Hints): 검토할 파일, 핵심 클래스/함수, 관심 영역
  • 수정 힌트 (Fix Hints): 높은 확률의 수정 위치 및 구현 제안

3. 주요 기여 (Key Contributions)

1. CodeScout 프레임워크: 저장소 인식 분석을 통해 입력 품질을 개선하는 체계적인 문제 명세 강화 접근법을 제시했습니다.
2. 실험적 검증: SWEBench-Verified 벤치마크에서 SWE-agent, OpenHands, Mini-SWE-Agent 등 다양한 에이전트 아키텍처와 LLM(GPT-5-mini, DeepSeek R1, Qwen3 Coder) 을 사용하여 CodeScout 의 효과를 입증했습니다.
3. 행동 분석 및 비용 효율성:
   • CodeScout 이 에이전트의 탐색 경로를 어떻게 변화시키는지 분석했습니다.
   • 약한 모델 + 강한 증강기: 비용 효율적인 약한 모델로 문제 진술을 증강하면, 더 큰 모델의 성능을 크게 향상시킬 수 있음을 보였습니다.
   • 강한 모델 + 약한 증강기: 강한 모델이 실행되더라도 약한 증강기를 사용해도 성능이 일정 수준 유지됨을 확인했습니다.

4. 실험 결과 (Results)

• 해결률 향상: SWEBench-Verified 벤치마크에서 CodeScout 을 적용한 결과, 기본 베이스라인 대비 20% 의 해결률 향상을 기록했습니다. 이는 최대 27 개의 추가 이슈가 해결됨을 의미합니다.
• 단계 수 감소: 문제 진술이 강화된 경우, 에이전트가 문제를 해결하는 데 걸리는 단계 수가 크게 감소했습니다. (예: Figure 1 의 사례에서 21 단계에서 6 단계로 단축).
• 로컬라이제이션 정확도: 생성된 패치가 정답과 동일한 파일이나 함수를 수정하는 정확도 (Localization Accuracy) 가 모든 모델에서 향상되었습니다. 특히 추론 능력이 부족한 모델 (DeepSeek R1 등) 에서 개선 폭이 컸습니다.
• 비용 효율성:
  • 증강 과정에 추가된 토큰 비용은 에이전트가 불필요한 탐색을 줄임으로써 얻는 전체적인 토큰 절감 효과보다 작거나 상쇄되는 경향이 있었습니다.
  • GPT-5-mini 와 같이 긴 경로를 생성하는 모델의 경우 증강 오버헤드가 상대적으로 작았습니다.

5. 의의 및 결론 (Significance & Conclusion)

• 패러다임 전환: 에이전트가 문제 해결에 바로 뛰어드는 것이 아니라, 먼저 코드를 '이해'하고 컨텍스트를 구축한 후 해결책을 모색해야 함을 강조합니다.
• 모델 용량 이상의 가치: 모델 자체의 용량 (Capacity) 을 늘리는 것뿐만 아니라, 문제 이해에 대한 사전 투자 (Upfront Problem Understanding) 가 AI 지원 소프트웨어 공학의 신뢰성을 높이는 강력한 보완책임을 입증했습니다.
• 범용성: 특정 에이전트 아키텍처에 종속되지 않고, 다양한 에이전트와 모델 조합에서 일관된 성능 향상을 제공하여 실제 산업 환경 적용 가능성을 시사합니다.

요약하자면, CodeScout은 "나쁜 입력은 좋은 출력을 만들 수 없다"는 원칙에 따라, AI 에이전트가 직면한 문맥 부족 문제를 사전에 해결함으로써 소프트웨어 개발 자동화의 효율성과 정확성을 획기적으로 개선한 연구입니다.