Skip to content

Instantly share code, notes, and snippets.

@keisuke70

keisuke70/SKILL.md

Last active April 7, 2026 04:02
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save keisuke70/1063a8657fa7db9ba7ecefa622bffd32 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save keisuke70/1063a8657fa7db9ba7ecefa622bffd32 to your computer and use it in GitHub Desktop.
Download ZIP
Claude Code x Codex: Autonomous plan review skill
Raw
review-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"required": ["verdict", "issues", "summary", "confidence"],
"additionalProperties": false,
"properties": {
"verdict": { "enum": ["APPROVED", "NEEDS_CHANGES"] },
"confidence": { "type": "number", "minimum": 0, "maximum": 1 },
"summary": { "type": "string" },
"issues": {
"type": "array",
"items": {
"type": "object",
"required": ["severity", "location", "problem", "suggestion"],
"additionalProperties": false,
"properties": {
"severity": { "enum": ["critical", "major", "minor"] },
"location": { "type": "string" },
"problem": { "type": "string" },
"suggestion": { "type": "string" }
}
}
}
}
}
Raw
SKILL.md
name codex-plan-review
description Review implementation plans using Codex CLI with project context injection, structured JSON output, and peer-review evaluation. Iterates until approved (max 5 rounds).
user-invocable true
metadata
tags
plan, review, codex, quality

Codex Plan Review Skill

When to Apply

Apply this skill when:

  • User invokes /codex-plan-review
  • A plan has been created in plan mode and needs review before approval

Execution Flow

Step 1: コンテキスト収集（並列実行）

以下を並列で収集する:

  1. プランファイル: Glob で .claude/plans/*.md から最新を取得し Read
    • なければユーザにパスを確認
  2. プロジェクト知識: CLAUDE.md や auto-memory (MEMORY.md) がシステムプロンプトにロード済みならそれを使う。なければ Read で取得
  3. 関連コード: プランに登場するファイルのうち主要なもの（最大3ファイル）を Read
  4. Decision Records / ADR: プロジェクトに設計判断の記録があれば、プランに関連するものを Read（最大5件）

Step 2: レビュー観点の動的生成

プラン内容を分析し、適切なレビュー観点を組み立てる:

  • UI/デザイン系 → アクセシビリティ、状態遷移網羅性（loading/error/empty/disabled）、トークン一貫性
  • ロジック系 → エッジケース、閾値妥当性、既存Decision Record違反チェック
  • アーキテクチャ系 → 依存関係、既存パターン踏襲、破壊的変更リスク
  • 共通（常に含める） → 実装妥当性、網羅性、不要な複雑性

生成した観点リストは DYNAMIC_REVIEW_CRITERIA として Step 3 のプロンプトに埋め込む。

Step 3: Codex exec 実行（構造化出力）

Bash で以下を実行する。変数部分はStep 1-2で収集した実際の内容に置換すること。

codex exec --full-auto --sandbox read-only \
  --output-schema .agents/skills/codex-plan-review/review-schema.json \
  - <<'CODEX_PROMPT'
あなたはシニアソフトウェアエンジニアです。以下の実装プランをレビューしてください。
出力は指定されたJSONスキーマに厳密に従うこと。

## プロジェクトの既知ルール・落とし穴
${PROJECT_KNOWLEDGE}

## 関連する設計判断 (Decision Records)
${DECISION_RECORDS}

## 関連する既存コード
${EXISTING_CODE_SNIPPETS}

## レビュー観点
${DYNAMIC_REVIEW_CRITERIA}

## プラン内容
${PLAN_CONTENT}
CODEX_PROMPT

重要:

  • --sandbox read-only で Codex がファイルを変更しないようにする
  • --output-schema で構造化JSON出力を強制する（スキーマは全objectに additionalProperties: false 必須）
  • stdout から直接JSONをパースする
  • タイムアウト: 最大120秒
  • codex コマンドが見つからない場合、ユーザに npm install -g @openai/codex を案内

Step 4: 出力解析 + Claude側の評価（ピアレビュー）

  1. stdout の JSON 出力をパースする
  2. verdict === "APPROVED" → Step 6 へ
  3. verdict === "NEEDS_CHANGES" → 各issueをClaude側で独立に評価:
評価結果 アクション
同意 プランに Edit で反映。反映内容を記録
不同意 却下理由を記録。次ラウンドでCodexに「この指摘は〇〇の理由で却下した」と伝える
判断できない ユーザに提示して判断を仰ぐ（AskUserQuestion を使用）

評価時の判断基準:

  • プロジェクトの既知ルールと矛盾する指摘 → 不同意
  • Decision Records に既に判断が記録されている内容の蒸し返し → 不同意（DRを引用して却下）
  • 既存コードベースのパターンと矛盾する指摘 → 不同意（パターンを説明して却下）
  • 合理的かつコンテキストに沿った指摘 → 同意

Step 5: 再レビュー（最大5ラウンド）

  1. Step 4 で同意したissueのみプランに反映済みの状態で、再度 Step 3 を実行
  2. プロンプトに以下を追加:
    • 前ラウンドで却下したissueとその理由
    • 「以下の指摘は検討済みで却下された。同じ指摘を繰り返さないこと」
  3. エスカレーションルール: Codexが同じissueを2ラウンド連続で指摘した場合、ユーザに判断を委ねる
  4. 停止条件: 5ラウンドでAPPROVEDが出なければ停止し、ユーザに状況を報告

Step 6: 完了報告

以下を表示してスキル完了:

  • ✅ APPROVED — Codex レビュー通過
  • レビューラウンド数
  • 採用したissue数 / 却下したissue数
  • 主な変更サマリー（あれば）

Important Notes

  • 構造化出力 (--output-schema) により VERDICT のテキストパースは不要。JSONの verdict フィールドを直接参照する
  • Claude側の評価は「鵜呑み」ではなく「ピアレビュー」。プロジェクトコンテキストを持つClaude側が、コンテキストなしのCodexより正確な判断ができるケースが多い
  • Decision Records に記録された判断は「確定済み」として扱い、Codexの指摘で覆さない
  • codex review コマンドは Git diff 専用であり、プランレビューには使用しない

Setup

.agents/skills/codex-plan-review/
├── SKILL.md
└── review-schema.json

npm install -g @openai/codex
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment