codex-plan

Codex Plan Skill

Codex を使用して、詳細な実装計画を作成するよう依頼されています。あなたの役割は次のとおりです。

1. ユーザーの計画依頼（以下の ARGUMENTS: に表示）を理解する
2. AskUserQuestion を使用して、確認の質問をする
3. Codex 向けの優れた詳細なプロンプトを作成する
4. Codex を実行して計画を生成し、保存する

常に使用するもの： gpt-5.4 と xhigh の推論 出力： 現在のディレクトリにある codex-plan.md

---

Step 1: 依頼を分析する

ユーザーの計画依頼は、この指示の末尾に ARGUMENTS: <request> として記載されています。

以下を特定します。

• 中心となる目標は何ですか？
• どの技術や分野が関係していますか？
• どの点が曖昧、または詳細不足ですか？
• 計画に大きく影響する判断事項は何ですか？

Fast-path（単純なタスク）

タスクが非常に単純な場合（単一ファイルの設定変更、誤字の修正、影響するファイルが 2 つ未満で、アーキテクチャ上の判断が不要な場合）は、Codex をスキップします。簡略化した構成で codex-plan.md を直接作成します。

# Plan: [Task Name]
**Generated**: [Date]
**Estimated Complexity**: Low
## Overview
[1-2 sentences]
## Task
- **Location**: [file path]
- **Description**: [what to do]
- **Acceptance Criteria**: [testable criteria]

Fast-path の場合でも、計画を作成する前に、Step 2 で少なくとも 1 つの確認質問をする必要があります。作成後は Step 6（出力を検証する）に進みます。

---

Step 2: 確認の質問をする（必須）

計画を生成する前に、AskUserQuestion ツールを使用して、対象を絞った質問を 1～5 個します。

まず、タスクの曖昧さを評価します。

• 単純で明確なタスク（範囲が明確で、明白な進め方がある）→ 質問は 1～2 個
• 複雑で曖昧なタスク（複数の進め方があり、要件が不明確）→ 質問は 3～5 個
• 0 個は不可 — 理解を確認するため、必ず少なくとも 1 つ質問します

確認の質問の例：

• 範囲と要件を絞り込む
• 技術の選択を明確にする
• 制約（時間、予算、チームの規模）を把握する
• 必須事項と、あれば望ましい事項を特定する
• 統合要件を明らかにする
• セキュリティやコンプライアンスの要件を確認する

質問の例

「認証を実装する」の場合：

• どの認証方式を使いますか？（メールアドレス／パスワード、OAuth、SSO、マジックリンク）
• RBAC が必要ですか、それとも認証済み／未認証の区別だけでよいですか？
• バックエンドのスタックは何ですか？（Node／Express、Python／Django など）
• セッションの保存先はどこですか？（データベース、Redis、ステートレスな JWT）
• 必要な機能は何ですか？（パスワードのリセット、メール認証、2FA）
• コンプライアンス要件はありますか？（SOC2、GDPR、HIPAA）

「API を構築する」の場合：

• 管理するリソース／エンティティは何ですか？
• REST と GraphQL のどちらを使いますか？
• 認証方式は何ですか？
• 想定される規模やトラフィックはどの程度ですか？
• レート制限、キャッシュ、バージョニングは必要ですか？

「バグを修正する」の場合：

• 安定して再現する方法は何ですか？（手順、環境、発生頻度）
• 期待する動作と実際の動作は何ですか？
• 関連するテストカバレッジはありますか？（既存のテストで検出できるべきだったもの）
• 影響を受けるプラットフォーム／ブラウザー／環境は何ですか？

「リファクタリング」の場合：

• 外部 API／インターフェースとの互換性を維持する必要がありますか？
• 依拠できる既存のテストカバレッジはありますか？
• パフォーマンス上の制約はありますか？（劣化を許容できないなど）
• 段階的に進めますか、それとも一括で進めますか？（部分的な進捗をマージできますか？）

「インフラ／DevOps」の場合：

• 対象環境はどこですか？（ローカル、ステージング、本番）
• 既存の CI/CD パイプラインはありますか？
• シークレットの管理方法はどうしますか？
• ロールバック要件はありますか？（ブルーグリーン、カナリア、即時）

---

Step 3: 対象ファイルを特定する

あなたはプロダクトマネージャー兼ファイル特定担当です。 実装を計画するのではなく、関連ファイルを見つけることが役割です。

回答を得た後、以下を調べます。

• エントリーポイント：メインファイル、CLI エントリー、ルートハンドラー
• 変更対象ファイル：タスクで変更する具体的なファイル
• 主要なインポート／依存関係：これらのファイルが依存するモジュール
• 既存のパターン：命名規則、エラー処理のスタイル、アーキテクチャ

Codex プロンプトに ## Target Files のリストを作成します。

## Target Files to Read
- `src/auth/login.ts` — current login handler, will be modified
- `src/middleware/session.ts` — session middleware, imports from login
- `src/types/user.ts` — User type definition, dependency

ファイルの内容を要約しないでください — 用途を 1 行で示して、パスだけを列挙します。Codex が <context_loading> を通じて全文を読み込みます。

---

Step 4: Codex プロンプトを作成する

以下を含む詳細なプロンプトを作成します。

1. 明確な目的 — 作成する必要がある計画
2. すべての要件 — 確認の質問で判明した内容
3. 制約 — 技術の選択、期間、チームの規模
4. 対象ファイル — Step 3 のファイルパス一覧
5. 計画の構成 — references/plan-template.md を読み込み、内容全体を挿入する
6. 出力の指示 — 現在のディレクトリに codex-plan.md を書き込む

重要： Codex に確認の質問をしないよう伝えてください。必要な情報はすべてそろっているため、計画を作成してファイルに保存するだけでよいと伝えます。

状況に応じたテンプレート： 小規模または単純なタスクの場合は、<output_verbosity_spec> に従うため、関係のないセクション（フェーズ、E2E テスト、ロールバック）を必ず省略し、代わりにフラットなタスクリストを出力してもよいと Codex に伝えてください。

Codex プロンプトの例

Create a detailed implementation plan for [TASK DESCRIPTION].

## Requirements
- [Requirement 1 from clarifying questions]
- [Requirement 2]
- [Requirement 3]
- NOT needed: [Things explicitly excluded]

## Target Files to Read
- `[path/to/file1]` — [one-line purpose]
- `[path/to/file2]` — [one-line purpose]
- `[path/to/file3]` — [one-line purpose]

## Plan Structure

Read and follow the exact template structure from `references/plan-template.md`.

Adapt the template to task complexity:
- For minor tasks, OMIT irrelevant sections (e.g., multiple Phases, E2E Tests, Rollback) and use a flat task list instead.
- For complex tasks, use the full phased structure with all sections.

## Behavioral Constraints

<output_verbosity_spec>
- Default: 3-6 sentences or <=5 bullets for typical answers.
- Simple yes/no questions: <=2 sentences.
- Complex multi-step or multi-file tasks:
  - 1 short overview paragraph
  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
- Avoid long narrative paragraphs; prefer compact bullets and short sections.
- Do not rephrase the user's request unless it changes semantics.
</output_verbosity_spec>

<design_and_scope_constraints>
- Implement EXACTLY and ONLY what the user requests.
- No extra features, no added components, no UX embellishments.
- Style aligned to the design system at hand.
- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless requested or necessary.
- If any instruction is ambiguous, choose the simplest valid interpretation.
</design_and_scope_constraints>

<context_loading>
- Start by reading ALL files listed in "Target Files to Read" — in full, not just the sections mentioned in the task.
- Then expand to key files they import from or that depend on them.
- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
- Do not ask clarifying questions about things that are answerable by reading the codebase.
</context_loading>

## Instructions
- Write the complete plan to a file called `codex-plan.md` in the current directory
- Do NOT ask any clarifying questions - you have all the information needed
- Be specific and actionable - include code snippets where helpful
- Follow test-driven development: specify what tests to write BEFORE implementation
- Identify task dependencies so parallel work is possible
- Just write the plan and save the file

Begin immediately.

---

Step 5: Codex を実行する（必須）

作成したプロンプトを使って、次のコマンドをそのまま実行します。

codex exec --full-auto --skip-git-repo-check \
  -c model=gpt-5.4 \
  -c model_reasoning_effort=xhigh \
  -c model_reasoning_summary=concise \
  --output-last-message /tmp/codex-plan-result.txt \
  "YOUR_CRAFTED_PROMPT_HERE"

次に、結果を表示します。

cat /tmp/codex-plan-result.txt

---

Step 6: 出力を検証する（必須）

Codex の完了後（またはファストパスで自分で計画を書いた後）、次の手順を実行します。

1. 生成された codex-plan.md を読み取る
2. 構成を確認する：ファイルが存在し、有効な Markdown であり、少なくとも以下を含んでいることを確認します。
   • # Plan: 見出し
   • ## Overview セクション
   • 1 つ以上の ### Task エントリ
3. チェックに失敗した場合、または codex exec がエラー／タイムアウトを返した場合：
   • プロンプトを調整する（要件を簡略化し、曖昧さを解消する）
   • 実行を1 回だけ再試行する
4. 再試行にも失敗した場合：エラーをユーザーに示し、問題の原因を説明する
5. チェックに合格した場合：計画の結果をユーザーに示す

---

重要なルール

1. 必ず 1 つ以上の確認質問をする — Step 2 を省略しないでください（複雑さに応じて 1～5 個の質問）
2. 必ず gpt-5.4 を xhigh reasoning で使用する — 例外なし（ファストパスを除く）
3. 必ず Codex に質問をしないよう伝える — そのまま実行させてください
4. 必ず --full-auto フラグを使用する
5. 必ず Step 6 で出力を検証する — 構成を確認し、失敗した場合は 1 回再試行する
6. 出力ファイル：現在の作業ディレクトリにある codex-plan.md

---

それでは実行

ユーザーの計画作成リクエストは、以下の ARGUMENTS: に示されています。内容を分析し、Step 1 から始めてください。