Community코딩 & 개발github.com

steipete/oracle

Oracle 두 번째 모델 리뷰: 프롬프트/파일 번들링, 디버그, 리팩터링, 설계.

oracle란 무엇인가요?

Oracle은 개발자와 AI 에이전트 사용자를 위해 설계된 CLI 도구로, 프롬프트와 선택한 파일을 하나의 '원샷(one-shot)' 요청으로 번들링하여 다른 모델(GPT-5.5 Pro 등)이 실제 저장소 컨텍스트를 바탕으로 답변할 수 있게 합니다. ChatGPT와 브라우저 기반 워크플로를 기본으로 하며, API 사용도 지원하지만 비용이 발생하므로 명시적인 동의가 필요합니다. `--file` 옵션으로 파일, 디렉토리, 글로브(glob) 패턴을 포함하거나 제외할 수 있으며, `.gitignore`를 존중하고 기본적으로 큰 파일과 도트 파일을 필터링합니다. 세션 관리를 통해 장기 실행 작업이 분리되거나 타임아웃되어도 다시 연결할 수 있으며, 성능 추적(`--perf-trace`), 토큰 예산 확인(`--files-report`, `--dry-run`), 그리고 프롬프트 템플릿 가이드를 제공하여 효율적인 사용을 돕습니다. 주 사용 사례는 두 번째 모델 리뷰, 디버깅, 리팩터링, 설계 자문이며, 출력은 참고용으로 간주하고 코드베이스와 테스트를 통해 검증해야 합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/oracle

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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")
  • 첨부 파일: 디렉토리/글로브 + 제외 패턴; 비밀 정보는 피하세요.

최적 경로 (빠르고 안정적)

  1. 좁은 파일 세트를 선택하세요(진실이 포함된 최소 파일).
  2. 보낼 내용을 미리 확인하세요(필요 시 --dry-run + --files-report).
  3. 일반적인 GPT‑5.5 Pro ChatGPT 워크플로를 위해 브라우저 모드로 실행하고, 명시적으로 원할 때만 API를 사용하세요.
  4. 실행이 분리/타임아웃되면: 저장된 세션에 다시 연결하고(재실행하지 마세요).

명령어 (권장)

  • 도움말 보기 (세션당 한 번):

    • 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-pro
    • oracle --preflight --models gpt-5.4,gemini-3-pro
    • oracle --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 build
    • node ~/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, 키 파일, 인증 토큰). 적극적으로 삭제하고 필요한 것만 공유하세요.
  • "충분한 컨텍스트"를 선호하세요: 더 적은 파일 + 더 나은 프롬프트가 전체 저장소 덤프보다 낫습니다.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

관련 스킬