Opus 5를 프로덕션 CI/CD에 붙여보면 첫 주부터 막힙니다. 소켓 통신이나 권한 검증 로직만 들어가면 보안 가드레일이 85% 트리거 레벨에서 차단합니다. Anthropic API 가드레일 동작을 뜯어보면 단순 텍스트 요청 시 정상적인 소켓과 파일 시스템 제어 코드의 28.5%를 위협 코드로 잘못 짚어냅니다.
잘못 들어간 가드레일 하나 때문에 빌드가 터지고 재시도 비용만 쌓입니다. 이 문제를 현장에서 풀었던 프롬프트 구조와 에이전트 상태 관리 방식을 정리했습니다.
샌드박스 설정과 JSON 스키마로 오탐률 낮추기
가드레일이 터지는 이유는 모델이 코드의 실행 맥락을 모르기 때문입니다. API 요청 시 샌드박스 경계를 명확히 하고 반환 형식을 제한하면 오탐을 획기적으로 줄일 수 있습니다.
- System Prompt 최상단에
SAFETY_CONTEXT_BOUNDARIES구문을 넣고, 생성 작업이 격리된 CI/CD 빌드 환경 내부에서만 실행된다는 사실을 밝힙니다. - API 호출 시 JSON Output Schema를 같이 넘겨 반환 값을
status,file_path,generated_code,imports필드로 묶습니다. - API 응답 코드가 400이나 422로 돌아오면 인터페이스를 추상화 모드로 바꾼 뒤 지수 백오프로 다시 요청하는 Python 인터셉터를 파이프라인에 얹습니다.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"status": { "type": "string", "enum": ["success", "abstracted_retry"] },
"file_path": { "type": "string" },
"generated_code": { "type": "string" },
"imports": { "type": "array", "items": { "type": "string" } }
},
"required": ["status", "file_path", "generated_code", "imports"],
"additionalProperties": false
}
이 구조를 붙이면 빌드 실패율이 28.5%에서 4.2%로 떨어집니다. 1,000회 빌드 기준 재시도 비용은 145달러에서 82.5달러로 줄고, 파이프라인 소요 시간도 4.2분에서 2.4분으로 짧아집니다.
Redis 체크포인트로 타임아웃 세션 복원하기
30분이 넘어가는 멀티 파일 리팩토링을 단일 API 세션으로 밀어붙이면 HTTP 타임아웃이 발생합니다. 연결이 끊기면 지금까지 태운 수십만 개의 컨텍스트 토큰이 날아가고 다시 처음부터 시작해야 합니다. 돈은 돈대로 나가고 작업은 끝나지 않습니다.
전체 태스크를 최소 단위로 쪼개고 Redis 기반의 AST(추상 구문 트리) 상태 저장소를 이어 붙여야 합니다.
- 리팩토링 작업을 파일이나 모듈 단위의 서브 태스크 배열로 나눕니다.
- 서브 태스크가 끝날 때마다 대상 코드의 AST 구조, 의존성 상태, 실행 로그 요약을 Redis 체크포인트 키에 비동기로 넣습니다.
- 세션이 끊기면 Redis에서 마지막 성공 체크포인트를 불러옵니다. 실패 원인을 리마인더 메시지로 주입해 실패한 지점부터 다시 실행합니다.
Redis AST 상태 관리를 적용하면 멀티 파일 작업 성공률이 54.0%에서 94.5%로 올라갑니다. 터졌을 때 버려지는 토큰 비율도 100%에서 12% 수준으로 감소합니다. 월간 에이전트 API 운영 비용이 4,500달러에서 2,150달러로 줄어드는 이유입니다.
CAD와 이미지 토큰 줄이는 전처리 파이프라인
프론트엔드 UI나 엔지니어링 코드를 만들 때 2048x2048 넘는 3D CAD 스크린샷을 그대로 넣으면 토큰을 순식간에 잡아먹습니다. 단일 요청당 비전 토큰만 1,650개 이상 빠져나갑니다.
ezdxf 라이브러리로 텍스트 메타데이터를 먼저 뽑고, 이미지는 압축해서 넘기는 전처리 래퍼가 필요합니다.
- ezdxf 라이브러리로 DXF CAD 파일에서 레이어 목록, 헤더 변수, 엔티티 요약 정보만 텍스트로 추출합니다.
- 스크린샷은 Python Pillow 라이브러리로 읽어 Grayscale 흑백 채널로 바꿉니다.
- LANCZOS 필터를 써서 최대 1024px 해상도로 줄인 뒤 JPEG 품질 80으로 압축해 Opus 5 비전 입력으로 전달합니다.
from PIL import Image
import ezdxf
def preprocess_cad_and_image(dxf_path, image_path):
# 1. DXF 텍스트 메타데이터 추출
doc = ezdxf.readfile(dxf_path)
layers = [layer.dxf.name for layer in doc.layers]
meta_text = f"Layers: {', '.join(layers)}, Entities: {len(doc.modelspace())}"
# 2. 이미지 다운스케일링 및 흑백 변환
with Image.open(image_path) as img:
img = img.convert("L")
img.thumbnail((1024, 1024), Image.Resampling.LANCZOS)
img.save("processed_temp.jpg", "JPEG", quality=80)
return meta_text, "processed_temp.jpg"
이렇게 돌리면 파일당 비전 토큰 소모량이 1,650개에서 300개로 줄어듭니다. 텍스트 메타데이터 180토큰을 더해도 300달러 예산으로 처리할 수 있는 파일 수가 3.6배 늘어납니다. 응답 대기 시간도 8.4초에서 2.3초로 단축됩니다.
Tree-sitter 기반 컨텍스트 압축
수십만 라인의 코드베이스 전체를 프롬프트에 집어넣는 건 돈을 길바닥에 버리는 짓입니다. 모델의 주의력도 산만해집니다. 오픈소스 페어 프로그래밍 도구인 Aider가 리포지토리 맵을 그려 필요한 인터페이스만 뽑아 쓰는 방식이 훨씬 실용적입니다.
Tree-sitter 구문 분석기와 Personalized PageRank 알고리즘을 조합해 핵심 심볼 시그니처만 추출하는 CLI를 만들 수 있습니다.
- 로컬 환경에 Tree-sitter를 세팅하고 Git staged 변경점 파일을 감지하도록 작성합니다.
- 수정 중인 파일(Seed File)을 기준으로 클래스, 메서드, 함수 정의와 참조 구문을 찾아 프로젝트 그래프 를 생성합니다.
- 감쇠 인자() 기준 Personalized PageRank를 계산해 연관 심볼 상위 시그니처만 추려냅니다. 1,024 토큰 제한 내의 컨텍스트 맵을 만들어
.git/hooks/pre-commit에 붙입니다.
Git Pre-commit Hook에 이 과정을 물려두면 커밋이나 CI 파이프라인 실행 시 주입되는 컨텍스트 크기가 수십만 토큰에서 1,000~2,000 토큰 사이로 고정됩니다. 입력 토큰 비용이 80% 이상 깎입니다.
