Repro Lens: ML agent를 위한 재현성 검사

Repro Lens는 ML·코딩 agent를 위한 재현성 검사 도구입니다. 코드 속 재현 위험 요소를 스캔하고, 실험을 리플레이하여 변경 전후의 출력을 비교합니다. ML 코드를 변경한 뒤 실험 결과가 깨지지 않았는지 확인하고 싶다면 이것이 핵심 용도입니다. 정적 검사에는 Python 3.11+와 Git만 필요하며 ML 의존성이나 API 키가 필요 없습니다. 다만 실험 리플레이에는 해당 실험 자체의 의존성이 필요하고, 반드시 사용자가 명시적으로 트리거해야 합니다.

누구에게 적합한가

• 코드를 변경하기 전후로 실험의 재현 가능성을 검증해야 하는 ML/연구 엔지니어, 그리고 coding agent에 재현성 감사 프로세스를 설정하려는 팀.
• 정적 스캔만 원하는 사용자: ML 의존성도 API 키도 필요 없고, 스캔되는 코드는 임포트·실행되지 않으며 파일 위치가 포함된 정적 결과를 출력합니다.
• 부적합한 경우: Git 환경이 없으면 두 설치 경로 모두 사용할 수 없습니다. Python이 3.11 미만이면 정적 검사기를 실행할 수 없습니다. 위 요건 외에 소스 자료에는 다른 시스템 전제 조건이 언급되지 않았으며, Windows 등 플랫폼 지원 여부는 공식적으로 밝혀지지 않았습니다.
• 증거에 없는 내용은 추정하지 마십시오. 지원하는 텍스트/코드 언어도, 어떤 agent 클라이언트에서 사용 가능한지도 명시되어 있지 않습니다.

3분 만에 첫 사용 완료하기

전제 조건: 로컬에 Python 3.11+, Git, uv가 설치되어 있어야 합니다. 권장 메인 경로는 uv로 공식 저장소에서 특정 버전을 고정하여 설치하는 것입니다:

uv tool install 'git+https://github.com/00200200/[email protected]'

대안은 가상환경에서 동일한 git URL로 pip 설치하는 것입니다(역시 Git 필요). 이는 부차적인 옵션일 뿐 별도의 메인 진입 경로가 아닙니다.

설치 후 먼저 저위험·읽기 전용 정적 검사를 실행해 보십시오. 프로젝트에서 agent나 터미널에 "repro-lens check로 이 파일에 알려진 재현성 위험이 있는지 검사해줘"라는 작업을 지시합니다. 핵심 동작 check에 해당하며, 파일 위치가 표시된 정적 결과를 반환하고 스캔된 코드는 절대 임포트되지 않습니다. 성공 신호는 출력에 파일 위치가 표시된 결과가 나열되는 것입니다(결론이 "위험 없음"이어도 실행이 성공했다는 의미입니다).

주의: check는 진단 동작이며, 이는 스캔 코드를 임포트하지 않는다는 의미일 뿐입니다. 파일을 읽고 쓰거나, 명령을 실행하거나, 네트워크에 접근하는지는 소스 자료에 설명이 없어 확인할 수 없습니다. 실험 리플레이(verify, 두 실행의 선언된 출력이 일치해야 함)는 실험을 실제로 실행하므로 부작용이 있는 동작입니다. 첫 사용 시에는 사용하지 말고, 사용할 경우 실험 의존성이 완비되었는지 먼저 확인하고 트리거 전에 명확히 승인하십시오.

사용 사례

사례 1: 학습 스크립트 변경 전 정적 감사. agent에 "학습 스크립트에 repro-lens check를 실행해줘"라고 지시합니다. 도구는 check 동작을 수행하여 코드를 임포트하지 않고 정적 결과와 파일 위치를 반환합니다. 이를 바탕으로 변경이 알려진 재현성 위험을 도입했는지 판단할 수 있습니다. 소스 자료에 없는 세부 사항(예: 구체적인 규칙 목록)은 제공되지 않으므로, "위치가 포함된 결과를 얻었다"는 것까지만 확인할 수 있습니다.

사례 2: 수정 후 출력 비교. 전제 조건: 변경 전에 공식 워크플로를 통해 리포트를 저장해 두었어야 합니다. agent에 "repro-lens의 verify로 실험을 리플레이하고, compare로 저장된 두 리포트를 비교해줘"라고 지시합니다. verify는 두 실행의 선언된 출력이 완전히 일치해야 하며, compare는 저장된 리포트를 diff합니다. 기대 결과: verify가 통과하면 출력이 선언과 일치함을 의미하고, compare는 리포트 차이를 제시합니다. 리플레이에는 실험 자체의 의존성이 필요하며 명시적 명령입니다. 도구가 자동으로 리플레이해 주지 않습니다.

사용 경계

• 파일·명령 접근: check는 스캔된 코드를 임포트하지 않습니다. verify는 실험을 실행합니다(의존성 필요). 리플레이는 항상 명시적 명령이며, pre-commit 훅(저장소 repro-lens, rev v0.3.0, id repro-lens)은 코드와 프로젝트 정책만 검사하고 자동 리플레이하지 않습니다. 네트워크 접근 여부는 공식적으로 밝혀지지 않았습니다.
• 확인 지점: 실험을 실행하는 모든 동작(verify)은 트리거 전에 실험 구성과 부작용을 확인해야 합니다.
• 설치 차이: uv로 특정 버전 v0.3.0을 설치하는 것이 권장되며, 가상환경에서의 pip 설치는 공식이 제시하는 대안입니다. 마켓플레이스나 기타 플랫폼 설치 방식은 소스 자료에 언급되지 않았으므로 추정하지 마십시오.
• agent 통합: 저장소의 skills/reproducibility/SKILL.md는 기존 coding agent가 감사 또는 승인된 수정을 수행하도록 안내할 수 있으며, 그 런처는 CLI와 동일한 엔진을 호출합니다. 전체 저장소는 Codex 플러그인이기도 합니다(.codex-plugin/plugin.json 포함). 그 외에 구체적으로 지원되는 agent 클라이언트는 공식 목록이 없습니다.
• 미확인 핵심 정보: 네트워크 동작, 지원되는 코드 언어 범위, check/compare의 읽기·쓰기 경계 모두 공식 설명이 없으므로 사용 전에 저장소 문서를 기준으로 하십시오.