본문으로 건너뛰기
호환성 경고를 넘어 저장소 밖의 호출자를 찾는 Quasar
목차

호환성 경고를 넘어 저장소 밖의 호출자를 찾는 Quasar (2026-10)

원문 정보

테스트를 통과한 뒤에도 남은 옛 API

여러 릴리스 전부터 대체 API가 있던 옛 메서드를 없애려 한다고 가정해 봅니다. 그 메서드로는 새 동작에 필요한 옵션도 표현할 수 없습니다. 남겨 두는 데도 비용이 듭니다. 라이브러리 개발 팀은 deprecated API까지 테스트하고 문서화하고 지원해야 하며, 오래된 진입점을 유지하는 동안 라이브러리를 바꾸는 데도 제약을 받습니다.

라이브러리 테스트는 통과합니다. 호환성 검사기도 메서드 제거를 경고하지만, 그 경고만으로는 아직 이 메서드를 호출하는 소비처가 있는지 알 수 없습니다. 호출자가 한 버전에 몰려 있는지, 여러 세대에 걸쳐 있는지도 빠져 있습니다. 다른 라이브러리가 이 API를 구현하거나 감싸고 있다면 영향은 더 커질 수 있습니다. 몇몇 팀과 직접 조율하면 끝날 일인지, 사용 중단을 알리고 넓은 범위의 이관을 추진해야 할 일인지 판단할 근거가 부족합니다.

작은 규모라면 가까운 팀에 물어보거나 몇몇 저장소를 검색하면 됩니다. Netflix의 공용 Java 라이브러리는 서로 독립적으로 바뀌는 수많은 저장소에서 쓰입니다. 변경은 한 저장소에서 시작하지만, 누가 어떤 버전으로 그 API를 쓰는지 알려 주는 답은 소비처 코드와 빌드에 흩어져 있습니다. 근거를 모으지 못하면 호환성을 깨는 변경을 내보낸 뒤 소비처의 실패로 영향을 알아내거나, 위험을 모른다는 이유로 옛 API를 계속 남겨 두게 됩니다.

Quasar는 이 판단에 필요한 심볼 정의와 참조를 Netflix 저장소 전반에서 색인합니다. 공개 API의 어떤 심볼이 바뀌었는지 찾고, 바로 그 심볼을 쓰는 저장소를 조회하는 도구입니다. 호환성 경고에 관측된 영향 범위를 연결하면, 라이브러리를 만드는 쪽은 머지나 릴리스 전에 다음 행동을 고를 근거를 얻습니다.

사라질 메서드를 참조하는 137개 저장소

원문이 든 예는 Client 인터페이스의 getLegacyValue(Request)를 없애고 getValue(Request, Options)로 바꾸는 변경입니다. Quasar는 커밋별로 보관한 API 정의를 비교해 심볼의 추가, 제거, 시그니처 변경을 구분합니다. 제거되거나 시그니처가 바뀐 심볼이 소비처 영향 분석 후보가 됩니다.

분석 시점은 PR 리뷰입니다. 버전 간 비교도 업그레이드 계획이나 이관 가이드를 작성할 때 유용하지만, 코드 리뷰 중이라면 API를 유지하거나 이관 경로를 먼저 마련하는 선택지가 아직 열려 있습니다.

이 변경을 놓고 API 비교 결과, 사용처 조회 결과, 라이브러리 중요도를 모으면 어떤 판단이 가능할지 보여 주는 설명용 보고서가 있습니다. 한 API의 실제 응답을 그대로 옮긴 자료는 아닙니다. 이 예에서 제거할 메서드를 참조하는 저장소는 137개입니다. 라이브러리에 의존하는 모든 저장소를 센 값이 아니라, 해당 심볼을 참조하는 저장소 수입니다.

버전별로 보면 4.2.1에 86개, 4.1.7에 38개, 3.9.4에 13개가 있습니다. 4.2.1에 모인 큰 집단과 3.9.4에 남은 긴 꼬리가 드러납니다. 샘플 호출 위치에는 checkout-service의 84·129줄과 client-wrapper의 57줄이 붙습니다. 숫자로만 보이던 영향 범위가 엔지니어나 코딩 에이전트가 처리할 파일 경로와 줄 번호의 작업 목록으로 구체화됩니다.

보고서의 라이브러리 중요도는 Tier 1입니다. 이 등급은 하위 애플리케이션 가운데 가장 높은 등급을 따른 것이므로, 메서드를 호출하는 137개 저장소가 모두 Tier 1이라는 뜻은 아닙니다. 심볼 단위의 호출자 수와 라이브러리 전체의 중요도는 구분해서 읽어야 합니다. 이 예에서는 요청한 base와 head SHA의 색인도 모두 확인됐습니다.

이 정도 근거가 있으면 제거 계획도 달라질 수 있습니다. 제거를 머지하고 실패를 기다리는 대신 옛 메서드를 유지하며 사용 중단을 알리고, 이관 경로를 공개한 뒤 소비처와 더 넓게 조율하는 계획을 세울 수 있습니다. 오래된 버전에 남은 호출자도 추적 대상입니다. 같은 API 제거라도 호출자의 수와 버전 분포를 알고 나면 필요한 이관 작업의 규모를 가늠하기 쉬워집니다.

설명용 보고서의 수치와 호출 위치
항목값
변경 종류REMOVED, Client#getLegacyValue(Request)
영향받는 저장소137개
버전 4.2.186개
버전 4.1.738개
버전 3.9.413개
샘플 소비처checkout-service(84, 129줄), client-wrapper(57줄)
라이브러리 중요도Tier 1(가장 높은 등급의 하위 애플리케이션 기준)
base·head SHA 색인둘 다 확인

예시 보고서는 설명용이며 한 API의 실제 응답이 아닙니다.

저장소마다 같은 심볼을 가리키는 SCIP 식별자

호출자를 찾는 데 기존 도구가 모두 같은 답을 주지는 않습니다. 바이너리·소스 호환성 도구는 계약이 달라졌다는 사실을 찾지만 사용자는 찾지 못합니다. 의존성 그래프에는 선언된 의존 관계가 나타나도 특정 메서드를 호출한다는 증거는 없습니다. 텍스트 검색은 오버로드나 상속, 호출에 쓰인 아티팩트 버전을 놓칠 수 있습니다. 소비처 빌드를 실행하면 강한 검증 근거를 얻지만, 전체 저장소에 실행하기에는 비용이 큽니다.

Quasar가 연결의 기준으로 삼은 것은 SCIP의 심볼 식별자입니다. SCIP은 의미 기반 코드 인텔리전스를 위한 공개 교환 형식으로, 언어별 인덱서가 코드의 정의·참조·관계를 안정적인 심볼 식별자와 함께 기록합니다. 각 인덱서가 자기 언어의 코드를 해석하고, Quasar는 그 결과를 저장소 사이에서 연결합니다.

개념적으로 client-lib가 메서드를 정의로 색인하고 checkout-service가 그 메서드의 호출을 참조로 색인하면, 양쪽 기록은 같은 심볼을 가리킵니다. 저장소를 따로 색인해도 연결이 가능합니다. Quasar는 라이브러리 버전·커밋별 API 정의를 소비처 참조와 함께 보관하므로, 한쪽의 API 변경에서 다른 쪽의 정확한 사용처까지 찾아갈 수 있습니다.

색인은 CI에서 쌓입니다. 등록된 CI 빌드가 실행될 때마다 언어별 인덱서가 SCIP 인덱스를 수집 서비스에 제출하고, 수집 서비스는 API 정의와 소비처 참조를 Parquet 형식으로 Amazon S3에 저장합니다. 심볼 식별자만 남기는 것이 아니라 의존성 버전과 소스 위치도 함께 보관합니다.

PR 리뷰에서는 색인된 base와 head의 정의를 비교한 뒤 Amazon Athena로 직접 소비처 참조를 셉니다. 분석 결과를 제공하는 경로는 REST·GraphQL API와 MCP 서버입니다. 후속 사용처 쿼리에서는 버전별 분포와 소스 위치를 더 살펴볼 수 있습니다.

구현체와 그 호출자까지 조사하는 별도의 JVM 호환성 영향 평가 경로도 있습니다. 이 경로에서는 라이브러리 개발 팀의 도구가 변경된 JVM 심볼을 넘깁니다. 앞의 예라면 옛 메서드의 디스크립터를 받고 Quasar가 정식 심볼 식별자를 만듭니다.

직접 참조를 찾는 Athena 쿼리는 요청된 변경 목록인 requested_changes와 참조 테이블 symbol_refs를 그 식별자로 조인합니다. 결과에는 저장소, 의존성 버전, 파일 경로 같은 조사 근거가 담깁니다. Quasar는 구현체와 구현체를 거친 호출도 확인하고, 영향받는 저장소가 중복 집계되지 않도록 한 번씩만 셉니다. 그 저장소에서 발견한 버전과 파일 위치의 샘플도 반환합니다.

참조가 없다는 결과에 필요한 근거

호환성 위반과 높은 위험은 같은 판단이 아닙니다. 호출자가 관측되지 않아도 메서드 제거는 API 계약을 깰 수 있고, 영향받는 저장소와 버전은 그 변경에 필요한 이관 작업을 보여 줍니다. Quasar는 관측한 영향을 보고할 뿐 릴리스 정책을 강제하지 않습니다. 라이브러리 개발 팀은 호환성과 영향 범위를 함께 보고 릴리스 경로를 정합니다.

특히 “참조가 관측되지 않음”에는 범위가 붙습니다. 색인된 대상에서 찾지 못했다는 뜻입니다. 리플렉션, 설정, 동적 로딩으로 쓰이는 API나 오래된 브랜치, 불완전한 색인 때문에 소비처가 드러나지 않을 수 있습니다. 이 결과를 아무도 사용하지 않는다는 증명으로 읽어서는 안 됩니다.

비교할 커밋부터 정확해야 합니다. PR 분석에는 요청한 base와 head 커밋의 API 스냅샷이 모두 있어야 하며, 둘 중 하나라도 없으면 Quasar는 비교할 수 없다고 보고합니다. 기본 브랜치의 스냅샷으로 대신하지 않습니다. 비교 자체를 하지 못한 상태가 변경 없는 API diff처럼 보이는 일을 막기 위한 처리입니다.

소비처 수에도 검토할 근거가 따라야 합니다. 샘플 호출 위치와 버전 분포에 더해, 요청한 커밋이 색인됐는지, 소비처 색인이 얼마나 최신인지, 근거가 잘렸는지를 보여 줘야 합니다. 그래야 137개라는 수치든 참조가 없다는 결과든 어디까지 믿을지 판단할 수 있습니다. 근거가 약하거나 오래됐다면 제거와 이관 계획을 정하기 전에 색인을 먼저 갱신하는 것이 다음 행동입니다.

이 방식은 Netflix 내부 도구인 Quasar 밖에도 적용할 수 있습니다. 의미 단위로 코드를 색인하고 API 정의를 보관하는 데서 출발하되, 변경 시점에 소비처를 조회한 결과와 근거의 품질까지 함께 전달하는 방식입니다. 호출자 수만으로는 부족합니다. 그 숫자가 어디서 나왔고 무엇을 놓칠 수 있는지 확인할 수 있어야 릴리스 판단에 쓸 수 있습니다.

생성된 Java까지 따라가는 Protobuf 참조

소비처가 호출하는 이름이 개발 팀이 관리하는 API에 그대로 나타나지 않는 경우도 있습니다. 생성 코드가 그 사이에 있는 경우입니다. Quasar는 SCIP의 관계 정보를 사용해 Protobuf 정의에서 생성된 Java 멤버를 거쳐, 그 멤버를 쓰는 저장소까지 추적합니다. 소비처 코드에 .proto 요소의 이름이 직접 등장하지 않아도 사용처를 찾습니다.

이런 연결을 여러 언어에서 찾는 일과 호환성이 깨졌는지 판단하는 일은 별개입니다. SCIP은 심볼과 참조를 기록하는 형식이지, 각 생태계의 호환성 규칙을 판정하는 도구는 아닙니다. 참조를 찾았다는 이유만으로 해당 언어의 API 변경까지 평가할 수 있는 것은 아닙니다.

현재 Quasar는 색인된 JVM과 Protobuf API 정의를 비교합니다. Protobuf 변경은 생성된 Java를 거쳐 소비처까지 추적하며, JVM에는 라이브러리 개발 팀의 도구가 식별한 호환성 위반을 입력받는 별도 영향 평가 경로도 있습니다. Go, Python, JavaScript/TypeScript, Rust에서는 사용처 쿼리를 지원하지만, 이 언어들의 호환성을 깨는 API 변경은 아직 평가하지 않습니다.

사용처 조회를 지원하는 언어가 늘어도 호환성 판단에는 해당 생태계의 규칙이나 신뢰할 만한 라이브러리 개발 팀의 신호가 필요합니다. 생태계별 호환성 검사를 더 넓히는 일은 앞으로의 방향입니다.

PR보다 먼저 Quasar를 찾을 코딩 에이전트

코딩 에이전트가 맡는 개발 작업이 늘면 저장소 밖의 맥락도 더 필요해집니다. 에이전트가 로컬 수정을 빠르게 끝내더라도, 그 API를 쓰는 소비처를 모르면 하위 저장소의 위험을 판단하거나 이관 계획을 세우기 어렵습니다. 라이브러리 개발 팀의 판단을 돕던 호출 위치와 버전 정보가 에이전트에게도 필요한 근거입니다.

지금도 에이전트는 요청을 받으면 MCP로 Quasar를 조회할 수 있습니다. 현재 PR에는 API 변경 결과와 관측된 소비처 수, 신뢰도가 나타나며, 별도 쿼리로 버전과 소스 위치를 확인합니다. Netflix가 더 앞당기려는 것은 이 근거를 확인하는 시점입니다. 에이전트가 라이브러리 코드를 쓰면서 공개 심볼을 바꾸고 있음을 알아채고, PR이 생기기 전에 Quasar에 영향을 조회하게 하는 것이 목표입니다.

접근 경로만 마련하면 끝나는 일은 아닙니다. REST·GraphQL API와 MCP는 조회 수단을 제공하지만, 언제 조회해야 하는지까지 에이전트에게 알려 주지는 않습니다. 코딩 워크플로가 공개 API 수정을 인식해야 영향 조회를 시작할 수 있고, 라이브러리 개발 팀을 언제 판단에 참여시킬지도 정할 수 있습니다.

코딩 중의 조회가 PR 분석을 대체하지는 않습니다. PR에서는 구체적인 diff를 검증하고 앞선 작업에서 알아채지 못한 변경을 잡아야 합니다. 색인의 범위와 최신성, 모호성, 미지원 플랫폼, 근거의 잘림 여부도 두 단계 모두에서 기계가 읽을 수 있는 형태로 전달해야 합니다. 에이전트가 “사용 가능한 색인에서 관측된 사용처 없음”을 “제거해도 안전”으로 바꾸어 해석하면 안 됩니다.

그다음 목표는 확인한 호출 위치를 소비처 이관 작업으로 연결하는 일입니다. 지금은 요청에 따른 조회가 가능하며, 이를 코딩 워크플로에 포함하고 에이전트가 이관 변경을 준비하도록 발전시키려 합니다. 같은 사용처 정보는 릴리스 뒤에도 이관할 소비처를 찾는 데 쓰입니다. 코드 리뷰 연동을 더 깊게 하고 에이전트가 이관 수고를 줄이더라도, API와 릴리스 결정의 책임과 승인은 라이브러리 개발 팀에 남습니다.

마지막 수정 일자