수작업의 굴레를 벗어나 주간 릴리스 체계로 전환

개발자는 수십 개의 PR(Pull Request, 코드 수정 제안)을 일일이 확인하며 릴리스 노트를 작성하는 반복적인 수작업을 수행해 왔다. 변경 사항을 취합하고 읽기 좋게 정리하는 과정은 기술적으로 어렵지 않으나, 서로 다른 주제를 가진 수십 개의 제안서를 분석하는 데 상당한 집중력이 요구된다. 실제로 허깅페이스 유지관리자는 공지문 작성을 포함한 소규모 릴리스 하나를 처리하기 위해 며칠에 걸쳐 반나절 이상의 시간을 소모했다.

허깅페이스는 이러한 수작업 중심의 프로세스를 AI 기반 자동화로 전환하여 `huggingface_hub`의 릴리스 주기를 기존 4~6주에서 매주 1회로 단축했다. 이번 체계의 핵심은 릴리스 과정에서 발생하는 업무를 기계적 단계와 판단 단계로 분리한 것이다. 버전 업데이트, 커밋, 태깅, 푸시, 하위 테스트 브랜치 생성과 같은 기계적 절차는 CI(지속적 통합, 코드 변경 사항을 자동으로 테스트하고 병합하는 체계) 워크플로우에 맡기고, 릴리스 노트 작성과 공지문 초안 생성이라는 '두뇌 작업'에 AI를 투입했다. 이를 통해 유지관리자는 며칠이 걸리던 집필 노동에서 벗어나 15분 내외의 최종 검토 세션만으로 배포를 완료할 수 있게 되었다.

오픈 웨이트 모델과 GitHub Actions 기반의 자동화 스택

허깅페이스는 외부 벤더 계약이나 폐쇄형 모델 없이 유지관리자가 직접 실행하고 제어할 수 있는 투명한 워크플로우 구축을 설계 목표로 설정했다. 특정 기업의 API에 종속되어 모델을 교체할 수 없거나 독점적인 릴리스 플랫폼을 사용하는 상황을 배제하고, 누구나 자신의 프로젝트에 맞춰 수정하고 도입할 수 있는 구조를 지향했다. 이를 위해 GitHub Actions(깃허브 액션, 소프트웨어 개발 워크플로우 자동화 도구)와 오픈 웨이트 모델(Open-weights models, 가중치 값이 공개된 AI 모델)을 조합해 전체 스택을 구성했다.

모든 자동화 동작은 `.github/workflows/release.yml` 파일 하나에서 제어되며, 사용자가 GitHub Actions UI에서 수동으로 트리거하는 방식으로 작동한다. 워크플로우가 실행되면 시스템은 버전 번호를 올리고, 변경 사항을 커밋하며, 태그를 생성해 푸시하는 과정을 순차적으로 수행한다. 이후 하위 테스트 브랜치를 열고 릴리스 완료 후의 PR을 생성하는 범위까지 자동화 대상에 포함했다. OpenCode라는 도구를 함께 활용하여 별도의 인프라 구축 비용 없이도 유지관리자가 직접 실행 가능한 환경을 구현함으로써, 도구의 접근성과 제어권을 동시에 확보했다.

비결정론적 AI를 제어하는 '신뢰-검증' 루프

AI 모델은 자연스러운 문장을 생성하는 능력은 뛰어나지만, 동일한 입력값에도 결과가 달라질 수 있는 비결정론적 특성을 가진다. 이러한 특성은 릴리스 노트에서 특정 PR을 누락하거나 존재하지 않는 기능을 지어내는 환각(Hallucination, 사실이 아닌 정보를 그럴듯하게 생성하는 현상)으로 이어질 위험이 있다. 특히 AI가 자신감 있게 작성한 잘못된 초안은 검토자가 이를 그대로 신뢰하게 만들어, 아무런 초안이 없는 상태보다 더 위험한 결과를 초래한다.

허깅페이스는 이를 해결하기 위해 비결정론적인 AI 초안을 결정론적인 파이썬 스크립트로 검증하는 '신뢰-검증(Trust-but-verify)' 루프를 도입했다. 파이썬 스크립트가 AI 모델 작동 전 릴리스 대상 PR 전체 목록을 추출해 정답지인 그라운드 트루스(Ground Truth, 실제 정답 데이터)로 저장한다. AI가 초안을 작성하면 스크립트가 출력물과 초기 PR 목록을 대조해 누락이나 추가 항목이 있는지 확인하는 가드레일을 실행한다. 만약 불일치가 발견되면 전체 프로세스를 중단시키는 대신, 오류가 발생한 특정 PR들만 식별해 에이전트에게 다시 수정하도록 요청하는 피드백 루프를 통해 결과의 완결성을 보장한다.

문서 Diff 분석과 SKILL.md를 통한 정확도 향상

AI가 PR 제목만으로 내용을 요약할 경우, 실제 API와 일치하지 않는 코드 예시를 임의로 만들어내는 문제가 발생한다. 허깅페이스는 이를 방지하기 위해 PR 메타데이터와 함께 실제 변경된 문서 내용을 컨텍스트에 포함하는 방식을 적용했다. 구체적으로 `docs/` 경로 하위의 .md 파일에서 발생한 unified diff(변경 전후의 차이를 텍스트로 보여주는 형식)를 추출해 AI에게 제공한다. 이를 통해 AI가 새로운 CLI(명령줄 인터페이스, 텍스트로 컴퓨터에 명령을 내리는 방식) 명령어를 설명할 때, PR 작성자가 문서에 실제로 작성한 예시를 그대로 인용하게 하여 서술의 정확도를 높였다.

AI의 출력 품질을 일정하게 유지하는 지침은 `SKILL.md`라는 별도의 마크다운 파일에서 관리한다. 이 파일은 하이라이트 항목 선정 기준, 섹션 구조화 방법, 문서 링크 추가 시점 등을 정의한 프롬프트 저장소로 작동한다. 이는 새로운 팀원이 업무를 배울 때 읽는 온보딩 가이드와 같은 형태로 작성되어 AI에게 구체적인 역할과 규칙을 부여한다. 프롬프트를 실행 코드와 분리해 파일로 관리함으로써 유지관리자는 프로젝트의 성격이나 톤앤매너에 맞춰 지침을 쉽게 수정할 수 있으며, 이는 곧 AI의 출력 품질 개선으로 이어진다.

OIDC 보안 강화와 데이터 피드백 기반의 지속적 개선

허깅페이스는 공급망 공격을 막기 위해 PyPI(파이썬 패키지 인덱스) 배포 보안 체계를 OIDC(OpenID Connect, 개방형 인증 표준) 기반의 Trusted Publishing(신뢰 기반 게시)으로 전환했다. 기존의 고정된 토큰 방식 대신 깃허브가 발행한 단기 토큰을 PyPI가 검증하는 구조를 채택하고, PEP 740 증명과 Sigstore(소프트웨어 공급망 보안 도구) 출처 확인을 적용해 유출 위험이 있는 장기 비밀키 관리 비용을 제거했다. 또한 에이전트 런타임인 OpenCode의 버전을 특정 지점으로 고정하고 SHA256(데이터의 고유 해시값) 검증을 거친 뒤 실행하도록 설정해 검증되지 않은 코드의 유입을 차단했다.

자동화의 결과물은 다시 모델의 학습 자산으로 전환된다. AI가 작성한 원본 초안과 인간이 최종 수정한 버전을 허깅페이스 버킷(Hugging Face Bucket, 클라우드 저장소)에 병렬로 저장하여, 모델의 작성 내용과 인간의 요구 사항 사이의 간극을 분석하는 데이터셋을 구축했다. 이렇게 수집된 데이터는 `SKILL.md` 지침을 정교화하는 기초 자료로 활용된다. 이러한 전체 과정(20~40개 PR 처리 및 공지 생성)에 드는 비용은 Inference Providers(인퍼런스 프로바이더, AI 모델 추론 서비스 제공자)의 종량제 요금 기준 약 0.25달러에 불과하다.

이 체계를 도입하려는 실무자는 네 단계의 과정을 거치면 된다. 먼저 `.github/workflows/release.yml` 파일을 포크(Fork, 저장소 복제)하여 대상 패키지를 지정하고, 프로젝트의 목소리를 담아 `SKILL.md`를 수정한다. 이어 모델 ID와 OpenCode 버전을 변수로 설정한 뒤, PyPI의 Trusted Publishing을 설정하면 저비용 고신뢰 자동화 파이프라인을 즉시 실행할 수 있다.