Oracle (CLI) — 최적의 사용법
Oracle은 프롬프트 + 선택한 파일을 하나의 "원샷" 요청으로 번들링하여 다른 모델이 실제 저장소 컨텍스트를 갖고 답변할 수 있도록 합니다(API 또는 브라우저 자동화). 출력은 참고용으로 처리하고, 코드베이스 및 테스트와 대조하여 검증하세요.
주요 사용 사례 (브라우저, GPT‑5.5 Pro)
여기서의 기본 워크플로: --engine browser와 함께 ChatGPT의 GPT‑5.5 Pro 사용. 이것은 "인간 개입" 경로입니다. 약 10분에서 1시간까지 걸릴 수 있으며, 다시 연결할 수 있는 저장된 세션이 생성됩니다.
권장 기본값:
- 엔진: browser (
--engine browser) - 모델: GPT‑5.5 Pro (
--model gpt-5.5-pro또는 ChatGPT 선택기 레이블--model "5.5 Pro") - 첨부 파일: 디렉토리/글로브 + 제외 패턴; 비밀 정보는 피하세요.
최적 경로 (빠르고 안정적)
- 좁은 파일 세트를 선택하세요(진실이 포함된 최소 파일).
- 보낼 내용을 미리 확인하세요(필요 시
--dry-run+--files-report). - 일반적인 GPT‑5.5 Pro ChatGPT 워크플로를 위해 브라우저 모드로 실행하고, 명시적으로 원할 때만 API를 사용하세요.
- 실행이 분리/타임아웃되면: 저장된 세션에 다시 연결하고(재실행하지 마세요).
명령어 (권장)
-
도움말 보기 (세션당 한 번):
npx -y @steipete/oracle --help
-
미리보기 (토큰 소모 없음):
npx -y @steipete/oracle --dry-run summary -p "<작업>" --file "src/**" --file "!**/*.test.*"npx -y @steipete/oracle --dry-run full -p "<작업>" --file "src/**"
-
토큰/비용 확인:
npx -y @steipete/oracle --dry-run summary --files-report -p "<작업>" --file "src/**"
-
시작/성능 추적:
npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<작업>" --file "src/**"- CLI 시작 또는 첫 출력까지 시간이 느리게 느껴질 때 사용;
first-output과exit을 검사하세요.
-
브라우저 실행 (주 경로, 장시간 실행 정상):
npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<작업>" --file "src/**"
-
수동 붙여넣기 대체 (번들 생성, 클립보드에 복사):
npx -y @steipete/oracle --render --copy -p "<작업>" --file "src/**"- 참고:
--copy는--copy-markdown의 숨은 별칭입니다.
파일 첨부 (--file)
--file은 파일, 디렉토리, 글로브를 허용합니다. 여러 번 전달할 수 있으며, 항목은 쉼표로 구분할 수 있습니다.
-
포함:
--file "src/**"(디렉토리 글로브)--file src/index.ts(리터럴 파일)--file docs --file README.md(리터럴 디렉토리 + 파일)
-
제외 (
!접두사):--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"
-
기본값 (구현의 중요한 동작):
- 기본 무시 디렉토리:
node_modules,dist,coverage,.git,.turbo,.next,build,tmp(명시적으로 리터럴 디렉토리/파일로 전달하지 않으면 건너뜀). - 글로브 확장 시
.gitignore를 준수합니다. - 심볼릭 링크를 따르지 않습니다 (글로브 확장이
followSymbolicLinks: false사용). - 도트 파일은 명시적으로 도트 세그먼트를 포함하는 패턴(예:
--file ".github/**")으로 옵트인하지 않는 한 필터링됩니다. - 기본 제한:
ORACLE_MAX_FILE_SIZE_BYTES또는~/.oracle/config.json의maxFileSizeBytes를 높이지 않으면 1MB를 초과하는 파일은 거부됩니다.
- 기본 무시 디렉토리:
예산 및 관찰 가능성
- 목표: 총 입력을 약 196k 토큰 미만으로 유지.
- 지출 전에 토큰 다량 소모 파일을 찾으려면
--files-report(및/또는--dry-run json)를 사용하세요. - 시작 및 첫 출력 타이밍을 위해
--perf-trace/ORACLE_PERF_TRACE=1을 사용하세요. 추적은 프롬프트, 토큰, 키, 쿠키 및 인라인 쿠키 페이로드를 삭제합니다. 분리된 API 자식 프로세스는 세션 접미사가 붙은 사이드카 추적 파일을 작성합니다. - 숨겨진/고급 설정이 필요하면:
npx -y @steipete/oracle --help --verbose.
엔진 (API vs 브라우저)
- 자동 선택:
OPENAI_API_KEY가 설정되면api를 사용하고, 그렇지 않으면browser를 사용합니다. - 브라우저 엔진은 GPT + Gemini만 지원합니다. Claude/Grok/Codex 또는 다중 모델 실행에는
--engine api를 사용하세요. - API 실행은 사용 비용이 발생하므로 시작하기 전에 명시적인 사용자 동의가 필요합니다.
- 브라우저 첨부 파일:
--browser-attachments auto|never|always(auto는 최대 약 60k 문자까지 인라인으로 붙여넣은 후 업로드).--browser-bundle-files --browser-bundle-format zip을 추가하여 여러 텍스트 파일을 파일 이름을 유지하면서 하나의 ZIP으로 업로드합니다.
- 원격 브라우저 호스트 (로그인된 머신이 자동화를 실행):
- 호스트:
oracle serve --host 0.0.0.0 --port 9473 --token <secret> - 클라이언트:
oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<작업>" --file "src/**"
- 호스트:
API 사전 점검
- API 실행은 명시적인 사용자 동의가 필요하며 비용이 발생합니다.
- API 실행 전에 비밀 정보를 출력하지 않고 공급자 준비 상태를 확인하세요:
oracle doctor --providers --models gpt-5.4,claude-4.6-sonnet,gemini-3-prooracle --preflight --models gpt-5.4,gemini-3-prooracle --route --model gpt-5.4
- 사용자가 자사 OpenAI를 원하면
--provider openai또는--no-azure를 전달하세요. 이렇게 하면 내보낸 Azure 환경/설정이 경로를 가로채는 것을 방지합니다:oracle --provider openai --engine api --model gpt-5.5-pro ...
- 부분 성공이 유용한 다중 모델 패널의 경우
--allow-partial --write-output <path>를 사용하여 성공적인 모델 파일과<stem>.oracle.json매니페스트를 쉽게 복구할 수 있습니다:oracle --models gpt-5.4,claude-4.6-sonnet,gemini-3-pro --allow-partial --write-output /tmp/panel.md -p "<작업>"
--timeout 10m은 일반적인 사용자 대상 API 제한 시간입니다. Oracle은--http-timeout이 명시적으로 설정되지 않은 한 HTTP 전송 제한 시간을 파생합니다.- 내보낸
OPENAI_API_KEY가 유효하지 않고 사용자가 자신의 개인 OpenAI 키를 원하는 경우, 하나의 지속적인 tmux 세션에서$one-password를 사용하세요. 알려진 항목:API Key - OpenAI - Personal, 필드api_key. 단일 Oracle 명령에만 주입하고 키를 절대 출력하지 마세요:OPENAI_API_KEY="$(op item get 'API Key - OpenAI - Personal' --account my.1password.com --fields label=api_key --reveal)" oracle --provider openai --engine api --model gpt-5.5-pro ...
- Oracle 자체를 디버깅하려면
~/Projects/oracle을 풀(pull)한 후 로컬 체크아웃을 선호하세요:pnpm -C ~/Projects/oracle run buildnode ~/Projects/oracle/dist/scripts/run-cli.js ...
세션 및 슬러그 (작업 손실 방지)
~/.oracle/sessions아래에 저장됩니다 (ORACLE_HOME_DIR로 재정의 가능).- 브라우저 실행은
~/.oracle/sessions/<id>/artifacts/아래에transcript.md, Deep Research 보고서, 사용 가능한 경우 다운로드된 ChatGPT 생성 이미지를 포함한 지속적인 파일을 저장합니다. - 실행이 분리되거나 오래 걸릴 수 있습니다(브라우저/API + GPT‑5.5 Pro는 종종 그렇습니다). CLI가 타임아웃되면: 재실행하지 말고, 다시 연결하세요.
- 목록:
oracle status --hours 72 - 연결:
oracle session <id> --render
- 목록:
--slug "<3-5 단어>"를 사용하여 세션 ID를 읽기 쉽게 유지하세요.- 중복 프롬프트 방지 기능이 있습니다. 진정으로 새로운 실행을 원할 때만
--force를 사용하세요. - CLI 안전장치: 프롬프트 없이 root로 실행하면 0이 아닌 종료 코드;
--dry-run은--render/--render-markdown과 충돌; Ctrl-C는 브라우저 정리/재연결이 계속 실행되는 동안 포그라운드 API 실행을 코드 130으로 종료합니다.
프롬프트 템플릿 (고신호)
Oracle은 제로 프로젝트 지식으로 시작합니다. 모델이 스택, 빌드 도구, 규칙 또는 "명백한" 경로를 추론할 수 없다고 가정하세요. 다음을 포함하세요:
- 프로젝트 브리핑 (스택 + 빌드/테스트 명령 + 플랫폼 제약).
- "중요한 파일 위치" (키 디렉토리, 진입점, 설정 파일, 종속성 경계).
- 정확한 질문 + 시도한 내용 + 오류 텍스트 (있는 그대로).
- 제약 사항 ("X를 변경하지 마세요", "공개 API 유지", "성능 예산" 등).
- 원하는 출력 ("패치 계획 + 테스트 반환", "위험한 가정 목록", "절충점이 있는 3가지 옵션 제시").
"철저한 프롬프트" 패턴 (나중에 복원용)
이것이 긴 조사가 될 것임을 알 때, 나중에 독립적으로 사용할 수 있는 프롬프트를 작성하세요:
- 상단: 6–30 문장의 프로젝트 브리핑 + 현재 목표.
- 중간: 구체적인 재현 단계 + 정확한 오류 + 이미 시도한 내용.
- 하단: 새로운 모델이 완전히 이해할 수 있도록 모든 필요한 컨텍스트 파일을 첨부하세요 (진입점, 설정, 키 모듈, 문서).
동일한 컨텍스트를 나중에 재현해야 한다면, 동일한 프롬프트 + --file … 세트로 다시 실행하세요 (Oracle 실행은 일회성입니다; 모델은 이전 실행을 기억하지 않습니다).
안전
- 기본적으로 비밀 정보를 첨부하지 마세요 (
.env, 키 파일, 인증 토큰). 적극적으로 삭제하고 필요한 것만 공유하세요. - "충분한 컨텍스트"를 선호하세요: 더 적은 파일 + 더 나은 프롬프트가 전체 저장소 덤프보다 낫습니다.