oracle — ベストプラクティス

Oracle はプロンプト + 選択したファイルを 1 つの「ワンショット」リクエストにまとめることで、別のモデルが実際のリポジトリコンテキストで回答できるようにします (API またはブラウザ自動化)。出力は参考情報として扱い、コードとテストに照らし合わせて検証してください。

メインユースケース (ブラウザ、GPT‑5.2 Pro)

デフォルトのワークフロー: ChatGPT の GPT‑5.2 Pro で --engine browser を使用します。これは一般的な「長考」パスです。約 10 分から約 1 時間は正常です。再接続可能な保存済みセッションが期待できます。

推奨デフォルト設定:

• Engine: browser (--engine browser)
• Model: GPT‑5.2 Pro (--model gpt-5.2-pro または --model "5.2 Pro")

ゴールデンパス

1. タイトなファイルセットを選択します (真実を含む最小限のファイル)。
2. ペイロードとトークン消費をプレビューします (--dry-run + --files-report)。
3. 通常の GPT‑5.2 Pro ワークフローにはブラウザモードを使用し、API は明示的に必要な場合のみ使用します。
4. 実行が切断/タイムアウトした場合: 保存済みセッションに再接続します (再実行しないでください)。

コマンド (推奨)

• ヘルプ:

  • oracle --help
  • バイナリがインストールされていない場合: npx -y @steipete/oracle --help (pnpx は使用しないこと、sqlite バインディングのため)

• プレビュー (トークン消費なし):

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

• トークン確認:

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

• ブラウザ実行 (メインパス、長時間実行は正常):

  • oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"

• 手動ペーストフォールバック:

  • oracle --render --copy -p "<task>" --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 を尊重します。
  • シンボリックリンクをフォローしません。
  • パターンで明示的にオプトインしない限りドットファイルを除外します (例: --file ".github/**")。
  • 1 MB を超えるファイルは拒否します。

エンジン (API 対 ブラウザ)

• 自動選択: OPENAI_API_KEY が設定されている場合は api、そうでない場合は browser。
• ブラウザは GPT と Gemini のみをサポートしており、Claude/Grok/Codex またはマルチモデル実行には --engine api を使用します。
• ブラウザ添付:
  • --browser-attachments auto|never|always (約 60k 文字までインライン貼り付け、その後アップロード)。
• リモートブラウザホスト:
  • ホスト: oracle serve --host 0.0.0.0 --port 9473 --token <secret>
  • クライアント: oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"

セッション + スラッグ

• ~/.oracle/sessions に保存されます (ORACLE_HOME_DIR でオーバーライド可能)。
• 実行は切断されるか長時間かかる場合があります (ブラウザ + GPT‑5.2 Pro では頻繁に発生)。CLI がタイムアウトした場合: 再実行せず、再接続してください。
  • リスト: oracle status --hours 72
  • 接続: oracle session <id> --render
• --slug "<3-5 words>" を使用してセッション ID を読みやすくします。
• 重複プロンプトガードが存在します。本当に新規実行が必要な場合のみ --force を使用します。

プロンプトテンプレート (高シグナル)

Oracle はプロジェクト知識がゼロから始まります。モデルがスタック、ビルドツーリング、規約、または「明白な」パスを推論できないと想定してください。以下を含めます:

• プロジェクト概要 (スタック + ビルド/テストコマンド + プラットフォーム制約)。
• 「ものがどこにあるか」 (主要ディレクトリ、エントリポイント、設定ファイル、境界)。
• 正確な質問 + 試したこと + エラーテキスト (そのまま)。
• 制約 (「X を変更しないこと」、「公開 API を保持しなければならない」など)。
• 期待される出力 (「パッチプランとテストを返す」、「トレードオフ付きの 3 つのオプションを提供する」など)。

セキュリティ

• デフォルトではシークレットを添付しないでください (.env、キーファイル、認証トークン)。積極的に編集します。必要なもののみ共有してください。

「詳細なプロンプト」復元パターン

長時間の調査の場合、スタンドアロンプロンプト + ファイルセットを書いて、後で再実行できるようにします:

• 6～30 文のプロジェクト概要 + 目標。
• 再現手順 + 正確なエラー + 試したこと。
• 必要なすべてのコンテキストファイルを添付します (エントリポイント、設定、主要モジュール、ドキュメント)。

Oracle 実行はワンショットです。モデルは以前の実行を覚えていません。「コンテキストの復元」は、同じプロンプト + --file … セットで再実行することを意味します (または、まだ実行中の保存済みセッションに再接続)。