무료 서버로 전환하기 전에 도구 계약을 포팅하는 방법

코딩 워크플로우를 무료 모델 액세스로 재지정하기 전에 도구 계약(tool contract)을 포팅해야 합니다. 남아 있는 유료 엔드포인트, 무제한 재시도 횟수, 그리고 공급업체 도구 이름들은 취소되어도 살아남아 다음 실행을 계속 지휘합니다. 휴대 가능한 계약과 남은 스캔 정보가 있으면 노트북에서 리허설할 수 있는 전환(cutover)이 생깁니다. 무료 서버 용량이 여전히 이전 유료 호스트를 호출하는 도구 스키마를 고치지는 못합니다.

이 마이그레이션 다이어리는 이 이동을 모델 브랜드 간의 경쟁이 아니라 운영 문제로 취급합니다. 이것은 과거 도구 호출 기록부가 아니며, 서비스가 이미 노출하고 있는 공개 API의 스냅샷도 아닙니다. 사용자가 가진 검토 규칙(review rules)만 유지하고, 공급업체 SDK가 엔드포인트를 숨겼기 때문에 존재하는 바인딩(bindings)은 제거해야 합니다. 이것은 특정 할당량(quota)이 유지할 것이라는 주장이 아니라, 스크래치 디렉토리에서 실행해야 하는 제안입니다.

호스트를 선택하기 전에 남겨진 것들을 명명하세요

유료 코딩 에이전트는 보통 채팅 기록에 내보내지지 않는 세 가지 것을 저장합니다. 첫째는 로컬 이름과 공급업체 URL, 타임아웃, 재시도 정책을 바인딩하는 도구 맵(tool map)입니다. 둘째는 에이전트가 접근할 수 있는 리포지토리, 셸, 네트워크 호스트를 나열하는 권한 노트(permission note)입니다. 셋째는 여전히 이전 호스트 문자열과 이전 계정 ID를 포함하는 실패 호출 캐시입니다.

만약 이 디렉토리를 무료 서버에 복사하면, 유용한 규칙들과 함께 이전 청구 경로(bill path)도 가져오게 됩니다. 유료 계정을 완전히 삭제하기 전에 휴대 가능한 동작(portable behavior)과 공급업체 잔여물(vendor residue)을 분리해야 합니다. 휴대 가능한 동작에는 허용하는 파일 패턴, 금지하는 명령어, 수락하는 diff 크기가 포함됩니다. 공급업체 잔여물에는 기본 URL, 독점 도구 이름, 숨겨진 원격 측정 플래그(telemetry flags), 그리고 관대한 제한을 가정하는 재시도가 포함됩니다.

접근 권한이 남아 있을 때 두 목록을 모두 적어두세요. 왜냐하면 내보내기 버튼은 종종 재시도(retry) 블록을 누락하기 때문입니다. 나중에 호스팅할 곳에서는 비록 모델 자체에 여전히 접근할 수 있다 하더라도, 당신이 기록하지 않은 시간 초과(timeout)를 복구할 수 없습니다. 누락된 재시도 블록은 다음 주에 기억할 세부 사항이 아니라 전환 결함으로 간주해야 합니다.

감(vibe) 대신 의사 결정표 사용하기

당신이 원하는 아티팩트는 의사 결정표, 로컬 스캐너, 그리고 모든 설정 편집 후에 다시 실행할 수 있는 짧은 승인 테스트입니다. 새 호스팅 환경을 선택하기 전에 각 바인딩(binding)을 한 번씩 읽고 네 가지 결과 중 하나로 표시하세요. 'Keep'은 규칙이 여전히 당신의 리포지토리를 설명하며 공급업체, 호스트 또는 계정을 명시하지 않는다는 의미입니다. 'Rewrite'는 동작 자체는 보존할 가치가 있지만, 엔드포인트(endpoint), 도구 이름 또는 시간 초과가 그렇지 않다는 의미입니다.

'Drop'은 호출이 다음 호스팅 환경에서 대체하지 않을 유료 기능을 충족시키기 위해 존재했다는 의미입니다. 'Block'은 해당 바인딩이 아직 검토하지 않은 비밀 정보(secrets), 프로덕션 호스트 또는 쉘에 접근할 수 있다는 의미입니다. 이 표가 바로 전환 계획이며, 결과가 명확해지기 전까지는 행을 마이그레이션해서는 안 됩니다. 'Block' 행은 사람이 명령, 경로 목록 및 비밀 출처를 검토하기 전까지는 마이그레이션하지 않습니다.

'Drop' 행은 무료 모델을 가리킨다고 해서 수정할 수 없습니다. 왜냐하면 그 동작 자체가 당신의 것이 아니었기 때문입니다. 'Rewrite' 행은 로드되기 전에 새로운 이름, 새로운 시간 초과, 그리고 새로운 시도 횟수 제한이 필요합니다. 이전 공급업체 URL을 잔여 파일(residue file)에 남겨두어 제거되었음을 증명할 수 있게 하세요. 만약 한 행을 분류할 수 없다면, 'Block'으로 표시하고 해당 도구의 전환을 중단하세요.

도구 계약만 담는 디렉터리를 만들고, 이 디렉터리는 수정하려는 리포지토리 외부에 두세요. 에이전트 설정을 복사한 다음, 도구 이름, 경로(path), 타임아웃(timeout), 시도 횟수(attempts)를 지정하는 필드만 남기도록 축소하세요. 공급업체 URL(vendor URL)은 스캐너가 볼 수 있도록 별도의 파일에 두고, 나중에 이 파일을 로드하지 않도록 하세요.

mkdir -p cutover/tool-contract
cp agent/tools.json cutover/tool-contract/tools.vendor.json
python3 cutover/freeze_contract.py cutover/tool-contract/tools.vendor.json

아래의 동결(freeze) 스크립트는 실행되지 않은 제안이며, 복사된 설정에서만 실행해야 합니다. 이 스크립트는 작은 허용 목록(allowlist)의 필드를 유지하고 나머지 모든 키를 검토할 수 있는 잔여 파일(residue file)에 작성합니다. 스크립트를 홈 디렉터리에 지정하지 마세요. 관련 없는 파일들이 의도치 않게 파싱하려는 토큰을 포함할 수 있기 때문입니다.

#!/usr/bin/env python3
"""제안: 휴대 가능한 도구 계약 동결(freeze). 이 초안에서는 실행되지 않습니다."""
import json
...

동결 작업을 마친 후, 잔여 파일을 열어 기본 URL(base URLs), 계정 식별자(account identifiers), 공급업체 도구 별칭(vendor tool aliases)을 확인하세요. 만약 이 파일이 비어 있다면, 에이전트가 실제로 로드하는 라이브 바인딩(live binding) 대신 요약 보기(summary view)를 내보냈을 가능성이 높습니다. 유료 구독을 취소하기 전에 에이전트 설정으로 돌아가 원시 바인딩(raw binding)을 내보내세요.

2단계: 더 좁은 예산을 위해 재시도 횟수 제한하기

유료 플랜은 종종 호출이 성공하거나 공급업체 타임아웃이 발생할 때까지 반복하는 재시도 도우미(retry helper)를 숨기고 있습니다. 무료 모델 접근은 느리거나, 작거나, 혹은 특정 날짜에는 단순히 사용할 수 없을 수도 있으므로, 지난달의 제한을 가정해서는 안 됩니다. 휴대 가능한 파일에 명시적인 시도 상한선(attempt ceiling)을 설정하고, 이 상한선에 도달하면 작업을 실패시키세요. 두 번의 시도는 시작 제안일 뿐이며, 모든 리포지토리에 복사해야 할 측정된 최적값은 아닙니다.

빌드가 느리다면 빌드 도구에 대해서만 타임아웃을 늘리고 일반적인 파일 읽기는 짧게 유지하세요. 무료 서버가 긴 재시도 루프를 더 저렴하게 만들지는 못합니다. 왜냐하면 여전히 큐 시간과 로그 볼륨으로 비용을 지불하기 때문입니다. 다음 작업자가 이전의 무제한 도움말 기능을 복원하지 않도록 결정 테이블에 선택된 상한선을 기록하세요.

{
  "tools": {
    "read_file": {
...

3단계: 새 호스트가 부팅되기 전에 잔여물 스캔하기

포터블 파일에 여전히 호스트, 비밀과 같은 할당(secret-like assignment), 또는 무한정 시도 횟수가 포함되어 있는 경우 실패하는 스캐너가 필요합니다. 이 명령어는 CI에서 실행해도 안전한데, 방금 디스크에 생성한 계약 디렉토리만 읽기 때문입니다. 모델을 호출하지 않으며, 네트워크 접근, 토큰 또는 실행 중인 에이전트 프로세스가 필요하지 않습니다.

#!/usr/bin/env python3
"""제안: 포터블 계약에 여전히 유료 잔여물이 남아 있으면 실패합니다."""
import json
...

python3 cutover/scan_leftovers.py cutover/tool-contract/tools.portable.json

실패를 경고로 간주하여 마이그레이션 일정을 깔끔하게 유지하기 위해 억제하는 것이 아니라, 차단된 전환(blocked cutover)으로 취급하세요. 이 스캐너는 의도적으로 범위가 좁기 때문에, 통과했다고 해서 워크플로우가 정확하거나 완전하다는 것을 증명하지 못합니다. 통과는 단지 이 파일이 더 이상 코드에 나열하기로 선택한 잔여 패턴을 포함하고 있지 않다는 것만을 증명할 뿐입니다.

4단계: 게이트를 넓히지 않고 무료 모델 액세스로 리허설하기

스캔이 통과하면, 임시 작업 공간(scratch workspace)을 무료 모델 액세스에 연결하고 지루하지만 읽기 전용 작업을 하나 실행하세요. 테스트 디렉토리의 요약만 요청하고, 네트워크는 비활성화하며, 추적 기록(trace)을 포터블 파일과 비교하세요. 내보내기가 불완전할 경우 여전히 이전 설정 화면이 필요하므로, 두 파일이 일치할 때까지 유료 계정을 활성 상태로 유지하세요.

공개: 이 문서는 MonkeyCode의 제품 홍보의 일환으로 작성되었습니다. MonkeyCode는 단지 현재 무료 모델 액세스와 해당 리허설을 위한 무료 서버 옵션을 제공하는 한 곳일 뿐입니다. 의존하기 전에 제품 페이지에서 라이브 제한, 모델 목록 및 기간을 확인하십시오. 이 초안은 할당량, 하드웨어 모양, 모델 이름 또는 무료 옵션이 유지될 것이라는 약속을 기록하지 않습니다.

유용한 리허설에는 네 가지 점검 사항이 있으며, 동결한 계약 옆에 관찰된 결과를 작성해야 합니다.

1. 트레이스(trace)는 포터블 계약에 이미 존재하는 도구 이름만 보여야 하며, 추가적인 공급업체 별칭은 붙지 않아야 합니다.
2. 요청 라인에는 이전 공급업체 호스트, 원격 측정 도메인 또는 잔여 파일의 계정 식별자가 포함되어서는 안 됩니다.
3. 강제 시간 초과는 숨겨진 헬퍼가 포기할 때까지 루프를 반복하는 대신 구성된 최대 시도에서 중지해야 합니다.
4. 실행은 허용 목록(allowlist) 외부 경로를 읽을 수 없어야 하며, 상위 디렉터리에 대한 프로브는 재시도 없이 실패로 닫혀야 합니다.

만약 어떤 점검 사항이라도 실패하면, 모델, 호스트 또는 프롬프트 문구를 변경하기 전에 계약을 수정하십시오. 다른 모델은 여전히 삭제하는 것을 잊은 호스트를 호출할 것이며, 더 큰 컨텍스트 창(context window)이 그것을 숨기지 못합니다. 실패한 점검 사항을 잔여 검토(residue review)에 작성하여 유료 계정이 사라진 후 다시 발견하지 않도록 하십시오.

의도적으로 남겨두는 것들

리허설 로그가 동결된 계약과 같은 디렉터리에 저장된 후에만 유료 계정을 취소하십시오. 해당 특정 파일에 대한 서면 보존 이유가 없는 한, 공급업체 인터페이스에서 다른 것은 내보내지 마십시오. 채팅의 허세(Chat vanity), 사용하지 않는 프롬프트 팩, 원격 측정 식별자는 자산이 아니라 남은 잔여물입니다.

결정 테이블(decision table), 포터블 JSON(portable JSON), 잔여 검토(residue review), 그리고 4단계 확인 로그(four-check log)는 유지하고 나머지는 폐기하세요. 또한, 스캐너가 출력하지 않았더라도 이전 에이전트 설정에 존재했던 모든 키를 순환시켜야 합니다. 설정 내보내기(Config exports)는 불완전한 그림이며, 복사된 dotfile에는 JSON 요약에서 누락된 토큰을 여전히 담고 있을 수 있습니다. 키 순환(Rotation)은 사람이 수행하는 단계이므로, 이 일지(diary)는 이를 스크립트하거나 예약하거나 새로운 비밀번호를 저장해주지 않습니다.

누가 이것을 사용해서는 안 되는가

에이전트가 별도의 승인 게이트 없이 배포하고, 메일을 보내거나, 프로덕션 데이터에 접근할 수 있다면 이 방법을 건너뛰세요. 스캐너는 귀하의 비즈니스 위험을 이해하지 못하며, 가격이 0이라는 이유만으로 무료 서버가 샌드박스(sandbox)가 되는 것은 아닙니다. 원시 도구 바인딩(raw tool bindings)을 내보낼 수 없다면 건너뛰세요. 스키마를 추측하는 것은 실제로 가지고 있지 않은 권한을 발명해냅니다.

워크플로우가 대체하지 못한 공급업체 전용 도구에 의존한다면 건너뛰세요. 이 제안은 또한 단일 저장소(single repository)와 전환 전에 모든 바인딩을 읽을 수 있는 단일 운영자(single operator)를 가정합니다. 공유 에이전트 플랫폼에는 소유주, 인벤토리, 그리고 롤백(rollback)이 필요하며, 이것은 이 일지에서 제공하려는 것이 아닙니다. 시도 제한 횟수(attempt cap)를 기준점으로 삼지 말고, 임시적인 성공을 다음 주에도 무료 접근이 유지된다는 증거로 취급하지 마십시오.

만약 포터블 계약을 연습할 저위험 장소를 원한다면, 무료 모델 액세스와 무료 서버를 사용하고 로그를 보관하세요. 이 로그가 현재 호스트의 약관, 모델 또는 가격이 변경될 때 다음 호스트로 가져갈 수 있는 부분입니다. 오늘 선택하는 호스트보다 이 습관이 더 중요합니다. 왜냐하면 다음 전환은 기억(memory)에서가 아니라 이 로그로부터 시작할 것이기 때문입니다.