Codex CLI 完全ガイド：簡単！カスタムプロンプトを使った仕様駆動開発

はじめに

Kiro の「要件定義 → 設計 → 実装」の思想をヒントに、Codex CLI のカスタムプロンプトで仕様駆動開発フローを再現する方法を紹介します。以下のテンプレートを prompts/ ディレクトリに配置しておけば、チームメンバーは同じ手順で AI と協働しながらプロジェクトを推進できます。

---

1. 仕様駆動開発フロー（Kiro 参照）

1. 要件抽出：高レベル要求からユーザーストーリーと受け入れ条件を整理。
2. 設計：データフロー、API、DB スキーマなどを定義し既存資産と整合。
3. タスク分割：実装タスクと依存関係を計画。
4. 実装：タスクごとにコードを生成しテストまで整備。
5. 自動同期：テスト・ドキュメント更新などの補助タスクを自動化。
6. レビュー/反復：成果物をチェックし、必要に応じて改訂。
7. リリース準備：品質・セキュリティ・ドキュメントの最終確認。

この流れに合わせて 7 つのテンプレートを用意します。必要に応じて argument_hint の入力を変えながら何度でも再利用できます。

---

2. カスタムプロンプトの配置と命名ルール

• フォルダ：~/.codex/prompts/（グローバル）またはリポジトリ直下の prompts/。
• ファイル形式：先頭に JSON メタ情報を記述し、--- 以降に Markdown で本文を書く。
• 命名衝突：ビルトインコマンド名（init 等）と重複しないようにする。

{
  "name": "spec-requirements",
  "description": "要件抽出＋ユーザーストーリー生成",
  "argument_hint": "機能名、対象ユーザー、背景、制約を入力"
}
---
# ここから本文 …

Codex は name を /prompts:<name> として扱い、description をコマンドポップアップに表示します。

---

3. プロンプトテンプレート一覧（実践版）

3.1 要件抽出：prompts/spec-requirements.md

{
  "name": "spec-requirements",
  "description": "要件抽出＋ユーザーストーリー生成",
  "argument_hint": "機能名、ターゲットユーザー、目的、制約を入力"
}
---
# 要件抽出セッション

## 0. 入力サマリ
- 機能/プロジェクト名: {入力値}
- ターゲットユーザー: {入力値}
- 背景・ビジネス目的: {入力値}
- 既知の制約/前提: {入力値}

## 1. 追加で確認したい質問
- 足りない情報があれば箇条書きで質問を列挙してください。

## 2. ユーザーストーリー
| ID | As a | I want | So that | リンクする要件/制約 |
|----|------|--------|---------|----------------------|

## 3. 受け入れ条件 (Acceptance Criteria)
- Given / When / Then 形式でストーリーごとに列挙。
- テスト観点ごとにグループ化し、空欄があれば TODO と記す。

## 4. 非機能要件
- パフォーマンス、セキュリティ、アクセシビリティ、SLO など。

## 5. ランディングゾーンと制約
- 依存システム、外部 API、ライセンス制約など。

## 6. リスクと未解決事項
- 影響度 / 発生確率で分類し、フォローアップすべき項目をリスト化。

## 7. 成功指標 (Success Metrics)
- 定量・定性の KPI 候補を提示。

3.2 設計：prompts/spec-design.md

{
  "name": "spec-design",
  "description": "データフロー・アーキテクチャ設計",
  "argument_hint": "要件サマリと既存システム情報を入力"
}
---
# システム設計レビュー

1. **前提再確認**
   - 対象要件 (ID) と非機能要件を箇条書き。

2. **アーキテクチャ概要**
   - 主要コンポーネントと役割を整理。
   - Mermaid 形式のシーケンス図またはコンポーネント図を提案。

3. **データフロー / 状態遷移**
   - ユースケースごとのシーケンスを箇条書き。
   - 状態遷移図や ER 図が必要なら Mermaid で生成。

4. **API / インターフェース仕様**
   - エンドポイント、HTTP メソッド、入出力スキーマ、バリデーション。
   - エラーケースとレスポンス例も含める。

5. **データモデル / 永続化戦略**
   - テーブル/コレクション構造、主キー、インデックス。
   - 既存モデルとのマッピングがあれば記載。

6. **既存コードへのマッピング**
   - 参照すべきファイル、クラス、ユーティリティ。
   - 差分が生じる箇所と互換性への配慮。

7. **リスクとガードレール**
   - 不確定事項、技術的負債、性能ボトルネック。

8. **テスト/観測性**
   - ログ、メトリクス、トレースの追加点。
   - 推奨テストケース（単体/統合/E2E）。

3.3 タスク分割：prompts/spec-planning.md

{
  "name": "spec-planning",
  "description": "実装タスクと依存関係の整理",
  "argument_hint": "設計結果の要約と優先順位を入力"
}
---
# 実装プラン

## タスクツリー
- 箇条書きで親タスク > サブタスクを表現。
- 各タスクに ID (T-1 形式) を付与。

## タスク詳細
| ID | 概要 | 紐づく要件ID | 成果物 (ファイル/モジュール) | 依存関係 | テスト観点 | 備考 |
|----|------|---------------|-------------------------------|-----------|-------------|------|

## スケジュール案
- クリティカルパスを明記。
- 並行可能なタスクをグルーピング。

## リスク緩和策
- 各リスク (ID) に対して担当者とフォローアップタイミングを設定。

3.4 タスク実行：prompts/spec-implement.md

{
  "name": "spec-implement",
  "description": "個別タスクの実装支援",
  "argument_hint": "タスクID、目的、関連ファイルを入力"
}
---
# 実装ステップガイド

- **タスク IDと目的**: {入力値}
- **関連ファイル/モジュール**: 箇条書き
- **準備**: 必要なセットアップ、依存ライブラリ、Feature Flag など
- **実装ステップ**
  1. ステップ1 …
  2. ステップ2 …
- **コードスニペット候補（必要に応じて言語名を追記）**
      # 例:
      # function foo() { ... }
- **検証**
  - 実行すべきコマンド（例: `just test`、`cargo test -p ...`）。
  - 手動確認が必要なら手順も記載。
- **レビュー観点**: 忘れがちなポイント、リファクタリング提案。

3.5 自動化フック：prompts/spec-hooks.md

{
  "name": "spec-hooks",
  "description": "自動同期フックの提案",
  "argument_hint": "CI/CD 環境と欲しい自動化を入力"
}
---
# 自動化フック設計

| トリガー | 実行条件 | 実行内容 | ツール/スクリプト | 成功時のアウトプット | 失敗時の対応 |
|----------|----------|-----------|---------------------|------------------------|----------------|

- **推奨 MCP/CI 連携**: Codex MCP、GitHub MCP、外部 API など。
- **セキュリティ/ガバナンス配慮**: 機密情報の扱い、署名、RBAC。
- **継続的改善案**: 次に追加するべき自動化の候補。

3.6 レビューと反復：prompts/spec-review.md

{
  "name": "spec-review",
  "description": "レビュー/修正サイクルの支援",
  "argument_hint": "レビュー対象 (仕様/設計/コード) と観点を入力"
}
---
# レビューガイド

## 対象
- レビュー対象: {入力値}
- 前提/関連タスク: {入力値}

## チェックリスト
- [ ] 機能要件を満たしているか
- [ ] 非機能要件 …
- [ ] セキュリティ / コンフィグ …

## 指摘事項
| 優先度 | 内容 | 根拠/参照 | 対応者 | 期限 |
|--------|------|------------|--------|-------|

## 改善プラン
- 修正ステップ
- 再検証手順
- 影響範囲の確認方法

3.7 リリース準備：prompts/spec-release.md

{
  "name": "spec-release",
  "description": "リリース最終チェック",
  "argument_hint": "リリースバージョン、主要変更点を入力"
}
---
# リリースチェックリスト

## リリース概要
- バージョン: {入力値}
- 主な変更点: {入力値}

## チェック項目
- [ ] テスト完了 / カバレッジ報告
- [ ] セキュリティスキャン / 依存更新
- [ ] ドキュメント整合（README, CHANGELOG, API Docs）
- [ ] リリースノート下書き
- [ ] ロールバック手順確認

## リリース手順
1. コマンド/スクリプト …
2. 確認事項 …

## 通知計画
- 内部向け: …
- 外部向け: …

## レトロスペクティブ
- 良かった点、課題、次回へのアクション

---

4. ワークフローへの組み込み手順

1. テンプレートを prompts/ に配置し、Git 管理下でレビュー可能にする。
2. TUI で /prompts:spec-requirements のように呼び出し、入力ヒントに沿って必要情報を渡す。
3. 各ステージのアウトプットを README や設計書、Issue/PR に転記し共有。
4. MCP を活用する場合は、spec-hooks の提案を参考に codex mcp add ... でツールを登録し /mcp で確認。
5. /status や /review と組み合わせて継続的に状態を把握しながら進める。

---

5. 運用ベストプラクティス

• テンプレートのバージョン管理：Pull Request 経由で更新し、プロンプト自体をレビュー対象に含める。
• プロジェクト別カスタマイズ：フロントエンド/バックエンド用など目的別に複数テンプレートを用意。
• 入力ヒントの活用：argument_hint に必要情報を明記しておくと差し戻しが減る。
• 自動化との連携：spec-hooks の結果を GitHub Actions や Codex MCP に落とし込み、属人化を防ぐ。
• ナレッジ蓄積：レビュー結果やレトロスペクティブをテンプレートに追記することで、次の開発サイクルに活かす。

---

6. まとめ

• Kiro の仕様駆動開発フローを Codex CLI のカスタムプロンプトで再現することで、要件定義からリリースまで一貫したプロセスをチームで共有できます。
• /prompts:<name> 形式で呼び出せるテンプレートを整備しておけば、メンバーは迷わず同じアウトプット形式を維持できます。
• MCP との連携や自動化フックの提案もテンプレート化しておくと、仕様・実装・運用のズレを最小化できます。