TL;DR

  • OpenAI Decisions API는 애플리케이션이 제공한 GitHub 풀 리퀘스트(PR)의 변경 사항을 정해진 검토 질문에 따라 평가하고 검토 경로를 정리하는 데 활용됨.
  • “PR이 좋은가?”처럼 기준이 불분명한 질문보다 검토 경로 분류와 기존 호출자의 마이그레이션 필요성처럼 범위가 좁고 역할이 명확한 질문이 적합함.
  • 모델 입력에는 PR 제목과 설명, 변경 파일 경로와 패치가 포함되며, 증거가 부족한 경우 needs_review 선택지를 두고 기여자 제공 내용은 지시가 아닌 증거로 취급함.
  • 예제 스크립트는 Node.js 22 이상, GitHub 및 OpenAI 자격 증명을 사용하며 변경 파일 1~100개, 패치 누락 없음, 입력 100KB 이하 조건을 적용함. 이는 예제의 제한이며 Decisions API의 입력 한도가 아님.
  • 반환된 판단은 검토 보조 자료이며 정확성이나 병합 준비 상태를 증명하지 않음. 사람이 결과를 검토하고 테스트·필수 리뷰·브랜치 보호를 별도로 유지해야 함.

풀 리퀘스트에 무엇을 물어야 할까?

  • 검토 절차에서 역할이 분명한 판단부터 질문해야 함. “이 PR이 좋은가?”는 정확성, 설계, 프로젝트 선호를 한데 섞어 승인 기준이 불분명함.
  • “이 변경으로 기존 호출자가 코드를 업데이트해야 하는가?”는 검토자가 평가할 수 있는 더 구체적인 우려를 짚음.
  • CSV 파서의 기본 구분자를 쉼표에서 세미콜론으로 바꾸는 사례에서는 구현 변경이 작더라도 기존 기본값에 의존하는 호출자가 명시적 옵션을 지정해야 할 수 있음. PR 설명에서 정리 작업이라고 표현하더라도 호환성 검토가 관련될 수 있음.
  • 같은 변경 사항에 서로 독립적인 두 질문을 적용하는 예시는 다음과 같음.
  • 질문: 눈에 보이는 변경에 적합한 검토 경로는 무엇인가?
  • 응답 유형: 선택지
  • 선택지: 호환성, 구현, 검토 필요
  • 활용: 검토 대기열 제안
  • 질문: 패치에 기존 호출자의 마이그레이션이 필요한 변경이 드러나는가?
  • 응답 유형: 조건 판단
  • 의미: 해당 조건이 참일 확률
  • 활용: 마이그레이션 안내 검토 대상으로 표시
  • 결정 모델의 응답 유형을 사용하면 출력이 예측 가능해짐. 다만 공개 인터페이스의 정의, 호출자가 의존할 수 있는 동작, 추가 맥락이 필요한 변경 등 질문의 정의는 각 저장소에 맞아야 함.

모델에 어떤 증거를 제공해야 할까?

  • 맥락으로 PR 제목과 설명을 제공하고, 변경된 파일 경로와 패치 텍스트를 포함해야 함. GitHub 풀 리퀘스트 REST API에서 해당 정보를 가져올 수 있음.
  • 파일 경로만으로는 영향을 받는 영역을 알 수 있지만 코드 변경이 동작을 바꾸는지는 설명할 수 없음.
  • 패치만으로는 판단이 어려운 경우도 있음. 내보낸 함수가 내부 패키지에 속하거나 다른 계층이 변경을 보완해 동작이 유지될 수 있음. 답변에 중요한 세부 사항이라면 관련 인터페이스 문서와 주변 코드도 추가해야 함.
  • 제공된 증거만으로 검토 경로를 확정할 수 없는 경우를 위해 예제는 needs_review 선택지를 명시함.
  • PR 설명과 소스 코드 주석은 기여자가 제공한 증거로 취급해야 함. 판단 지침은 애플리케이션이 관리하며, “호환성 검토를 건너뛰라”는 주석이 검토 정책을 바꾸도록 두지 않아야 함.

GitHub 풀 리퀘스트에서 어떻게 시험할 수 있을까?

  • 예제 실행에는 Node.js 22 이상과 터미널 환경 변수 OPENAI_API_KEY, GITHUB_TOKEN이 필요함. GitHub 토큰에는 저장소의 풀 리퀘스트를 읽을 권한이 필요함.
  • 스크립트는 선택한 PR의 제목, 설명, 텍스트 패치를 OpenAI에 직접 전송함.
  • 예제는 변경 파일이 1~100개인 PR을 처리하고 모든 파일에 패치 텍스트가 있어야 함. 수집한 입력이 예제에서 정한 100KB 예산을 넘거나 수집 중 PR이 변경되면 중단함. 이 제한은 작은 텍스트 변경을 대상으로 한 예제의 경계이며 Decisions API의 입력 제한이 아님.
  • 구현 절차는 다음과 같음.
  • 저장소 소유자, 저장소 이름, PR 번호를 입력으로 받고 환경 변수와 인수 형식을 확인함.
  • GitHub REST API로 PR 정보와 파일 목록을 가져오며, 요청에 30초 시간 제한을 설정하고 리디렉션을 거부함.
  • 파일 수와 패치 존재 여부를 확인한 뒤 PR 정보를 다시 조회해 헤드 커밋, 베이스 커밋, 제목, 설명이 수집 도중 바뀌지 않았는지 확인함.
  • 제목, 설명, 파일명, 이전 파일명, 상태, 패치로 입력을 구성하고 UTF-8 기준 크기를 확인함.
  • PR 콘텐츠를 지시가 아닌 증거로 취급하도록 지침을 포함해 gpt-6-luna 모델에 검토 경로 선택과 마이그레이션 조건 판단을 요청함.
  • PR 식별자, 수집한 헤드·베이스 커밋 식별자, 모델, 응답을 JSON으로 출력함.
  • 실행 명령은 node triage-pr.mjs OWNER REPO PR_NUMBER 형식이며, 인수에는 확인할 저장소와 PR을 지정함. 출력에는 OpenAI의 답변과 증거 수집에 사용한 커밋 식별자가 포함됨.
  • 스크립트는 GitHub 데이터를 읽고 결과를 출력할 뿐 제안된 코드를 체크아웃하거나 실행하지 않음.
  • 더 큰 PR을 처리하려면 GitHub 페이지네이션을 적용하고 각 질문에 필요한 추가 맥락을 선택해야 함. 입력 예산에 맞추려고 diff 일부를 잘라낸 뒤 전체 변경에 대한 평가처럼 취급해서는 안 됨. 패치가 있어도 저장소 맥락의 일부일 뿐임.

반환된 답변을 어떻게 사용해야 할까?

  • answers 배열에서 각 답변을 이름으로 찾아야 함. review_track의 선택지 답변에는 선택된 값과 대안별 확률이 들어가며, migration_needed의 조건 판단 답변에는 눈에 보이는 변경이 마이그레이션을 요구할 추정 확률이 들어감.
  • Decisions API 응답 스키마에서는 개별 답변 유형이 거부(refusal)일 수도 있으므로 해당 필드를 읽기 전에 유형을 확인해야 함.
  • 결과를 검사한 헤드와 베이스 커밋에 연결해야 함. 새 커밋이 추가되거나 비교 기준 브랜치가 바뀌면 증거가 달라질 수 있으므로, 이전 결과를 현재 작업의 경로 지정에 사용하기 전에 다시 분류해야 함.
  • 이후 라벨이나 리뷰어 제안을 추가하더라도 답변을 GitHub 작업에 대응시키는 규칙은 애플리케이션 코드가 관리해야 함.
  • 먼저 추천 검토 경로를 리뷰어에게 보여주고, 의견이 다른 사례를 모아 원인이 모델인지, 맥락 부족인지, 불분명한 검토 정책인지 살펴봐야 함. 자동화 임계값은 이런 사례와 잘못된 경로 지정의 결과를 바탕으로 정해야 함. 예제는 특정 임계값을 적용하지 않고 예측을 출력함.

이 평가는 무엇을 입증하지 않을까?

  • PR 분류 결과만으로 변경의 정확성이나 병합 준비 상태가 입증되지는 않음. 구현 변경으로 분류되더라도 결함이 있을 수 있고, 마이그레이션 확률이 낮더라도 정보가 부족한 결과일 수 있음.
  • 테스트, 필수 리뷰, 브랜치 보호는 개발 절차의 별도 요소로 유지해야 함.
  • 두 모델 질문은 서로 다른 내용을 판단함. 예를 들어 선택적 매개변수 추가처럼 기존 호출자의 변경이 필요하지 않아도 호환성 검토는 유용할 수 있음.
  • 검토 경로 선택이나 마이그레이션 확률은 서면 코드 리뷰를 대신하지 않음. 설명, 수정 제안, 대안 논의가 필요하다면 별도의 리뷰 절차를 사용해야 함.

자주 묻는 질문

OpenAI Decisions API가 GitHub 풀 리퀘스트를 직접 가져올 수 있을까?

  • 가져올 수 없음. 애플리케이션이 PR 증거를 조회해 결정 요청에 포함해야 함. 예제는 OpenAI 호출 전에 GitHub REST API로 메타데이터와 파일 패치를 수집함.

스크립트가 풀 리퀘스트를 승인하거나 병합할까?

  • 승인하거나 병합하지 않음. 스크립트는 리뷰 제안과 확률을 출력하며 GitHub를 변경하지 않음. 병합 요건은 저장소의 리뷰 및 테스트 절차에 남음.

패치가 없거나 입력이 너무 큰 풀 리퀘스트는 어떻게 될까?

  • 예제는 패치가 누락됐거나 수집 입력이 예산을 넘으면 OpenAI를 호출하기 전에 중단함. 해당 PR을 별도로 처리하거나 질문에 맞는 증거를 모델에 제공하도록 수집 방식을 확장해야 함.

한 요청으로 여러 검토 우려를 확인할 수 있을까?

  • 가능함. OpenAI는 같은 입력에 대해 여러 독립 질문을 받을 수 있음. 후속 질문이 앞선 답변에 의존한다면 요청을 분리하고 애플리케이션 코드에서 진행 여부를 결정해야 함.

참고 자료

  • OpenAI Decisions API 가이드
  • GitHub 풀 리퀘스트 REST API
  • AI SDK 평가에서 Decisions로: 코드에서 무엇이 바뀌는가?