oracle

oracle

oracle は、2回目のモデル実行用にプロンプトと選択したファイルをまとめます。出力は参考情報として扱い、コードとテストに照らして検証してください。

主な使用方法

現在の CLI のデフォルトモデルは gpt-5.5-pro です。ブラウザーエンジンは ChatGPT Pro で長時間実行する場合に便利です。OPENAI_API_KEY または Azure の設定が済んでいる場合は、API エンジンが便利です。

推奨されるデフォルト設定：

• まずプレビュー：--dry-run summary --files-report
• ブラウザーで長時間実行：--engine browser --model gpt-5.5-pro
• API を明示して実行：--engine api --model gpt-5.5

基本的な手順

1. ファイルを絞り込みます（真実が記載されているファイルだけを選び、数を最小限にします）。
2. ペイロードとトークン消費量をプレビューします（--dry-run と --files-report）。
3. Pro でじっくり考えさせる場合はブラウザーモードを、API を明示的に呼び出す場合は API モードを使います。
4. 実行が切断またはタイムアウトした場合は、保存済みのセッションに再接続します。むやみに再実行しないでください。

コマンド（推奨）

• ヘルプ：

  • oracle --help
  • バイナリがインストールされていない場合：npx -y @steipete/oracle --help（sqlite バインディングのため、ここでは pnpx を使わないでください）。

• プレビュー（トークンを消費しません）：

  • 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.5-pro -p "<task>" --file "src/**"

• 手動で貼り付ける場合の代替手段：

  • oracle --render --copy -p "<task>" --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 を尊重します。
  • シンボリックリンクはたどりません。
  • パターンで明示的に指定しない限り、ドットファイルは除外されます（例：--file ".github/**"）。
  • 1 MB を超えるファイルは拒否されます。

エンジン（API とブラウザー）

• 自動選択：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 <secret>
  • クライアント：oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"

セッションとスラッグ

• ~/.oracle/sessions に保存されます（ORACLE_HOME_DIR で変更できます）。
• 実行は切断されたり、長時間かかったりすることがあります（ブラウザーと 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 … のファイル一式で再実行すること（または、まだ実行中の保存済みセッションを再度添付すること）を意味します。