CodexSpec の使用事例: プロジェクトに PR 記述生成機能を追加する¶
このドキュメントは、CodexSpec プロジェクト自体に新機能を追加するために CodexSpec ツールチェーンを使った完全なプロセスを記録したもので、Spec-Driven Development (SDD) の実践例を示しています。
概要¶
対象となる機能: /codexspec:pr コマンドの追加。構造化された GitHub PR / GitLab MR の説明を生成します。(出荷されたコマンドのユーザー向け概要は、README の /codexspec:pr の項目 を参照してください。)
開発フロー: specify → generate-spec → review-spec → clarify → spec-to-plan
主な特徴: 開発の途中で要件の問題が浮上し、clarify コマンドで修正された点です。これは SDD の柔軟性を示しています。CodexSpec の Confirmation Gate の具体例でもあり、あなたが明示的に確認するまでは何も確定せず、一度受け入れられた意思決定も clarify のチェックポイントで再検討されて覆すことができます。
ステージ 1: 初期要件の明確化 (/codexspec:specify)¶
初期のユーザー入力¶
プロジェクトに機能を追加したい。Git 関連の新コマンドで、正確で詳細かつ標準に準拠した GitHub PR の説明 (GitLab の場合は MR の説明) を生成する。参考までに、他のプロジェクトで使っていた 2 つの PR コマンドを以下に示す。
[参考例 1 - 構造化された説明]
ここまでに行ったすべての作業を踏まえ、プロジェクトメンテナーとして、この投稿に対する明確なプルリクエストの説明を書いてください。
PR の説明はチームの他のレビュアー向けとし、次のセクションを含めること:
1. Context
2. Implementation
3. Testing
4. How to Verify
[参考例 2 - シンプルな説明]
現在のブランチと origin/main とのコード差分をもとに、Git の慣例に従った Markdown でマージリクエストのタイトルと説明を作成してください。(中国語で記述すること。)
明確化のプロセス¶
Q1: 出力言語
- 選択肢: プロジェクト設定に従う / 中国語 / 自動検出
- ユーザーの選択: プロジェクト設定に従う (現在: en)
Q2: プラットフォームサポート
- 選択肢: GitHub と GitLab の両方をサポート / GitHub のみ / プラットフォームを自動検出
- ユーザーの選択: プラットフォームを自動検出
Q3: PR 説明の内容
- 選択肢: 詳細な構造化説明 / 簡潔な説明 / カスタマイズ可能なテンプレート
- ユーザーの選択: 詳細な構造化説明 (推奨)
Q4: 起動条件
- 選択肢: 現在のブランチと origin/main / 未 push のコミット / 設定可能なターゲットブランチ
- ユーザーの選択: 設定可能なターゲットブランチ
Q5: spec のソース
- 選択肢: spec.md を優先 / Git 情報のみ / すべてのソースを統合
- ユーザーの選択: すべてのソースを統合 (推奨)
Q6: 名前付け
- 選択肢: codexspec.pr / codexspec.create-pr / codexspec.create-mr
- ユーザーの選択: codexspec.pr (推奨)
Q7: spec が見つからない場合の扱い
- 選択肢: 生成を続行し Context をスキップ / 先に spec 作成を促す / 警告しつつ継続
- ユーザーの選択: 生成を続行し Context をスキップ
Q8: 出力方法
- 選択肢: ターミナル出力 / ファイルに保存 / ターミナル + 任意でファイル
- ユーザーの選択: ターミナル + 任意でファイル (推奨)
Q9: デフォルトのセクション
- 選択肢: Context, Implementation, Testing, How to Verify (すべて選択)
- ユーザーの選択: 4 セクションすべて
Q10: コマンドのパラメータ
- ユーザーの選択: すべてのパラメータは任意
--target-branch: デフォルトは origin/main--output: 指定がない場合はターミナル出力のみ--sections: 指定がない場合はデフォルトに従う--no-spec: spec.md の検索をスキップ
言語設定の修正¶
ユーザーからのフィードバック: 言語の挙動は /commit-staged コマンドに合わせるべき。すなわち、まず config.yml の language.commit を優先し、language.commit が未設定の場合にのみ language.output にフォールバックする。
更新後の要件サマリ:
ステージ 2: 仕様書ドキュメントの生成 (/codexspec:generate-spec)¶
生成されたドキュメントの構造¶
生成された spec.md は次のセクションを含みます。
- 概要: 機能の概要
- 目標: 4 つの目標
- ユーザーストーリー: 受け入れ基準を伴う 4 つのユーザーストーリー
- 機能要件: 8 つの要件 (REQ-001 から REQ-008)
- コマンドパラメータ: 4 つのパラメータ定義
- 非機能要件: 3 つの要件 (パフォーマンス、互換性、エラー処理)
- 受け入れ基準 (テストケース): 10 のテストケース
- エッジケース: 6 つのエッジケース
- 出力フォーマットの例: GitHub PR と GitLab MR の例
- 対象外: 明示的に除外した機能
- 依存関係: 依存関係
- 関連コマンド: 関連コマンド
主要な要件の抜粋¶
### REQ-003: Language Configuration
The command shall determine output language in the following priority order:
1. `language.commit` in `.codexspec/config.yml` (highest priority)
2. `language.output` in `.codexspec/config.yml` (fallback)
3. English (default if no configuration)
ステージ 3: 仕様のレビュー (/codexspec:review-spec)¶
レビュー結果¶
- 総合ステータス: ✅ Pass
- 品質スコア: 92/100
- 準備状態: 計画対応可
検出された問題¶
警告 (対応推奨):
- SPEC-001: テストファイル検出のロジックが明示的に指定されていない
- SPEC-002: 複数の spec.md が存在する場合「最終更新日時」で選ぶと不正確になりうる
提案 (あると嬉しい):
--titleパラメータの追加を検討する- 出力フォーマットの検証要件を追加する
- GitHub Enterprise の URL パターンのサポートを検討する
レビューレポートの場所¶
.codexspec/specs/2026-0613-1200ab-pr-description-generator/review-spec.md
これは 証拠に基づくレビュー です。上記の警告と提案はそれぞれ spec 内の具体的で特定可能なギャップに紐付き、助言項目 (あると嬉い) は受け入れ判断に影響せず、自動変更もトリガーしません。
ステージ 4: 要件の明確化と調整 (/codexspec:clarify) ― 重要な転換点¶
発見された問題¶
ユーザーからのフィードバック:
spec.md の使い方に問題があることに気づきました。たとえば、ユーザーが非常に小さな変更を行う場合は、CodexSpec の標準フロー (specify → plan → tasks → implement) をたどらず、対話や Claude Code の組み込み plan モードで直接変更を行い、変更が終わったあとに別途 CodexSpec コマンドを呼び出して標準準拠の PR 説明を生成したくなります。このとき、デフォルトで「最終更新日時の spec.md」を選ぶと、今回の変更と無関係な過去の spec.md の内容を引き込んでしまうかもしれません。
これはまさに Confirmation Gate の実例です。先の意思決定 (「デフォルトで最終更新日時の spec.md を使う」) は記録されていましたが、覆せないという意味での確定はしていませんでした。ユーザーが現実の利用パターンという新情報とともに clarify のチェックポイントで再検討し、一度受け入れられたデフォルトは覆りました。
明確化 Q&A のプロセス¶
Q1: spec の選択戦略
コンテキスト: 現在の EC-004 は「複数の spec.md → 最終更新日時のものを使用」としている。しかし、ユーザーが SDD フローに従わず小さな変更を行った場合、最新の spec.md は今回の変更と無関係な可能性がある。
| 選択肢 | 説明 |
|---|---|
| A | ユーザーが明示的に --spec を渡さない限り、デフォルトでは spec.md を使わない |
| B | ブランチ名で一致させる |
| C | ユーザーに選択を促す |
| D | ファイル変更で一致させる |
ユーザーの選択: 選択肢 A
理由: 誤参照を避けるため。--spec パラメータにより、SDD 連携を望むユーザーが明示的にオプトインできる。
Q2: spec のコンテンツ抽出戦略
コンテキスト: ユーザーが --spec を渡した場合、spec.md の構造が不完全だとどうするか?
| 選択肢 | 説明 |
|---|---|
| A | ベストエフォートで抽出し、欠落セクションはスキップ |
| B | 警告し Context をスキップ |
| C | 完全な構造を要求し、そうでなければエラーにする |
ユーザーの選択: 選択肢 A 理由: spec のフォーマット問題でワークフローを止めないため。
Q3: テストファイルの検出
コンテキスト: Testing セクションはどのようにテストファイルを検出すべきか?
| 選択肢 | 説明 |
|---|---|
| A | 一般的なディレクトリパターン (tests/, test/) |
| B | 言語非依存のヒューリスティクス (ディレクトリ + ファイル名パターン) |
| C | 能動的な検出は行わず、コミットメッセージからのみ推論 |
ユーザーの選択: 選択肢 B 理由: 様々な言語の多様なプロジェクト構造をカバーできるため。
Q4: PR タイトルの生成
コンテキスト: PR のタイトルはどのように生成すべきか?
| 選択肢 | 説明 |
|---|---|
| A | ブランチ名のパースを優先 |
| B | 最初のコミットメッセージを優先 |
| C | 統合 (git diff + ブランチ名 + コミットメッセージ) |
ユーザーの選択: 選択肢 C 理由: 最初のコミットは変更の一部しか表しておらず、ブランチ名は強い命名規律を前提とする。参照できる git 情報とコード変更が豊富にある場合、統合的に分析する方がより正確。
Q5: 検証コマンドの生成
コンテキスト: 「How to Verify」セクションは検証コマンドをどう生成すべきか?
| 選択肢 | 説明 |
|---|---|
| A | 汎用テンプレート |
| B | プロジェクト検出 (pyproject.toml → pytest, package.json → npm test) |
| C | コミットメッセージから推論 |
ユーザーの選択: 選択肢 B 理由: プロジェクト検出の方が実用的な検証コマンドを生成できるため。
明確化セッションのサマリ¶
| 質問 | 決定 | 影響 |
|---|---|---|
| spec の選択戦略 | --spec でオプトイン |
REQ-007, EC-004, パラメータ表 |
| spec のコンテンツ抽出 | ベストエフォートで抽出 | REQ-005b, EC-004c |
| テストファイル検出 | 言語非依存のヒューリスティクス | REQ-006b |
| PR タイトルの生成 | 統合的分析 | REQ-008a |
| 検証コマンドの生成 | プロジェクトファイル検出 | REQ-010 |
主要な変更: パラメータロジックの反転¶
この反転は、本ケーススタディにおける Confirmation Gateのもっとも明快な実例です。当初「確定」していた (つまり spec をデフォルトでオンにするという) デフォルト --no-spec が、ユーザーがそれを壊すような現実のワークフローを持ち出したことで、再検討され、反転し、オプトインとして再確認されました。
ステージ 5: 技術実装計画 (/codexspec:spec-to-plan)¶
計画の概要¶
実装アプローチ: Markdown テンプレートファイル (/codexspec:commit-staged と一貫)
新規依存関係なし ― 機能はスラッシュコマンドのテンプレートで提供され、Python コードは不要です。
技術的意思決定のサマリ¶
| 決定 | 選択 | 理由 |
|---|---|---|
| 実装アプローチ | Markdown テンプレート | 既存コマンドと一貫、保守が容易 |
| 言語優先順位 | commit > output > en | /commit-staged と一貫 |
| プラットフォーム検出 | リモート URL のパース | シンプルで信頼性が高い |
| spec 連携 | オプトイン (--spec) |
誤参照を回避 |
| コンテンツ抽出 | ベストエフォート | ワークフローを止めない |
| テスト検出 | ディレクトリ + ファイル名パターン | 言語非依存 |
| タイトル生成 | 統合的分析 | 最も正確 |
| コマンド検出 | プロジェクトファイル検出 | より実用的 |
| 出力モード | ターミナル優先、任意でファイル | 柔軟 |
実装フェーズ¶
- フェーズ 1: テンプレート作成 (YAML frontmatter、言語設定、Git コンテキスト)
- フェーズ 2: コア機能 (Spec 連携、テスト検出、コマンド検出、タイトル生成)
- フェーズ 3: エッジケース対応
- フェーズ 4: テスト
- フェーズ 5: ドキュメントの更新
ファイル一覧¶
作成:
templates/commands/pr.md
修正:
CLAUDE.md- コマンドの説明を追加README.md- コマンドを一覧に追加
テスト:
tests/test_pr_template.py
完全なフロー図¶
┌─────────────────────────────────────────────────────────────────────────┐
│ CodexSpec SDD 開発フロー │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:specify │
│ ├─ Q&A で要件を明確化 │
│ ├─ ユーザーが参考例を提供 │
│ └─ 言語・プラットフォーム・内容・パラメータなどを網羅する 10 の質問 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:generate-spec │
│ ├─ 完全な spec.md を生成 │
│ ├─ ユーザーストーリー 4 つ、機能要件 8 つ、テストケース 10 個 │
│ └─ .codexspec/specs/2026-0613-1200ab-pr-description-generator/spec.md │
│ に保存 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:review-spec │
│ ├─ 品質スコア: 92/100 │
│ ├─ 警告を 2 件検出 (テストファイル検出、複数 spec の取り扱い) │
│ └─ ステータス: Pass、計画に進める │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:clarify (重要な調整) │
│ ├─ ユーザーが現実の利用上の問題を提示 │
│ ├─ 明確化の質問 5 つ、すべて回答 │
│ ├─ 主要な変更: --no-spec → --spec (オプトイン) │
│ └─ 要件を 5 つ追加 (REQ-005b, 006b, 008a, 010、007 を更新) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:spec-to-plan │
│ ├─ 技術実装計画を更新 │
│ ├─ 技術意思決定 9 つ、うち新規は 5 つ │
│ ├─ 実装フェーズ 5 つ │
│ └─ .codexspec/specs/2026-0613-1200ab-pr-description-generator/plan.md │
│ に保存 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 後続ステップ (このセッションでは未完了) │
│ ├─ /codexspec:review-plan - 計画の品質を検証 │
│ ├─ /codexspec:plan-to-tasks - 実行可能なタスクに分割 │
│ └─ /codexspec:implement-tasks - 実装を実行 │
└─────────────────────────────────────────────────────────────────────────┘
主な学び¶
1. clarify ステージの価値¶
この事例は clarify コマンドの極めて重要な役割を示しています。
- ユーザーが使用中に現実の問題を発見 ― 小さな変更场景で spec.md を誤用するリスク
- 明確化の Q&A を通じて設計上の欠陥を解決 ― 自動検出からオプトインへの移行
- 要件変更が体系的に記録される ― すべての変更は spec.md の Clarifications セクションに保存
2. SDD フローの柔軟性¶
- 線形なフローではなく、どの段階でも戻って調整できる
clarifyはreview-specのあと、spec-to-planの前に挿入できる- 仕様書ドキュメントも技術計画も、変更を反映して更新される
3. パラメータ設計の進化¶
この変更は「デフォルトで SDD ワークフロー」から「非 SDD ワークフローもサポート」への設計上のシフトを反映しており、ツールをより汎用的にしています。
4. ドキュメントの出力¶
| ステージ | 出力ファイル | 内容 |
|---|---|---|
| generate-spec | spec.md | 完全な仕様書ドキュメント |
| review-spec | review-spec.md | 品質レビューレポート |
| clarify | (spec.md を更新) | 明確化の記録と要件の更新 |
| spec-to-plan | plan.md | 技術実装計画 |
付録: コマンドクイックリファレンス¶
# 1. 初期要件の明確化
/codexspec:specify
# 2. 仕様書ドキュメントの生成
/codexspec:generate-spec
# 3. 仕様の品質レビュー
/codexspec:review-spec
# 4. 要件の明確化・調整 (任意、問題を発見した場合に使用)
/codexspec:clarify [issue description]
# 5. 技術計画の生成
/codexspec:spec-to-plan
# 6. 計画の品質レビュー (任意)
/codexspec:review-plan
# 7. タスクへの分割
/codexspec:plan-to-tasks
# 8. 実装の実行
/codexspec:implement-tasks
このドキュメントは CodexSpec SDD ワークフローで生成され、実際の開発の対話を記録したものです。