plan-review

Plan Review Skill

目的

ユーザーが /plan-review {plan-file-path} を実行すると、「敵対的プラン反復」ワークフローを開始します。

1. 私（Claude Code）が Codex に指定されたプランを批判的にレビューするよう依頼します。
2. Codex が作成したレビューを読み、提案が妥当かどうかを評価します。
3. 妥当な提案に基づいてプランを修正し、変更を元のプランファイルに書き戻します。
4. レビューのステータスが NEEDS_REVISION の場合、Codex に自動的に再レビューを依頼します。
5. MOSTLY_GOOD または APPROVED で合意に達するまで繰り返します。

使用方法

/plan-review plans/my-feature-plan.md

セッションの再利用

Codex の呼び出しごとに、スクリプトの出力から session_id=xxx を抽出し、現在のタスクのセッション ID として保存します。同じタスクで後から Codex を呼び出す際は、--session <id> を渡してコンテキストを再利用します。これにより、Codex は以前のレビュー履歴を記憶し、複数回にわたって一貫性を保てます。

私のワークフロー（Claude Code）

ステップ 1：レビューファイルを特定する

プランファイル名からレビューファイルのパスを導き出します。

• plans/auth-refactor.md → reviews/auth-refactor-review.md
• ルール：reviews/{.md を除いたプランファイル名}-review.md

レビューファイルがすでに存在する場合、これは初回ではないため、Codex は前回の問題の解決状況を追跡する必要があります。

ステップ 2：Codex にプランのレビューを依頼する

/codex スキルを使い、次の指示を Codex に渡します。

Read the contents of {plan-file-path} and review it critically as an independent third-party reviewer.

Requirements:
- Raise at least 10 concrete and actionable improvement points
- Each issue must include: issue description + exact location/reference in the plan + improvement suggestion
- Use severity levels: Critical > High > Medium > Low > Suggestion
- If {review-file-path} already exists, read it first and track the resolution status of previous issues in the new round

Analysis dimensions, choosing the relevant ones based on the plan type:
- Architectural soundness: overdesign vs underdesign, module boundaries, single responsibility
- Technology choices: rationale, alternatives, compatibility with the existing project stack
- Completeness: missing scenarios, overlooked edge cases, dependency and impact scope
- Feasibility: implementation complexity, performance risks, migration and compatibility concerns
- Engineering quality: whether it follows the Code Quality Hard Limits in `CLAUDE.md`
- User experience: interaction flow, error/loading states, i18n when relevant
- Security: authentication, authorization, data validation when relevant

Append the current review round to {review-file-path}, creating the file if it does not exist.
Separate rounds with `---` and append new rounds at the end of the file. Use this format:

---

## Round {N} — {YYYY-MM-DD}

### Overall Assessment
{2-3 sentence overall assessment}
**Rating**: {X}/10

### Previous Round Tracking (R2+ only)
| # | Issue | Status | Notes |
|---|-------|--------|-------|

### Issues
#### Issue 1 ({severity}): {title}
**Location**: {location in the plan}
{issue description}
**Suggestion**: {improvement suggestion}
... (at least 10 issues)

### Positive Aspects
- ...

### Summary
{Top 3 key issues}
**Consensus Status**: NEEDS_REVISION / MOSTLY_GOOD / APPROVED

Key principle: be a critical reviewer, not a yes-man. Every issue must be specific enough that someone knows how to revise the plan.

レビューファイルを初めて作成する際は、先頭に次のヘッダーを追加します。

# Plan Review: {plan title}

**Plan File**: {plan-file-path}
**Reviewer**: Codex

ステップ 3：レビューを読んでプランを修正する

Codex の処理が完了したら、レビューファイルにある最新のレビューラウンドを読みます。

1. Codex が指摘した各問題を一つずつ評価します。
2. 妥当な提案を採用し、プランファイルを修正します。
3. 妥当でない提案を却下する場合は、必要に応じてプランに理由を簡潔に記載します。
4. 新しいファイルを作成するのではなく、元のプランファイルを直接更新します。

ステップ 4：反復を続けるかどうかを決定する

Codex が提示する Consensus Status を使用します。

ステータス	対応
NEEDS_REVISION	プランを修正し、Codex に自動的に再レビューを依頼して、ステップ 2 に戻ります
MOSTLY_GOOD	プランを修正し、プランはおおむね成熟したことをユーザーに伝え、レビューをもう一度行う必要があるか尋ねます
APPROVED	プランがレビューに合格し、実装の準備ができたことをユーザーに伝えます

ステップ 5：完了する

反復が完了したら、次の内容をユーザーに報告します。

• 完了したレビューラウンドの回数
• 改善した主な領域
• 最終的なプランファイルのパス
• レビューログファイルのパス

ファイル規約

• プランごとにレビューファイルを 1 つ作成します：reviews/{topic}-review.md
• {topic} は .md を除いたプランファイル名です
• すべてのラウンドを同じファイルに追記し、--- で区切ります
• 例：plans/auth-refactor.md → reviews/auth-refactor-review.md