Context Matters: Evaluating Context Strategies for Automated ADR Generation Using LLMs

1. 연구 배경 및 문제 정의 (Problem)

• 배경: 소프트웨어 아키텍처는 지속적인 의사결정의 흐름이며, 이를 문서화하기 위해 아키텍처 의사결정 기록 (ADR, Architecture Decision Records) 이 표준으로 자리 잡았습니다. ADR 은 설계의 '왜 (Why)'를 기록하여 팀 온보딩, 지식 유지, 추적성 확보에 필수적입니다.
• 문제점:
  • 작성 부담: ADR 작성은 즉각적인 비용이 발생하지만 혜택은 미래 유지보수자에게 돌아가는 '인센티브 불일치'로 인해 실제 도입률이 낮고, 많은 프로젝트가 초기 기록 후 중단합니다.
  • LLM 의 한계: 최근 대규모 언어 모델 (LLM) 이 ADR 자동 생성에 유망한 도구로 부상했으나, 기존 연구들은 대부분 단일 결정을 즉각적인 코드 변경이나 좁은 컨텍스트만으로 생성하는 데 초점을 맞추었습니다.
  • 핵심 가설: 소프트웨어 아키텍처는 경로 의존성 (Path Dependency) 을 가집니다. 즉, 현재의 결정은 이전의 결정, 기술 스택, 트레이드오프의 역사에 의해 제약받습니다. 따라서 LLM 이 양질의 ADR 을 생성하려면 어떻게 과거의 ADR 히스토리를 컨텍스트로 제공하는지 (Context Engineering) 가 모델의 규모보다 더 중요할 수 있습니다.

2. 연구 방법론 (Methodology)

이 연구는 LLM 이 생성한 ADR 의 품질에 영향을 미치는 다양한 컨텍스트 제공 전략을 체계적으로 평가하는 실증 연구입니다.

• 데이터셋 구축:
  • 기존 MSR(Mining Software Repositories) 연구 (Buchgeher et al.) 의 데이터를 기반으로 750 개의 오픈소스 저장소에서 4,500 개 이상의 ADR 을 수집했습니다.
  • 중요: 단순 수집을 넘어, 저장소 구조 감사, 시간적 연속성 검증, 메타데이터 인덱싱을 통해 시계열 순서가 올바르게 정렬된 검증된 ADR 코퍼스를 구축했습니다.
• 실험 대상 모델:
  • 다양한 크기와 아키텍처를 가진 4 가지 LLM 선택:
    1. Gemini-2.5-Pro: 폐쇄형 SOTA 모델.
    2. Qwen3-235B: 최상위 오픈소스 모델.
    3. GLM-4.6: 그래프 기반 아키텍처를 도입한 모델.
    4. Gemma-3-4B: 경량 로컬 실행 모델.
• 컨텍스트 전략 (5 가지):
  1. Baseline (No Context): 이전 ADR 없이 제목만 제공.
  2. All_N: 프로젝트의 모든 이전 ADR 히스토리 포함.
  3. First_K: 프로젝트 초기의 K 개 (기초 설계 결정) ADR 만 포함.
  4. Last_K: 직전 K 개 (최근) ADR 만 포함.
  5. RAFG (Retrieval-Augmented Few-shot Generation): 질문 (새 ADR 제목) 과 유사한 K 개의 ADR 을 의미적 유사도 (Semantic Similarity) 로 검색하여 동적으로 포함.
• 평가 지표:
  • 자동화된 메트릭: BERTScore (의미적 유사성), BLEU, ROUGE, METEOR (표면적/구조적 일치도).
  • 인간 평가: 생성된 ADR 의 내용과 포맷에 대한 정성적 검토.

3. 주요 기여 (Key Contributions)

1. 시계열 정렬된 대규모 ADR 코퍼스 공개: 실제 아키텍처 진화를 시뮬레이션할 수 있는 검증된 '다음 단계 (Next-step)' 생성 실험용 데이터셋 구축.
2. 컨텍스트 전략의 정량적 비교: ADR 생성 품질에 미치는 의사결정 역사의 영향을 체계적으로 분석하고, 4 가지 전략 (All_N, First_K, Last_K, RAFG) 의 성능을 비교.
3. 실용적 가이드라인 제시: 모델 규모보다 컨텍스트 엔지니어링이 자동화 성공의 핵심 요소임을 입증하고, 도구 개발자를 위한 최적의 기본 설정 (Default) 을 제안.

4. 실험 결과 (Results)

• RQ1: 의사결정 역사의 영향
  • 컨텍스트가 없는 Baseline 은 성능이 가장 낮았으며, 과도하게 장황한 (Verbose) 텍스트를 생성했습니다.
  • 역사적 컨텍스트를 포함하면 생성 품질이 크게 향상되었고, 인간이 작성한 ADR 과 유사한 간결함과 논리를 갖추게 되었습니다.
• RQ2: 완전한 히스토리 vs 전략적 부분집합
  • Last_K (최근 3~5 개) 전략이 All_N (전체 히스토리) 과 거의 동등한 성능을 보였습니다.
  • 전체 히스토리를 포함하는 것은 토큰 비용 증가와 노이즈만 초래할 뿐, 품질 향상에는 미미한 효과만 있었습니다.
  • First_K (초기 K 개) 는 최근 결정에 비해 성능이 낮았으며, 초기 설계 결정이 현재 생성 작업에 직접적인 관련성이 적음을 시사합니다.
  • 결론: 전체 아키텍처 히스토리가 필요하지 않으며, 최근 3~5 개의 기록이 최적의 균형 (품질 vs 효율) 을 제공합니다.
• RQ3: 시간적 순서 vs 의미적 검색 (RAFG)
  • RAFG는 Last_K와 전체적으로 유사한 성능을 보였습니다.
  • 그러나 RAFG 는 비순차적이거나 교차 관심사 (Cross-cutting concerns) 가 관련된 복잡한 시나리오에서 시간적 근접성을 무시하고 개념적 관련성을 우선시함으로써 더 나은 성능을 발휘할 수 있는 잠재력을 보였습니다.
  • Trade-off: RAFG 는 구현 복잡성과 검색 지연 시간을 증가시키지만, Last_K 는 단순하고 효율적입니다.

5. 의의 및 시사점 (Significance)

• 패러다임 전환: ADR 자동화에서 모델의 규모 (Parameter Count) 나 아키텍처 혁신보다 어떻게 컨텍스트를 구성하느냐 (Context Engineering) 가 더 결정적인 요소임을 입증했습니다.
• 실무적 적용:
  • Last_K (최근 3~5 개) 는 인프라 구축 비용이 들지 않는 실용적인 기본 전략으로 권장됩니다.
  • 로컬 실행 가능한 경량 모델 (Gemma-3-4B 등) 도 적절한 컨텍스트를 제공하면 대규모 모델과 유사한 품질의 ADR 을 생성할 수 있어, 데이터 거버넌스 요구사항이 있는 조직에도 적용 가능합니다.
  • 문서화 위생 (Documentation Hygiene): 외부 링크나 암묵적 지식에 의존하는 ADR 은 자동화 도구와 평가 메트릭 모두에서 성능 저하를 유발하므로, ADR 은 자기 완결적 (Self-contained) 이어야 함을 강조합니다.
• 향후 연구 방향:
  • 시간적 근접성과 의미적 검색을 결합한 하이브리드 전략 개발.
  • 소스 코드와의 양방향 추적성 확보.
  • 다양한 도메인과 조직 문화에 따른 컨텍스트 전략의 최적화 연구.

요약

이 논문은 LLM 을 이용한 ADR 자동 생성에서 "어떤 과거 기록을 컨텍스트로 줄 것인가" 가 핵심임을 증명했습니다. 전체 히스토리를 모두 넣는 것보다 최근 3~5 개의 기록 (Last_K) 을 제공하는 것이 효율성과 품질 면에서 가장 우수하며, 복잡한 교차 의존성 문제가 있을 때만 의미 기반 검색 (RAFG) 을 고려해야 함을 시사합니다. 이는 소프트웨어 아키텍처 문서화 자동화의 실용적 구현을 위한 중요한 이정표가 됩니다.