OSS 모델 노트는 로컬 검토 계약을 통과해야 효력을 갖는다

OSS(Open Source) 모델 노트는 로컬 계약이 통과될 때까지 비구속적입니다. 이 계약은 하나의 명령어, 하나의 diff 범위, 그리고 두 개의 종료 코드를 잠급니다. 무료 모델은 그 게이트를 통과한 후에만 댓글을 달 수 있습니다.

바인딩되지 않은 노트가 실패하는 이유

긴 모델 답변은 완료된 검토처럼 들릴 수 있습니다. 하지만 여전히 실패하는 명령어의 재실행이 부족합니다. 유지 관리자들은 로컬 증거 대신 모델의 신뢰도를 병합(merge)하게 됩니다.

이 워크플로우는 작업을 세 개의 레인으로 분할합니다. 로컬 재생성(Reproduce)이 버그에 대한 주장을 담당합니다. 일회용 재실행과 모델 읽기(read)는 보조적인 역할을 합니다.

중요한 계약 필드들

계약은 패치 옆의 review-contract.json 파일에 유지하세요. 외부인이 확인할 수 있는 사실만을 기록해야 합니다. 코딩 스타일 의견은 이 파일에서 제외하세요.

{
  "repo": "example/widget",
  "base": "origin/main",
...

expect_before 필드는 패치 이전의 종료 코드를 저장합니다. expect_after 필드는 패치 이후의 종료 코드를 저장합니다. 두 숫자 모두 채팅이 아닌 명령어에서 나와야 합니다.

위젯 경로와 example.invalid 호스트는 실제 프로젝트가 아니라 플레이스홀더입니다. 실제 검토 실행 전에 공개 레포지토리로 교체하세요.

세 개의 레인, 하나의 소유자

운영자는 MonkeyCode를 오픈 소스 프로젝트로 제시합니다. 공개 고지: 이 기사는 MonkeyCode의 제품 아웃리치(product outreach)의 일환으로 준비되었습니다. 해당 주장은 재실행 레인과 읽기 레인에만 적용됩니다.

이 초안은 모델, 할당량(quota), 하드웨어 또는 기간을 명시하지 않습니다. 이러한 수치를 게시하기 전에 현재의 주요 출처를 인용하세요.

1단계. 실패하는 명령어 하나 고정하기

오늘 기준 base 커밋에서 실패하는 명령어를 선택하세요. 어떤 편집보다 먼저 계약에 작성하세요. 절대 종료되지 않는 프롬프트, 워치(watch), 그리고 명령어는 금지합니다.

git fetch origin
git switch --detach origin/main
python -m unittest tests.test_widget
...

출력된 종료 코드를 expect_before 필드에 복사하세요. 0은 이 명령이 버그를 보여주지 않음을 의미합니다. 코드 패치를 작성하기 전에 해당 명령을 교체하세요.

errexit 없이 스니펫을 실행하거나, 셸이 일찍 중단됩니다. 중단된 셸은 절대 before 마커를 출력하지 않습니다. 누락된 마커는 통과가 아니라 재현 실패입니다.

Step 2. 패치를 이름 지정된 경로로 제한하기

패치 실험을 위해 분리된 작업 트리를 여세요. diff를 확인한 후, 경로 목록이 일치할 때만 적용하세요. 더 넓은 diff는 작성된 계약을 거짓으로 만듭니다.

git worktree add --detach ../review-wt origin/main
git -C ../review-wt apply --check patch.diff
git -C ../review-wt apply patch.diff
...

다음 레인 전에 changed.txt를 allowed_paths와 비교하세요. 추가된 경로는 계약이 이미 오래되었음을 의미합니다. 목록을 업데이트하거나 추가 파일을 제거하세요.

Step 3. 로컬 after 로그 캡처하기

검토 작업 트리 내부에서 잠긴 명령을 실행하세요. 결합된 로그와 종료 마커를 저장하세요. 공간 절약을 위해 실패를 절대 잘라내지 마세요.

cd ../review-wt
python -m unittest tests.test_widget > after.log 2>&1
echo "after=$?" | tee -a after.log

expect_after가 0일 때 after 마커를 요구합니다. 다른 마커는 모든 후속 검토 레인을 차단합니다. 로컬 로그는 주요 검토 증거로 유지됩니다.

Step 4. 임시 서버에서 확인하기

임시 서버 세션에 사적인 것을 푸시하지 마세요. 공개 기본 저장소를 클론한 다음, 동일한 패치 파일을 적용하세요. 동일한 명령을 실행하고 서버 종료 코드를 로컬 코드 옆에 기록하세요.

동일한 patch.diff를 서버 레인에서 재사용하세요. 해당 호스트에서 메모리로부터 패치를 다시 빌드하지 마세요.

# 제안만 가능합니다. 실제 실행 전에 플레이스홀더를 교체하세요.
git clone --depth 1 https://example.invalid/widget.git review-srv
cd review-srv
...

서버 블록을 미실행 제안(unexecuted proposal)으로 표시합니다. 무료 서버는 컴파일러, 토큰 또는 긴 작업 시간이 부족할 수 있습니다. 이러한 격차를 기록하고 로컬 로그를 권위로 유지합니다.

5단계. 검열된 읽기 패킷 생성하기

패킷(packet)이라는 폴더에 네 가지 항목을 복사합니다. 계약서, 경로 목록, 두 개의 종료 라인, 그리고 범위가 지정된 diff를 포함해야 합니다. 먼저 비밀 정보(secrets), 환경 파일(env files), 절대 홈 경로(absolute home paths)는 제거하세요.

mkdir -p packet
cp review-contract.json changed.txt packet/
git -C ../review-wt diff -- widget/parse.py tests/test_widget.py > packet/scope.diff
...

이 패킷만이 유일한 모델 입력입니다. 전체 저장소 업로드는 검토 가치 없이 위험을 추가합니다. 노트 작성이 끝난 후에는 이 패킷을 삭제하세요.

6단계. 비구속적 읽기 요청하기

무료 모델에게 발견되지 않은 위험 목록을 작성해 달라고 요청합니다. 각 항목은 경로 또는 계약 키를 인용하도록 요구해야 합니다. '정확함', '안전함' 또는 '준비됨'이라는 판결은 금지하세요.

Role: non_binding_reader
Files: review-contract.json, changed.txt, exits.txt, scope.diff
Task: list risks the locked command does not cover
...

무료 모델 세션은 이러한 좁은 범위의 읽기 작업을 수행할 수 있습니다. 하지만 모델이 여전히 숨겨진 고정 장치(fixtures)와 로컬 관례를 놓칠 수 있습니다. 최종적으로 패치가 적용될지 여부는 인간 유지 관리자가 결정합니다.

7단계. 노트 게시 전 계약서 확인하기

계약서, 경로 목록, 그리고 로컬 로그에 대해 검사기(checker)를 실행하세요. 검사기가 성공을 출력할 때만 모델의 항목들을 게시하세요. 각 항목 앞에 비구속적 레이블을 붙이세요.

python3 check_review_contract.py review-contract.json changed.txt after.log

아래 스크립트는 로컬 미실행 제안입니다. 필드, 역할, 경로 범위, 그리고 종료 마커를 확인합니다. 네트워크에 절대 연결하지 않으며 풀 리퀘스트(pull request)도 열지 않습니다.

#!/usr/bin/env python3
"""Proposal: validate an OSS review contract before model notes."""
import json
...

8단계. 유지 관리자 노트 작성하기

검토자들이 쉽게 스캔할 수 있도록 고정된 노트 형식을 사용하세요. 로컬 증거를 먼저 배치하고 모델 텍스트를 나중에 배치합니다. 모델 섹션은 충분히 짧게 유지하여 스캔 가능하도록 하세요.

Command: python -m unittest tests.test_widget
Local before: 1
Local after: 0
...

서버 종료 라인이 누락된 것은 여전히 허용됩니다. 로컬 종료 라인이 누락된 것은 허용되지 않습니다. 독자들은 이 노트를 신뢰하기 전에 명령을 다시 실행해야 합니다.

실패한 검사 처리 방법

종료 코드 2는 필수 필드나 모델 역할이 잘못되었음을 의미합니다. 종료 코드 3은 diff가 허용된 경로 목록을 벗어났음을 의미합니다. 종료 코드 4는 로컬 로그에 예상되는 마커가 부족함을 의미합니다.

다른 모델 호출 전에 실패한 부분을 수정하십시오. 나쁜 로그를 덮어쓰도록 두 번째 모델에게 요청하지 마십시오. 명령 자체가 변경되었을 때만 계약(contract)을 편집하십시오.

유지되어야 하는 제한 사항

하나의 명령은 통과할 수 있지만, 이웃 동작이 실패할 수 있습니다. 깨끗한 서버라도 여전히 비공개 Fixture나 시스템 패키지를 놓칠 수 있습니다. 무료 모델 문구는 유창할 수 있지만 여전히 불완전할 수 있습니다.

단순히 마커만 포함하는 로그 라인은 이 검사를 속일 수 있습니다. 체커(checker)를 완전한 테스트 증명이 아닌 게이트로 취급하십시오. 마커를 받아들이기 전에 unittest 요약을 읽으십시오.

세트 비교를 실행하기 전에 상대 경로를 정규화하십시오. 선행 접두사는 잘못된 추가 경로 실패를 유발할 수 있습니다.

본 기사에서는 할당량(quota), 지연 시간(latency), 또는 가동 시간(uptime) 수치를 언급하지 않습니다. 해당 값들은 여기서 주요 출처와 비교하여 검증되지 않았습니다. 무료 등급은 약속된 프로덕션 호스트가 아닌 선택적 지원입니다.

사용해서는 안 되는 경우

패치가 비밀 정보나 고객 데이터를 포함할 때는 흐름을 건너뛰십시오. 프로젝트 규칙이 외부 모델 읽기를 금지하는 경우에는 건너뛰십시오. 서버가 연결할 수 없는 장치에 버그가 의존하는 경우에는 건너뛰십시오.

단일 명령으로 표현되지 않는 광범위한 리팩토링에는 건너뛰십시오. 검토가 공식적인 보안 감사를 되어야 하는 경우에도 건너뛰십시오. 구속력이 없는 모델 리더는 그 감사(audit)를 대체할 수 없습니다.

유지해야 할 관행

패치와 함께 계약, 로그 마커, 체커 결과를 저장하십시오. 검토 스레드에서 모든 모델 문장을 비구속적(non-binding)으로 표시하십시오. 관리자 한 명에게 잠긴 명령을 로컬에서 다시 실행하도록 요청하십시오.

선택적 재실행(reruns) 및 모델 읽기(reads)는 그러한 두 번째 검토를 지원할 수 있습니다. 하지만 이는 로컬 종료 코드(local exit code)를 대체하지는 않습니다. 증거와 논평을 분리하여 유지하는 운영자들은 MonkeyCode의 선택적 레인(optional lanes)을 시도해 볼 수 있습니다.