🤖
Claude Code SKILLでCodex連携を自動化：計画→承認→実装→検証の4フェーズワークフローを作成してみた
はじめに
Claude CodeとCodexを連携させる方法として、以前MCPを使った連携記事を書きました。MCPは強力ですが、実際に使い込むと「進捗が見えない」「デバッグが困難」という課題に直面しました。
そこで今回、SKILL形式でCodex連携を再実装し、さらに Claude（計画）→ ユーザー承認 → Codex（実装）→ Claude（検証） の自動ワークフローを構築しました。
注：本記事は筆者の実体験ベースです。CLIやエージェント系ツールは更新が速いので、手元のバージョン差分で挙動が変わる可能性があります。公式ドキュメントも併読してください。
この記事で作るもの
本記事では、以下の2つのSKILLを0から作成します。
| SKILL | 役割 | Codex側の安全設定（目安） |
|---|---|---|
/codex |
Codex CLIでコードベースを分析 | --sandbox read-only |
/claude-codex-workflow |
計画→承認→実装→検証の自動ワークフロー | --sandbox workspace-write |
図1: /codex（分析専用）と /claude-codex-workflow（実装まで自動化）の使い分け
この記事で分かること
- MCP連携からSKILL連携に移行するメリット
- Claude Code SKILLの作成方法（ディレクトリ構成、SKILL.mdの書き方）
- 計画→承認→実装→検証の4フェーズワークフローの実装
- 実際に遭遇したトラブルと解決方法
対象読者
- Claude Codeを日常的に使っている開発者
- MCPでのCodex連携に不満を感じている人（進捗が見えない、デバッグしづらい）
- SKILLの作成方法を実践的に学びたい人
前提条件
本記事の内容を実践するには、以下の環境が必要です。
必須
- Claude Code がインストール済み
-
Codex CLI がインストール済み（
codex --versionで確認） - Codex CLI の認証設定が完了している（
codex login statusで確認）
推奨
- Git管理されたプロジェクトディレクトリ（安全面・ロールバック面で強く推奨）
- ターミナル（bash/zsh）の基本操作ができる
動作確認環境（筆者）
- Claude Code: 1.0.34
- Codex CLI: 0.1.2502101636
- macOS 15.3 / Ubuntu 24.04
バージョンは一例です。特にCodex CLIはフラグやデフォルト挙動が変わる可能性があるので、
codex --help/ 公式CLIリファレンスも確認してください。
Codex CLIのインストール（未導入の場合）
# インストール（npm）
npm i -g @openai/codex
# 確認
codex --version
初回起動時はログインが求められます。
# 対話ログイン（ブラウザが開きます）
codex login
# ログイン状態確認（ログイン済みなら exit 0）
codex login status
APIキーでログインする場合（例）：
# OPENAI_API_KEY を使ってログイン（stdin から読み込み）
printenv OPENAI_API_KEY | codex login --with-api-key
CIなど非対話実行で
codex execを使う場合、環境変数CODEX_API_KEYが使えるケースがあります（codex exec専用）。扱うリポジトリが機密の場合、ログや出力にコードが含まれる点にも注意してください。
なぜSKILLでCodex連携を作ったか
MCP連携の課題
以前の記事で紹介したMCP（Model Context Protocol）連携には、以下の課題がありました。
| 課題 | 詳細 |
|---|---|
| 進捗が見えない | 実行中の状況がブラックボックス。数十分待っても何も表示されない |
| デバッグが困難 | エラー発生時に原因特定が難しい |
| 中断判断が難しい | 処理が継続中なのか停止しているのか分からない |
| タイムアウトの不安 | 長時間タスクで「待つべきか中断すべきか」迷う |
SKILL連携のメリット
SKILL形式に変更することで、これらの課題をだいぶ軽減できます。
| 項目 | MCP連携 | SKILL連携 |
|---|---|---|
| 進捗表示 | ❌ 見えない | ✅ ターミナル出力で把握しやすい |
| デバッグ | ❌ 困難 | ✅ CLIの出力・エラーで追いやすい |
| 中断判断 | ❌ 曖昧 | ✅ 実行ログが残る／止めどきが判断しやすい |
| カスタマイズ | △ 設定ファイル依存 | ✅ SKILL.mdで自由に定義 |
この課題と解決策は、@owayo さんの記事でも詳しく解説されています。
2つのSKILLの概要
今回作成する2つのSKILLの役割を整理します。
/codex - 安全な分析SKILL（read-only）
# 使用例
/codex このプロジェクトの構造を分析して、改善点を提案してください
- 目的: Codex CLIでコードベースを分析（読み取り中心）
-
Codexのサンドボックス:
read-only（ファイル編集をさせない） - ユースケース: コードレビュー、アーキテクチャ分析、セキュリティ観点の洗い出し
/claude-codex-workflow - 自動実装ワークフロー（workspace-write）
# 使用例
/claude-codex-workflow ユーザー認証機能を追加してください
- 目的: 計画→承認→実装→検証を自動化
-
Codexのサンドボックス:
workspace-write（ワークスペース内のファイル編集を許可） - ユースケース: 機能実装、バグ修正、リファクタリング
図2: 計画（Claude）→ 承認（ユーザー）→ 実装（Codex）→ 検証（Claude）のフロー
SKILL作成手順
SKILLを置く場所（個人 / プロジェクト）
Claude CodeのSKILLは配置場所でスコープが変わります。
-
個人スキル（全プロジェクトで使える）:
~/.claude/skills/<skill-name>/SKILL.md -
プロジェクトスキル（そのリポジトリだけで使える）:
.claude/skills/<skill-name>/SKILL.md
本記事では「まず試しやすい」個人スキル（~/.claude/skills/）で進めます。
ディレクトリ構成（例）
Claude Code SKILLは ~/.claude/skills/ 配下に配置します。
~/.claude/
├── skills/
│ ├── codex/
│ │ └── SKILL.md # /codex SKILL
│ └── claude-codex-workflow/
│ └── SKILL.md # /claude-codex-workflow SKILL
└── plans/ # ワークフローの計画保存先
└── task-YYYYMMDD-HHMMSS.md
plans/は筆者運用のフォルダです（公式仕様ではありません）。不要なら省略してOKです。
Step 1: ディレクトリ作成
# SKILLディレクトリを作成
mkdir -p ~/.claude/skills/codex
mkdir -p ~/.claude/skills/claude-codex-workflow
# （任意）計画保存先
mkdir -p ~/.claude/plans
Step 2: /codex SKILLの作成
~/.claude/skills/codex/SKILL.md を作成します。
---
name: codex
description: Codex CLIを使用したコードベース分析
version: 1.0.0
created: 2025-02-05
updated: 2025-02-05
author: yujmatsu
tags:
- codex
- analysis
- code-review
- security
mode: read-only
reference: https://zenn.dev/owayo/articles/63d325934ba0de
---
# Codex CLI Integration
このスキルは、Codex CLIを使用してコードベースの分析を実行します。
## 使い方
`/codex <分析リクエスト>`
例：
- `/codex このプロジェクトの構造を分析して、改善点を提案してください`
- `/codex 認証周りのコードをレビューして、セキュリティ上の問題を指摘してください`
- `/codex パフォーマンスのボトルネックを特定してください`
## 説明
- Codex CLIの`--full-auto`モードで完全自動実行
- `--sandbox read-only`で安全な読み取り専用分析
- リアルタイムで進捗を表示
- 確認や質問なしで具体的な提案まで自動出力
## 実行コマンド
codex exec --full-auto --sandbox read-only --skip-git-repo-check --cd "$CWD" "$ARGS 確認や質問は不要です。具体的な提案まで自主的に出力してください"
## 利点（MCP経由との比較）
- **進捗可視化**: 処理中の状況がリアルタイムで表示される
- **監視可能**: ターミナル出力でCodexの動作を確認できる
- **デバッグ容易**: エラー発生時の原因特定が簡単
- **中断判断**: 処理が継続中か停止しているかが明確
## 注意事項
- `--sandbox read-only`により、ファイルの変更は行われません
- 分析結果に基づいた実装は、別途Claude Codeで行う必要があります
Step 3: /claude-codex-workflow SKILLの作成
~/.claude/skills/claude-codex-workflow/SKILL.md を作成します。
---
name: claude-codex-workflow
description: Claude計画→Codex実装→Claude検証の自動ワークフロー
version: 1.0.0
created: 2025-02-05
updated: 2025-02-05
author: yujmatsu
tags:
- workflow
- automation
- codex
- implementation
- planning
- verification
mode: workspace-write
approval: implementation-only
phases:
- planning
- approval
- implementation
- verification
---
# Claude-Codex Workflow
Claude（計画）→ Codex（実装）→ Claude（確認）の一連のワークフローを自動化するスキルです。
## 使い方
`/claude-codex-workflow <実装タスクの説明>`
例：
- `/claude-codex-workflow ユーザー認証機能を追加してください`
- `/claude-codex-workflow パフォーマンスを改善してください`
- `/claude-codex-workflow このバグを修正してください`
## ワークフロー
### Phase 1: Planning (Claude) 🤔
1. タスクを分析し、実装方針を策定
2. 影響範囲、変更ファイル、テスト方針を明確化
3. 実装計画を `.claude/plans/task-[timestamp].md` に保存
4. **計画をユーザーに提示**
### Phase 2: User Approval ✋
- **ユーザーに計画の承認を求める**
- 修正が必要な場合は Phase 1 に戻る
- 承認後、Phase 3 へ進む
### Phase 3: Implementation (Codex) ⚡
1. Codex CLI を `--sandbox workspace-write` モードで起動
2. Phase 1 の計画を参照して実装を実行
3. リアルタイムで進捗を表示
4. ファイルの作成・変更を実行
### Phase 4: Verification (Claude) ✅
1. 実装されたコードを確認
2. 該当する場合、テストを実行
3. コードレビュー（セキュリティ、品質、パフォーマンス）
4. 結果をユーザーに報告
## コマンド例
### Implementation Phase
# Phase 3: Codex が実装を実行
codex exec --full-auto --sandbox workspace-write --skip-git-repo-check --cd "$CWD" "以下の計画に基づいて実装してください:
$(cat ~/.claude/plans/task-[timestamp].md)
確認や質問は不要です。計画に従って実装を完了させてください。"
## 利点
| フェーズ | 担当 | 利点 |
|---------|------|------|
| 計画 | Claude | 全体像を把握、方針を策定 |
| 実装 | Codex | 高速な実装、リアルタイム進捗 |
| 検証 | Claude | 品質保証、テスト実行 |
## 注意事項
### セキュリティ
- Codex は `workspace-write` モードで**実際にファイルを変更**します
- 重要なファイルは事前にバックアップを推奨
- Git コミット前に必ず内容を確認してください
### 承認ポイント
- **実装前のみ承認**を求めます（計画承認後、実装・検証は自動実行）
- より慎重な運用が必要な場合は、各フェーズ後に承認を求めるよう調整可能
### 失敗時の対応
- Phase 3 で実装が失敗した場合、エラー内容を確認して計画を修正
- Phase 4 で問題が見つかった場合、手動修正または再実行
## ディレクトリ構造
~/.claude/
├── skills/
│ └── claude-codex-workflow/
│ └── SKILL.md
└── plans/
├── task-20250205-093000.md
├── task-20250205-104500.md
└── ...
## カスタマイズ
### より慎重な運用（各フェーズで承認）
Phase 2 と Phase 4 の後にも承認を求める場合は、SKILL 内で AskUserQuestion を追加
### より自動化（完全自動）
Phase 2 の承認をスキップする場合は、計画作成後すぐに Phase 3 へ進む
### 実装提案のみ（read-only）
Codex を `--sandbox read-only` モードで実行し、実装提案のみを取得
実際の実装は Claude が行う
/codex SKILLの詳細
実行コマンドの解説
codex exec --full-auto --sandbox read-only --skip-git-repo-check --cd "$CWD" "$ARGS 確認や質問は不要です。具体的な提案まで自主的に出力してください"
| オプション | 説明 |
|---|---|
--full-auto |
完全自動実行（確認プロンプトなし） |
--sandbox read-only |
読み取り専用モード（ファイル変更なし） |
--skip-git-repo-check |
Git以外のディレクトリでも実行可能に |
--cd "$CWD" |
現在のディレクトリで実行 |
"$ARGS ..." |
ユーザーの入力 + 自動出力を促すプロンプト |
プロンプトの工夫
Codexは確認応答を求める場合があります。これを防ぐため、プロンプトに以下を追加しています。
確認や質問は不要です。具体的な提案まで自主的に出力してください
これにより、分析結果だけでなく具体的な改善提案まで自動で出力されます。
/claude-codex-workflow の詳細
4フェーズワークフロー
┌─────────────────────────────────────────────────────┐
│ Phase 1: Planning (Claude) 🤔 │
├─────────────────────────────────────────────────────┤
│ ✓ タスク分析 │
│ ✓ 実装方針の策定 │
│ ✓ 計画を ~/.claude/plans/ に保存 │
│ ✓ ユーザーに提示 │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ Phase 2: User Approval ✋ │
├─────────────────────────────────────────────────────┤
│ ⏸ ユーザーが計画を確認・承認 │
│ （修正が必要なら Phase 1 に戻る） │
└─────────────────────────────────────────────────────┘
↓ 承認後
┌─────────────────────────────────────────────────────┐
│ Phase 3: Implementation (Codex) ⚡ │
├─────────────────────────────────────────────────────┤
│ ✓ Codex を workspace-write モードで起動 │
│ ✓ 計画に基づいて実装実行 │
│ ✓ リアルタイムで進捗表示 │
│ ✓ ファイルの作成・変更 │
└─────────────────────────────────────────────────────┘
↓ 自動実行
┌─────────────────────────────────────────────────────┐
│ Phase 4: Verification (Claude) ✅ │
├─────────────────────────────────────────────────────┤
│ ✓ 実装内容の確認 │
│ ✓ テストの実行（該当する場合） │
│ ✓ コードレビュー │
│ ✓ 結果報告 │
└─────────────────────────────────────────────────────┘
なぜClaudeとCodexを分担するのか
| 役割 | Claude | Codex |
|---|---|---|
| 全体設計 | ✅ 得意 | △ |
| 実装速度 | △ | ✅ 高速 |
| 進捗表示 | - | ✅ リアルタイム |
| コードレビュー | ✅ 得意 | △ |
Claudeの設計力とCodexの実装速度・進捗可視性を組み合わせることで、効率的な開発ワークフローを実現します。
動作確認
/codex の実行例
/codex このディレクトリの構造を分析して、主要なファイルやフォルダの役割を教えてください
出力例:
[thinking] ディレクトリ構造を確認中...
[exec] ls -la でファイル一覧を取得
[thinking] 各ファイルの役割を分析中...
## 分析結果
### 主要な構成
- `src/` - アプリケーションのソースコード
- `tests/` - テストファイル
- `package.json` - 依存関係の定義
### 改善提案
1. READMEの追加を推奨
2. `.gitignore` の見直し
3. テストカバレッジの向上
...
実行時間: 約2-3秒
トークン使用量: 約12,000トークン
/claude-codex-workflow の実行例
/claude-codex-workflow ログイン機能を追加してください
Phase 1 出力例:
## 実装計画
### タスク
ログイン機能の追加
### 変更ファイル
- `src/auth/login.ts` (新規作成)
- `src/routes/index.ts` (ルート追加)
- `tests/auth/login.test.ts` (新規作成)
### 実装方針
1. ログインコンポーネントの作成
2. 認証ロジックの実装
3. ルーティング設定
4. テストの追加
この計画で実装を進めてよろしいですか？
ユーザー承認後、Phase 3-4 が自動実行されます。
ハマりどころ
1. "Not inside a trusted directory" エラー
症状: Git管理されていないディレクトリで実行するとエラー
原因: Codex CLIはデフォルトでGitリポジトリ内での実行を要求する
解決策: --skip-git-repo-check オプションを追加
# NG
codex exec --full-auto --sandbox read-only --cd "$CWD" ...
# OK
codex exec --full-auto --sandbox read-only --skip-git-repo-check --cd "$CWD" ...
2. Codexが確認を求めてくる
症状: 分析途中で「続けますか？」と確認を求められる
原因: Codexはデフォルトでユーザー確認を求める動作をする
解決策: プロンプトに明示的な指示を追加
"$ARGS 確認や質問は不要です。具体的な提案まで自主的に出力してください"
3. Claude Codeがセッションを使い回す
症状: ブランチ切り替え後も前のコンテキストが残る
原因: Claude Codeはセッション内でコンテキストを保持するため、ブランチの状態と不整合が生じる
対策: 新しいセッションを開始（/clear または再起動）
4. Codexの出力が途中で切れる
症状: 長い分析結果が途中で終了する
原因: Codex CLIのデフォルト出力制限
対策: 分析対象を絞る、または複数回に分けて実行
まとめ
これを実装したことにより、コーディングの精度が体感ですが上がったような気がします。
まだまだカスタマイズは必要なのかもしれませんが、
このまま育てていってみようと思います。
以下はまとめです。
MCP連携 vs SKILL連携
| 項目 | MCP連携 | SKILL連携 |
|---|---|---|
| 進捗表示 | ❌ 見えない | ✅ リアルタイム表示 |
| デバッグ | ❌ 困難 | ✅ ターミナル出力で確認可能 |
| 中断判断 | ❌ 曖昧 | ✅ 明確に判断可能 |
| カスタマイズ | △ 設定ファイル依存 | ✅ SKILL.mdで自由に定義 |
| セットアップ | ✅ 比較的簡単 | △ SKILL.md作成が必要 |
使い分け
| シーン | おすすめSKILL |
|---|---|
| コードレビュー・分析 | /codex |
| セキュリティ調査 | /codex |
| 機能実装 | /claude-codex-workflow |
| バグ修正 | /claude-codex-workflow |
| リファクタリング | /claude-codex-workflow |
次のステップ
-
まず
/codexを試す: read-onlyなので安全に試せます -
小さなタスクで
/claude-codex-workflowを試す: 簡単な機能追加から始める - SKILL.mdをカスタマイズ: 自分のワークフローに合わせて調整
本記事で作成したSKILLの配置
# ディレクトリ作成
mkdir -p ~/.claude/skills/codex
mkdir -p ~/.claude/skills/claude-codex-workflow
mkdir -p ~/.claude/plans
# SKILL.mdを作成（本記事のコードをコピー）
参考
-
Claude Code 公式ドキュメント（Skills） - SKILLの公式仕様（フロントマター、
$ARGUMENTSなど） - Codex CLI 公式ドキュメント - インストール・セットアップ
-
Codex CLI 公式リファレンス（コマンド/フラグ） -
codex execのオプション一覧 -
Codex Security（sandbox / approval） -
--sandboxと--ask-for-approvalの考え方 - Claude CodeとCodexの連携をMCPからSkillに変えたら体験が劇的に改善した
- Claude Code × Codex 連携入門：MCPで2つのコーディングエージェントをつなぐ実践ガイド
- Codex CLI 公式リポジトリ
Discussion