CodexSpec 使用事例: プロジェクトに PR 記述情報生成機能を追加¶
このドキュメントは、CodexSpec プロジェクト自体に新機能を追加するために CodexSpec ツールチェーンを使用した完全なプロセスを記録し、Spec-Driven Development (SDD) の実際の応用を示しています。
概要¶
目標機能: /codexspec:pr コマンドを追加し、構造化された GitHub PR / GitLab MR 記述情報を生成する。
開発プロセス: specify → generate-spec → review-spec → clarify → spec-to-plan
主な特徴: 開発プロセス中に要件の問題を発見し、clarify コマンドで調整を行い、SDD の柔軟性を示しました。
フェーズ 1: 初期要件の明確化 (/codexspec:specify)¶
ユーザーの初期入力¶
プロジェクトに新機能を追加したい: GitHub PR 情報（または GitLab の場合は MR 情報）を正確かつ詳細に、規格に準拠して生成する新しい Git 関連コマンドを提供する。以下は他のプロジェクトで使用した 2 つの PR コマンド内容で、参考として提供する。
[参考例 1 - 構造化記述]
プロジェクトメンテナーの役割を果たし、これまでのすべての作業に基づいて、このコミットに対する明確な Pull Request 記述を作成してください。
PR 記述はチームの他のレビュアー向けであり、以下のセクションを含む:
1. 背景 (Context)
2. 実装方法 (Implementation)
3. テスト (Testing)
4. 手動検証方法 (How to Verify)
[参考例 2 - シンプルな記述]
現在のブランチと origin/main ブランチのコード差分に基づいて、Git 規格に準拠した Merge Request のタイトルと説明を Markdown 形式で整理してください。（中国語で記述）
明確化プロセス¶
Q1: 出力言語
- 選択肢: プロジェクト設定に従う / 中国語 / 自動検出
- ユーザー選択: プロジェクト設定に従う (現在: en)
Q2: プラットフォームサポート
- 選択肢: GitHub と GitLab を両方サポート / GitHub のみ / プラットフォーム自動検出
- ユーザー選択: プラットフォーム自動検出
Q3: PR 記述内容
- 選択肢: 詳細な構造化記述 / シンプルな記述 / カスタムテンプレート可能
- ユーザー選択: 詳細な構造化記述 (推奨)
Q4: トリガー条件
- 選択肢: 現在のブランチ vs origin/main / 未プッシュの commits / ターゲットブランチ指定可能
- ユーザー選択: ターゲットブランチ指定可能
Q5: Spec ソース
- 選択肢: spec.md を優先 / git 情報のみ / すべてのソースを統合
- ユーザー選択: すべてのソースを統合 (推奨)
Q6: 命名
- 選択肢: codexspec.pr / codexspec.create-pr / codexspec.create-mr
- ユーザー選択: codexspec.pr (推奨)
Q7: Spec がない場合の処理
- 選択肢: 生成を継続、背景をスキップ / ユーザーに最初に spec 作成を促す / 警告して継続
- ユーザー選択: 生成を継続、背景をスキップ
Q8: 出力方法
- 選択肢: 端末出力 / ファイルに保存 / 端末 + オプションでファイル
- ユーザー選択: 端末 + オプションでファイル (推奨)
Q9: デフォルトセクション
- 選択肢: 背景、実装方法、テスト、検証方法 (すべて選択)
- ユーザー選択: 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 は以下のセクションを含む:
- Overview: 機能概要
- Goals: 4 つのゴール
- User Stories: 受け入れ基準付きの 4 つのユーザーストーリー
- Functional Requirements: 8 つの要件 (REQ-001 から REQ-008)
- Command Parameters: 4 つのパラメータ定義
- Non-Functional Requirements: 3 つの要件 (パフォーマンス、互換性、エラー処理)
- Acceptance Criteria (Test Cases): 10 のテストケース
- Edge Cases: 6 つのエッジケース
- Output Format Example: GitHub PR と GitLab MR の例
- Out of Scope: 明示的に除外された機能
- Dependencies: 依存関係
- Related Commands: 関連コマンド
主要要件の抜粋¶
### 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)¶
レビュー結果¶
- 全体ステータス: ✅ 合格
- 品質スコア: 92/100
- 準備状態: Ready for Planning
発見された問題¶
警告 (Should Fix):
- SPEC-001: テストファイル発見ロジックが明示的に指定されていない
- SPEC-002: 複数の spec.md がある場合、「最近修正」を選択するのは不正確かもしれない
提案 (Nice to Have):
--titleパラメータの追加を検討- 出力形式検証要件の追加
- GitHub Enterprise URL パターンサポートの検討
レビューレポートの保存場所¶
.codexspec/specs/001-pr-description-generator/review-spec.md
フェーズ 4: 要件の明確化と調整 (/codexspec:clarify) ⚠️ 重要な転換点¶
発見された問題¶
ユーザーフィードバック:
spec.md の使用について問題があることに気づいた。例えば、ユーザーが実際には非常に小さな変更を行っており、codexspec の標準化されたプロセス specify->plan->tasks->implement を使用せず、直接対話で修正したり claude code の内蔵 plan mode を使用したりして、修正完了後に codexspec のコマンドを単独で呼び出して規格に準拠した PR 情報を生成したい場合がある。このような状況で、デフォルトで最近修正された spec.md を使用すると、今回の修正とは無関係な以前の spec.md の内容が使用される可能性がある。
明確化 Q&A プロセス¶
Q1: Spec 選択戦略
コンテキスト: 現在の EC-004 は「複数の spec.md → 最近修正されたものを使用」と規定している。しかし、ユーザーが小さな変更を行う際に SDD プロセスを使用していない場合、最近の spec.md は現在の修正と無関係かもしれない。
| 選択肢 | 説明 |
|---|---|
| A | デフォルトで spec.md を使用せず、ユーザーが明示的に --spec パラメータを指定した場合のみ使用 |
| 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 |
重要な変更: パラメータロジックの反転¶
フェーズ 5: 技術実装計画 (/codexspec:spec-to-plan)¶
計画概要¶
実装方法: Markdown テンプレートファイル (/codexspec:commit-staged と一貫)
新規依存関係なし - 機能はスラッシュコマンドテンプレートで実装され、Python コードは不要。
技術決定サマリー¶
| 決定 | 選択 | 理由 |
|---|---|---|
| 実装方法 | Markdown テンプレート | 既存コマンドと一貫、メンテナンスが容易 |
| 言語優先順位 | commit > output > en | /commit-staged コマンドと一貫 |
| プラットフォーム検出 | Remote URL 解析 | シンプルで信頼性が高い |
| Spec 統合 | Opt-in (--spec) |
誤った参照を回避 |
| コンテンツ抽出 | ベストエフォート | ワークフローをブロックしない |
| テスト発見 | ディレクトリ+ファイル名パターン | 言語非依存 |
| タイトル生成 | 統合分析 | 最も正確 |
| コマンド検出 | プロジェクトファイル検出 | より実用的 |
| 出力モード | 端末優先、オプションでファイル | 柔軟 |
実装フェーズ¶
- Phase 1: テンプレート作成 (YAML frontmatter, 言語設定, Git コンテキスト)
- Phase 2: コア機能 (Spec 統合, テスト発見, コマンド検出, タイトル生成)
- Phase 3: エッジケース処理
- Phase 4: テスト
- Phase 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/001-pr-description-generator/spec.md に保存 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:review-spec │
│ ├─ 品質スコア: 92/100 │
│ ├─ 2 つの警告を発見 (テストファイル発見、複数 spec 処理) │
│ └─ ステータス: 合格、計画フェーズに進める │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:clarify ⚠️ 重要な調整 │
│ ├─ ユーザーが実際の使用シナリオの問題を発見 │
│ ├─ 5 つの明確化質問、すべて回答済み │
│ ├─ 重要な変更: --no-spec → --spec (opt-in) │
│ └─ 5 つの新要件 (REQ-005b, 006b, 008a, 010, 007 を更新) │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ /codexspec:spec-to-plan │
│ ├─ 技術実装計画を更新 │
│ ├─ 9 つの技術決定、5 つの新規決定を含む │
│ ├─ 5 つの実装フェーズ │
│ └─ .codexspec/specs/001-pr-description-generator/plan.md に保存 │
└─────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ 後続ステップ (このセッションでは未完了) │
│ ├─ /codexspec:review-plan - 計画品質を検証 │
│ ├─ /codexspec:plan-to-tasks - 実行可能なタスクに分解 │
│ └─ /codexspec:implement-tasks - 実装を実行 │
└─────────────────────────────────────────────────────────────────────────┘
主な学習ポイント¶
1. 明確化フェーズの価値¶
この事例は clarify コマンドの重要な役割を示しています:
- ユーザーが使用中に実際の問題を発見 - 小さな変更シナリオでの spec.md 誤用リスク
- 明確化 Q&A で設計上の欠陥を解決 - 自動検出から opt-in モードへ変更
- 要件変更がシステムに記録 - すべての変更は 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 [問題説明]
# 5. 技術計画の生成
/codexspec:spec-to-plan
# 6. 計画品質のレビュー (オプション)
/codexspec:review-plan
# 7. タスクへの分解
/codexspec:plan-to-tasks
# 8. 実装の実行
/codexspec:implement-tasks
このドキュメントは CodexSpec SDD ワークフローで自動生成され、実際の開発対話プロセスを記録しています。