주요 콘텐츠로 건너뛰기
AI 튜토리얼

UNCUT으로 셸 파이프라인에서 무손실 코딩 에이전트 실행하기

이 튜토리얼에서는 터미널, CI 작업, 컨테이너 및 실험 환경을 위한 소형 헤드리스 코딩 에이전트 하네스인 UNCUT을 설치하고 구성하는 방법을 설명합니다. 프롬프트 실행, 파이프로 전달된 입력 처리, 안전한 도구 사용, JSONL 세션 재개, NDJSON 이벤트 수신, 자동 잘림 없이 프로바이더 제한을 처리하는 방법을 배웁니다.

약 16분 소요
UNCUT으로 셸 파이프라인에서 무손실 코딩 에이전트 실행

UNCUT이란?

UNCUT은 셸 파이프라인, CI 작업, 컨테이너 및 에이전트 실험을 위해 설계된 헤드리스 코딩 에이전트 하네스입니다. 작고 정적으로 링크된 Go 바이너리로 배포되며 표준 입력과 표준 출력을 통해 통신합니다. 터미널 사용자 인터페이스, 텔레메트리, 플러그인 시스템, 백그라운드 에이전트, 자동 재시도 또는 숨겨진 컨텍스트 압축 기능은 없습니다.

UNCUT의 핵심 동작은 무손실 전송 계약입니다. UNCUT은 모든 모델 호출마다 전체 대화를 전송하며, 유효한 UTF-8 프롬프트, 저장된 메시지, 파일 내용 또는 명령 출력을 잘라내거나 요약하거나 정리하거나 다시 작성하지 않습니다. 제공업체가 출력 제한으로 응답을 중단하면 UNCUT은 부분 응답을 성공적인 답변으로 처리하지 않고 오류를 보고합니다.

중요: 무손실 전송은 모델의 컨텍스트 창을 확장하거나 제공업체 측 처리를 제어하지 않습니다. 제공업체는 여전히 너무 큰 요청을 거부할 수 있습니다. UNCUT은 콘텐츠를 조용히 제거하는 대신 해당 실패를 표시합니다.

주요 기능

  • 전체 컨텍스트: 저장된 모든 메시지와 도구 결과가 각 모델 요청마다 전송됩니다.
  • 헤드리스 작동: 최종 텍스트는 stdout에 기록되며, --json을 사용하면 구조화된 NDJSON 이벤트가 제공됩니다.
  • 이식 가능한 바이너리: Linux, macOS 및 Windows용 릴리스가 amd64와 arm64 아키텍처로 제공됩니다.
  • 제공업체 중립 프로토콜: UNCUT은 로컬 서버를 포함한 OpenAI 호환 Chat Completions 엔드포인트에서 작동합니다.
  • 재개 가능한 세션: 추가 전용 JSONL 파일이 전체 메시지와 도구 결과를 보존합니다.
  • 집중된 네 가지 도구: 에이전트는 파일 읽기, 파일 쓰기, 정확한 텍스트 교체 및 명령 실행을 수행할 수 있습니다.
  • 명시적 실패 처리: 잘못된 UTF-8, 손상된 세션, 출력 잘림 및 단계 제한 초과는 자동으로 조용히 복구되지 않고 오류를 발생시킵니다.

UNCUT 설치

Linux

사용 중인 아키텍처에 맞는 릴리스 바이너리를 다운로드합니다. ARM64 시스템에서는 amd64를 arm64로 변경합니다.

VERSION=0.1.1
ARCH=amd64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-linux-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

아직 등록되어 있지 않다면 $HOME/.local/bin을 영구적인 PATH 설정에 추가합니다.

macOS

Apple Silicon 시스템은 일반적으로 arm64를 사용하며, Intel Mac은 amd64를 사용합니다.

VERSION=0.1.1
ARCH=arm64
curl -fSLo uncut "https://github.com/Balanov/uncut/releases/download/v${VERSION}/uncut-darwin-${ARCH}"
mkdir -p "$HOME/.local/bin"
install -m 0755 uncut "$HOME/.local/bin/uncut"
export PATH="$HOME/.local/bin:$PATH"
uncut --version

Windows PowerShell

$Version = "0.1.1"
$Arch = "amd64"
$Dest = "$env:LOCALAPPDATA\Programs\UNCUT"
New-Item -ItemType Directory -Force $Dest | Out-Null
Invoke-WebRequest -Uri "https://github.com/Balanov/uncut/releases/download/v$Version/uncut-windows-$Arch.exe" -OutFile "$Dest\uncut.exe"
$env:Path = "$Dest;$env:Path"
uncut --version

Windows ARM64에서는 amd64 대신 arm64를 사용합니다. 이후 PowerShell 세션에서도 명령을 사용할 수 있도록 대상 디렉터리를 사용자 PATH에 추가합니다.

Go로 설치 또는 빌드

Go 1.26 이상이 설치되어 있다면 최신 버전을 직접 설치합니다.

go install github.com/Balanov/uncut/cmd/uncut@latest

또는 저장소 체크아웃을 빌드합니다.

git clone https://github.com/Balanov/uncut.git
cd uncut
go build -trimpath -ldflags="-s -w" -o bin/uncut ./cmd/uncut

Windows에서는 출력 경로로 bin/uncut.exe를 사용합니다.

다운로드한 바이너리 확인

모든 릴리스에는 checksums.txt 파일이 포함됩니다. 다음 예시는 Linux amd64 다운로드를 확인합니다.

VERSION=0.1.1
ARCH=amd64
curl -fSLO "https://github.com/Balanov/uncut/releases/download/v${VERSION}/checksums.txt"
grep "uncut-linux-${ARCH}$" checksums.txt | sha256sum -c -

현재 릴리스 바이너리는 코드 서명되지 않았으므로 Gatekeeper 또는 SmartScreen에서 경고를 표시할 수 있습니다. 실행 파일을 허용하기 전에 SHA-256 체크섬을 확인합니다. macOS에서 확인한 후에는 설치된 바이너리에서만 격리를 제거할 수 있습니다.

xattr -d com.apple.quarantine "$HOME/.local/bin/uncut"

모델 제공업체 구성

UNCUT에는 모델 식별자가 필요합니다. 호스팅 서비스를 사용하는 경우 일반적으로 API 키도 필요합니다. 두 값을 설정한 다음 프롬프트를 실행합니다.

export UNCUT_API_KEY="your-api-key"
export UNCUT_MODEL="your-model-id"
uncut "Inspect this repository and fix the failing tests"

UNCUT_BASE_URL 또는 OPENAI_BASE_URL이 설정되지 않은 경우 기본 엔드포인트는 https://api.openai.com/v1입니다. 다른 OpenAI 호환 엔드포인트를 사용하려면 해당 기본 URL을 지정합니다.

export UNCUT_BASE_URL="https://openrouter.ai/api/v1"

UNCUT은 UNCUT_API_KEY가 없을 경우 OPENAI_API_KEY를 대신 사용합니다. 로컬 엔드포인트에서는 기본적으로 키가 필요하지 않습니다.

로컬 Ollama 연결

README에서 테스트한 예시는 도구 사용이 가능한 qwen3:8b 모델이 설치되어 있다는 전제를 사용합니다.

ollama pull qwen3:8b
export UNCUT_BASE_URL="http://localhost:11434/v1"
export UNCUT_MODEL="qwen3:8b"
uncut "Explain this repository"

예시를 컴퓨터에 설치된 모델로 바꾸어 사용합니다. 도구 호출의 품질과 동작은 선택한 모델에 따라 달라집니다.

첫 코딩 작업 실행

에이전트가 검사할 저장소에서 UNCUT을 시작하세요. 기본적으로 현재 디렉터리가 파일 도구와 셸 명령의 작업 공간이 됩니다.

cd path/to/project
uncut "이 저장소를 검사하고 테스트를 실행한 다음 실패를 수정하세요"

작업 중 모델은 네 가지 도구를 호출할 수 있습니다.

  • read_file은 UTF-8 텍스트 파일 전체를 읽습니다.
  • write_file은 전체 내용을 쓰고 누락된 상위 디렉터리를 생성합니다.
  • replace는 정확히 한 번 일치하는 항목을 바꿉니다. 일치 항목이 없거나 여러 개이면 실패합니다.
  • run_command는 종료 코드와 stdout 및 stderr를 결합한 전체 출력을 반환합니다.

파일 도구 경로는 작업 공간 내부에 있어야 합니다. Unix에서는 명령이 /bin/sh -c를 통해 실행됩니다. Windows에서는 cmd.exe /D /S /C를 통해 실행됩니다.

Unix 파이프라인에서 UNCUT 사용

UNCUT은 파이프로 전달된 입력을 프롬프트에 있는 그대로 덧붙입니다. 따라서 임시 파일을 만들지 않고도 코드 리뷰와 로그 분석에 적합합니다.

git diff | uncut "이 diff를 검토하세요. 파일은 수정하지 마세요."
cat failing-test.log | uncut "가능성 높은 원인을 찾으세요"

입력은 유효한 UTF-8이어야 합니다. UNCUT은 바이트를 조용히 대체하지 않고 잘못된 입력을 거부합니다. 바이너리 파일도 거부합니다. Windows에서는 일부 명령이 UTF-16 또는 코드 페이지 출력을 생성하므로 가능한 경우 유틸리티가 UTF-8을 출력하도록 구성하세요.

구조화된 NDJSON 이벤트 수신

UNCUT을 스크립트, CI 시스템 또는 다른 에이전트 인프라와 통합할 때는 --json을 사용하세요.

uncut --json "테스트를 실행하고 실패를 수정하세요"

이벤트 스트림에는 다음 레코드 유형이 포함될 수 있습니다.

  • user는 사용자 메시지를 나타냅니다.
  • assistant는 어시스턴트 메시지와 완료된 도구 호출을 나타냅니다.
  • assistant_meta는 사용량 정보와 종료 사유를 나타냅니다.
  • tool은 완료된 도구 결과를 나타냅니다.
  • done은 실행이 성공적으로 완료되었을 때 나타납니다.
  • error는 실행이 실패했을 때 나타납니다.

UNCUT은 스트리밍하지 않는 Chat Completions를 사용합니다. 텍스트와 도구 호출을 지원하지만 이미지 입력은 지원하지 않습니다.

세션 생성 및 재개

세션은 전체 대화와 도구 결과가 포함된 추가 전용 JSONL 레코드입니다. 세션 파일로 작업을 시작한 다음 같은 파일을 재사용하여 계속 진행할 수 있습니다.

uncut --session .uncut/work.jsonl "리팩터링을 시작하세요"
uncut --session .uncut/work.jsonl "테스트를 계속 진행하세요"

파일이 이미 존재하면 UNCUT은 전체 기록을 불러옵니다. 새 레코드는 모든 단계가 끝날 때마다 추가되고 동기화됩니다. 잘못되었거나 불완전한 레코드가 있으면 명시적인 오류가 발생하며, 세션을 강제로 불러오기 위해 해당 레코드를 폐기하지 않습니다.

세션 파일에는 소스 코드, 명령 출력, 자격 증명 또는 기타 비밀 정보가 포함될 수 있습니다. 적절히 보호하고 버전 관리 시스템에 커밋하지 마세요.

작업 공간과 에이전트 루프 제어

현재 디렉터리가 아닌 다른 작업 공간에서 실행하려면 --cwd를 사용하세요.

uncut --cwd ./services/api "API 테스트를 실행하고 실패 원인을 설명하세요"

여러 플래그로 요청 및 루프 동작을 제어할 수 있습니다.

  • --max-steps <n>은 모델 호출 횟수를 제한합니다. 기본값은 32입니다.
  • --max-tokens <n>은 공급자의 기본값 대신 명시적인 공급자 출력 한도를 설정합니다.
  • --request-timeout <duration>은 기본값 10m에서 요청별 제한 시간을 변경합니다. 값이 0이면 제한 시간이 비활성화됩니다.
  • --no-agents는 UNCUT이 작업 공간의 AGENTS.md를 읽지 못하게 합니다.

기본적으로 UNCUT은 작업 공간 루트의 AGENTS.md를 전체 읽어 시스템 프롬프트에 추가합니다. 세션을 재개할 때는 현재 파일로 시스템 메시지를 다시 구성하지 않고, 처음 저장된 시스템 메시지를 재사용합니다.

종료 코드 이해

신뢰할 수 있는 종료 코드 덕분에 UNCUT을 자동화에 활용할 수 있습니다.

  • 0은 에이전트가 성공적인 최종 답변을 생성했음을 의미합니다.
  • 1은 공급자, 입출력, 세션 또는 실행 오류를 나타냅니다.
  • 2는 잘못된 명령줄 사용을 나타냅니다.
  • 3은 공급자가 finish_reason=length 또는 max_tokens를 반환했음을 의미하며, UNCUT은 불완전한 답변을 거부합니다.
  • 4는 최종 답변에 도달하기 전에 최대 단계 수에 도달했음을 의미합니다.

CI에서는 0이 아닌 모든 코드를 실패한 실행으로 처리하고 stderr 또는 --json의 최종 error 이벤트를 확인하세요.

고급 팁

한도를 신중하게 선택하기

UNCUT은 컨텍스트를 압축하지 않으므로 긴 세션과 대규모 도구 결과가 결국 모델의 컨텍스트 창을 초과할 수 있습니다. 적절한 시점에 새 세션을 시작하고, 충분한 컨텍스트 용량을 가진 공급자를 선택하며, 공급자의 응답 한도를 이해한 경우에만 --max-tokens를 설정하세요. UNCUT은 불완전한 응답을 결합하거나 자동으로 재시도하지 않습니다.

자동 실행을 기계 판독 가능하게 유지하기

CI와 통합에는 대화형 최종 텍스트를 파싱하는 대신 --json을 사용하세요. 별도의 메타데이터 이벤트를 사용하면 소비자가 어시스턴트 콘텐츠와 섞지 않고 종료 사유와 사용량을 확인할 수 있습니다.

신뢰할 수 없는 작업에는 격리된 환경 사용

UNCUT은 샌드박스가 아닙니다. 파일 도구가 작업 공간 경계를 적용하더라도 run_command는 현재 운영 체제 사용자의 권한으로 실행되며 이러한 파일 검사에 의해 제한되지 않습니다. 신뢰할 수 없는 프롬프트나 저장소는 일회용 컨테이너 또는 다른 격리된 환경에서 실행하세요. 파일 변경 사항과 세션 기록은 직접 검토하세요.

승인 대화상자, 자동 커밋, 자동 재시도 또는 숨겨진 복구 루프는 없습니다. 따라서 실행 동작은 직접적이지만, 적절히 제한된 환경을 선택하는 책임은 사용자에게 있습니다.

로컬에서 무손실 계약 확인

저장소에는 실제 바이너리와 로컬 제공자를 사용하는 결정론적 증명 스크립트가 포함되어 있습니다. Python 3이 필요하지만 API 키, 외부 모델 또는 서드파티 Python 패키지는 필요하지 않습니다.

go build -o bin/uncut ./cmd/uncut
python bench/proof.py ./bin/uncut

이 증명 스크립트는 대용량 파일과 명령 출력의 완전한 전송, 정확한 세션 재개, 편집 동작, 명시적인 잘림 오류, 단계 제한 및 잘못된 UTF-8 처리를 확인합니다. 이러한 검사는 모델의 품질이 아니라 전송 동작을 측정합니다. 기록된 결과와 재현 방법은 UNCUT 저장소에서 확인할 수 있습니다.

개발 검사 실행

UNCUT 자체를 수정할 때는 Go 코드를 포맷하고, 테스트하고, vet으로 검사하세요.

gofmt -w cmd internal
go test -count=1 ./...
go vet ./...

결론

UNCUT은 터미널, 파이프라인, 컨테이너 및 CI 시스템에서 코딩 에이전트를 실행할 수 있는 의도적으로 작고 투명한 방법을 제공합니다. 완전한 메시지 전송, 명시적인 오류 처리, 재개 가능한 세션, 구조화된 이벤트 및 네 가지 기본 제공 도구를 갖추어, 컨텍스트가 조용히 축소되는 것을 허용할 수 없는 경우에 유용합니다. OpenAI 호환 엔드포인트를 구성하고, 격리된 작업 공간에서 시작하며, 재현 가능한 자동화가 필요할 때는 세션 또는 NDJSON 출력을 사용하세요.