oracle

oracle은(는) 무엇을 하나요?

Oracle은 프롬프트 + 선택된 파일을 하나로 묶어 두 번째 모델 패스(second-model pass)를 실행합니다. 출력은 참고용으로 취급하고 코드와 테스트를 통해 검증하세요.

주요 경로

현재 CLI 기본 모델: gpt-5.5-pro. 브라우저 엔진은 긴 ChatGPT Pro 실행에 유용하며, API 엔진은 OPENAI_API_KEY 또는 Azure 구성이 준비된 경우 유용합니다.

권장 기본값:

• 먼저 미리보기: --dry-run summary --files-report
• 브라우저 장기 실행: --engine browser --model gpt-5.5-pro
• API 명시적 호출: --engine api --model gpt-5.5

골든 패스 (Golden path)

1. 파일 집합을 최대한 좁게 선택하세요 (진실이 포함된 최소 파일).
2. 페이로드와 토큰 사용량을 미리 확인하세요 (--dry-run + --files-report).
3. Pro 모드의 장기 사고(long thinking)에는 브라우저 모드를, 명시적 API 호출에는 API 모드를 사용하세요.
4. 실행이 분리/타임아웃되면: 저장된 세션에 재연결하세요. 무턱대고 다시 실행하지 마세요.

명령어 (선호)

• 도움말:

  • oracle --help
  • 바이너리가 설치되지 않은 경우: npx -y @steipete/oracle --help (pnpx는 사용하지 마세요; sqlite 바인딩 문제).

• 미리보기 (토큰 소모 없음):

  • oracle --dry-run summary -p "<작업>" --file "src/**" --file "!**/*.test.*"
  • oracle --dry-run full -p "<작업>" --file "src/**"

• 토큰 확인:

  • oracle --dry-run summary --files-report -p "<작업>" --file "src/**"

• 브라우저 실행 (주 경로; 장기 실행 정상):

  • oracle --engine browser --model gpt-5.5-pro -p "<작업>" --file "src/**"

• 수동 붙여넣기 대체:

  • oracle --render --copy -p "<작업>" --file "src/**"
  • 참고: --copy는 --copy-markdown의 숨은 별칭입니다.

파일 첨부 (--file)

--file은 파일, 디렉터리, glob 패턴을 허용합니다. 여러 번 전달할 수 있으며, 쉼표로 구분된 항목도 가능합니다.

• 포함:

  • --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 (명시적으로 디렉터리/파일로 전달되지 않으면 건너뜀).
  • glob 확장 시 .gitignore를 준수합니다.
  • 심볼릭 링크를 따르지 않습니다.
  • 패턴을 사용하여 명시적으로 선택하지 않는 한 점 파일(dotfiles)은 필터링됩니다 (예: --file ".github/**").
  • 1MB를 초과하는 파일은 거부됩니다.

엔진 (API vs 브라우저)

• 자동 선택: OPENAI_API_KEY가 설정된 경우 api, 그렇지 않으면 browser.
• 브라우저는 GPT + Gemini만 지원합니다. Claude/Grok/Codex 또는 다중 모델 실행에는 --engine api를 사용하세요.
• 브라우저 첨부 파일:
  • --browser-attachments auto|never|always (auto는 약 60k 문자까지 인라인으로 붙여넣은 후 업로드).
• 원격 브라우저 호스트:
  • 서버: oracle serve --host 0.0.0.0 --port 9473 --token <비밀>
  • 클라이언트: oracle --engine browser --remote-host <호스트:포트> --remote-token <비밀> -p "<작업>" --file "src/**"

세션 + 슬러그 (slug)

• ~/.oracle/sessions에 저장됩니다 (ORACLE_HOME_DIR로 재정의 가능).
• 실행이 분리되거나 오래 걸릴 수 있습니다 (브라우저 + Pro의 경우 자주 발생). CLI가 타임아웃되면: 다시 실행하지 말고 재연결하세요.
  • 목록: oracle status --hours 72
  • 연결: oracle session <ID> --render
• 세션 ID를 읽기 쉽게 유지하려면 --slug "<3-5 단어>"를 사용하세요.
• 중복 프롬프트 방지 기능이 있습니다. 정말로 새로 실행하려는 경우에만 --force를 사용하세요.

프롬프트 템플릿 (고신호, high signal)

Oracle은 제로 프로젝트 지식으로 시작합니다. 모델이 스택, 빌드 도구, 규칙 또는 "당연한" 경로를 추론할 수 없다고 가정하세요. 다음을 포함하세요:

• 프로젝트 브리핑 (스택 + 빌드/테스트 명령어 + 플랫폼 제약).
• "어디에 무엇이 있는지" (주요 디렉터리, 진입점, 구성 파일, 경계).
• 정확한 질문 + 시도한 내용 + 오류 텍스트 (그대로).
• 제약 조건 ("X를 변경하지 마세요", "공개 API 유지 필수" 등).
• 원하는 출력 ("패치 계획 + 테스트 반환", "절충점과 함께 3가지 옵션 제시").

첨부 파일

• 사용자가 요청하지 않는 한 .env, 키 파일, 인증 토큰을 첨부 파일에 포함시키지 마세요.

"철저한 프롬프트" 복원 패턴

장기 조사의 경우 독립적인 프롬프트 + 파일 집합을 작성하여 며칠 후에도 다시 실행할 수 있도록 하세요:

• 6~30 문장의 프로젝트 브리핑 + 목표.
• 재현 단계 + 정확한 오류 + 시도한 내용.
• 필요한 모든 컨텍스트 파일 첨부 (진입점, 구성, 주요 모듈, 문서).

Oracle 실행은 일회성(one-shot)입니다. 모델은 이전 실행을 기억하지 않습니다. "컨텍스트 복원"은 동일한 프롬프트 + --file ... 집합으로 다시 실행하거나 (또는 아직 실행 중인 저장된 세션에 재연결하는 것)을 의미합니다.