codex-advisor

Codex Advisor

概要

計画やコードレビューについて外部からの検証が必要な場合や、難しい問題に行き詰まった場合に、OpenAI の Codex CLI をセカンドオピニオンを提供するアドバイザーとして使用します。このスキルでは、スクリプトや自動化での使用に向けて、非対話モード（codex exec）を使用します。

使用するタイミング

• 作業を始める前に実装計画をレビューする
• 複雑な変更やセキュリティに関わる変更をコードレビューする
• 重要なトレードオフを伴うアーキテクチャ上の決定を行う
• 30 分以上行き詰まっている問題をデバッグする
• 解決策の別のアプローチを得る
• 不慣れなコードベースについての前提を検証する

前提条件

• OpenAI API キー、または ChatGPT Plus／Pro／Business アカウント
• Codex CLI のインストール

インストール

# Via npm
npm install -g @openai/codex

# Or via Homebrew
brew install --cask codex

認証

# Option 1: API key (required for non-interactive mode in CI)
export OPENAI_API_KEY="your-key"

# Option 2: Codex-specific key for CI environments
export CODEX_API_KEY="your-key"

# Option 3: Interactive login (one-time setup)
codex --login

モデルの選択

タスクに適したモデルを選択します。

モデル	最適な用途	使用するタイミング
gpt-5.2	汎用的な推論	計画レビュー、アーキテクチャに関する質問、コーディング以外のタスクのデフォルト
gpt-5.2-codex	実環境でのソフトウェアエンジニアリング	コードレビュー、デバッグ、コーディングに特化したタスク
gpt-5.1-codex-max	長時間の複数ステップのワークフロー	長時間かかるタスク（10 分超）、大規模な移行、複雑なリファクタリング
gpt-5.1-codex-mini	コストを重視するプロジェクト	コストが重要な場合の簡単なレビュー

推奨事項：

• 一般的な質問では gpt-5.2 から始めます
• タスクがコードに特化している場合は gpt-5.2-codex を使用します
• 多数のファイルや複雑な複数ステップの作業を伴うタスクには gpt-5.1-codex-max を使用します

推論レベル

徹底的に分析するには、常に xhigh の推論を使用してください。

レベル	使用例
xhigh	デフォルト - 詳細な分析、セキュリティレビュー、アーキテクチャ上の決定
high	レイテンシが重要な場合の複雑な分析
medium	簡単なタスクへの迅速な応答
low/none	アドバイザーの用途には推奨されません

非対話モード

すべてのコマンドで、非対話実行のために codex exec を使用します。スクリプトでの使用やパイプ処理には、これが不可欠です。

主なフラグ

フラグ	目的
--json	機械処理用に JSON Lines を出力
-o <path>	最終メッセージをファイルに保存
-C <path>	作業ディレクトリを設定（現在のコードベースには -C . を使用）
--full-auto	ファイルの変更を有効化（注意して使用）
--sandbox read-only	読み取り専用のサンドボックス（デフォルトで最も安全）
--sandbox workspace-write	ワークスペース内の書き込みのみを許可

出力の処理

# JSON output for parsing
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  --json "Your prompt" 2>/dev/null

# Save to file
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  -o output.txt "Your prompt"

# Pipe input and capture output
git diff | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review this diff" > review.txt 2>/dev/null

コマンドリファレンス

計画のレビュー

実装計画へのフィードバックを得ます。

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  "Review this implementation plan. Identify potential issues, missing edge cases, security concerns, or better approaches:

<paste plan here>"

現在のコードベースに関わる計画の場合：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Review this implementation plan in the context of this codebase. Identify potential issues, conflicts with existing patterns, or better approaches:

<paste plan here>"

コードレビュー

バグ、セキュリティ上の問題、改善点を確認するために、コードの変更をレビューします。

# Review staged changes
git diff --staged | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review these changes before commit. Check for:
- Bugs or logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling"

# Review a specific diff
git diff | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review this diff for bugs, security issues, and improvements"

# Review with codebase context
codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" -C . \
  "Review src/auth/login.ts for bugs, security vulnerabilities, and suggest improvements"

難しい問題の解決

難しい問題に行き詰まった場合：

codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" -C . \
  "I'm stuck on this problem: <description>

What I've tried:
1. <attempt 1>
2. <attempt 2>

Error/behavior I'm seeing: <details>

Suggest solutions or debugging approaches."

アーキテクチャ上の決定

設計上のトレードオフについて意見を得ます。

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "I need to decide between these approaches for <feature>:

Option A: <description>
Option B: <description>

Given this codebase, which approach is better and why? Consider maintainability, performance, and consistency with existing patterns."

別のアプローチ

新たな視点がほしい場合：

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Here's my current approach to <problem>: <description>

What are alternative ways to solve this? What am I missing?"

ワークフローの例

実装前のレビュー

codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" -C . \
  "Review this implementation plan for a user authentication system:

1. Add JWT middleware to Express routes
2. Create /auth/login and /auth/register endpoints
3. Store refresh tokens in Redis
4. Add rate limiting on auth endpoints

Identify missing pieces, security concerns, or better approaches."

コミット前のレビュー

git diff --staged | codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  "Review these changes for a PR. Check for:
- Bugs or logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling
- Test coverage gaps

Provide specific line-by-line feedback."

長時間かかる移行

複雑で複数のファイルにまたがるリファクタリングには、gpt-5.1-codex-max を使用します。

codex exec -m gpt-5.1-codex-max -c model_reasoning_effort="xhigh" -C . \
  "Help me migrate this codebase from Express to Fastify.

Review the current structure and create a detailed migration plan.
Identify all files that need changes and potential breaking changes."

CI／自動化

CI 環境では、CODEX_API_KEY を使用します。

# In CI environment
CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} \
  codex exec -m gpt-5.2-codex -c model_reasoning_effort="xhigh" \
  --json "Review this code" > review.json

GitHub Actions の例

- name: Code Review with Codex
  env:
    CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
  run: |
    git diff origin/main...HEAD | codex exec \
      -m gpt-5.2-codex \
      -c model_reasoning_effort="xhigh" \
      -o review.txt \
      "Review this PR diff for bugs and security issues"

ベストプラクティス

Codex Advisor を使用するタイミング

• 複数のシステムに影響する複雑な変更
• セキュリティに関わるコード（認証、暗号、入力検証）
• パフォーマンスが重要な箇所
• 不慣れなコードベースやプログラミング言語
• 30 分以上行き詰まっている場合

使用しないタイミング

• 単純で明白な変更（誤字、書式設定）
• 解決策が明確な些細なバグ修正
• リスクの低い変更を迅速に進める必要がある場合
• 手順が確立されている反復的なタスク

より良い結果を得るためのヒント

1. コンテキストを提供する：関連するファイルパス、エラーメッセージ、これまでに試したことを含めます
2. 具体的にする：「すべてをレビューして」ではなく、焦点を絞った質問をします
3. -C .を使用する：Codex がコンテキストに応じたアドバイスを行えるよう、コードベースを確認できるようにします
4. 適切なモデルを選択する：一般的な用途にはgpt-5.2、コードにはgpt-5.2-codex、複雑な用途にはgpt-5.1-codex-maxを使用します
5. 提案を検証する：Codex の推奨事項は、必ずコードベースに照らして検証します

セキュリティに関する考慮事項

• Codex は分析のためにコードを OpenAI のサーバーに送信します
• 独自コードを共有する前に、所属組織のポリシーを確認してください
• コードサンプルに機密性の高い認証情報、API キー、個人を特定できる情報を含めないでください
• 利用状況を監視できるよう、適切なレート制限が設定された API キーを使用してください

トラブルシューティング

「stdin is not a terminal」

データをパイプで渡す場合は、必ずcodex execを使用します：

# Wrong - interactive mode doesn't support piped input
git diff | codex -m gpt-5.2 "Review this..."

# Correct - use exec for non-interactive execution
git diff | codex exec -m gpt-5.2 "Review this..."

「Command not found」

# Check installation
which codex

# Reinstall if needed
npm install -g @openai/codex

認証エラー

# Re-authenticate interactively
codex --login

# Or set API key
export OPENAI_API_KEY="your-key"
export CODEX_API_KEY="your-key"  # For CI

レート制限

大量に使用する場合は、ChatGPT 認証ではなく、適切な利用枠の API キーを使用してください。

出力がない／空の応答

stderr と stdout を個別に処理するようにしてください：

# Capture output properly
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  "Your prompt" 2>/dev/null > output.txt

# Or use -o flag
codex exec -m gpt-5.2 -c model_reasoning_effort="xhigh" \
  -o output.txt "Your prompt"