openspec-proposal-creation

仕様提案の作成

仕様駆動開発の手法に従って、包括的な変更提案を作成します。

クイックスタート

仕様提案の作成では、主に次の3つの成果物を用意します。

1. proposal.md - 変更の理由、内容、影響の概要
2. tasks.md - 番号付きの実装チェックリスト
3. spec-delta.md - 正式な要件変更（ADDED/MODIFIED/REMOVED）

基本的なワークフロー：変更 ID を生成 → ディレクトリを用意 → 提案の草案を作成 → 仕様差分を作成 → 構造を検証

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Proposal Progress:
- [ ] Step 1: Review existing specifications
- [ ] Step 2: Generate unique change ID
- [ ] Step 3: Scaffold directory structure
- [ ] Step 4: Draft proposal.md (Why/What/Impact)
- [ ] Step 5: Create tasks.md implementation checklist
- [ ] Step 6: Write spec deltas with EARS format
- [ ] Step 7: Validate proposal structure
- [ ] Step 8: Present for user approval

ステップ 1：既存の仕様を確認する

提案を作成する前に、現在の状態を把握します。

# List all existing specs
find spec/specs -name "spec.md" -type f

# List active changes to avoid conflicts
find spec/changes -maxdepth 1 -type d -not -path "*/archive"

# Search for related requirements
grep -r "### Requirement:" spec/specs/

ステップ 2：一意の変更 ID を生成する

説明的で URL セーフな識別子を選びます。

形式：add-<feature>、fix-<issue>、update-<component>、remove-<feature>

例：

• add-user-authentication
• fix-payment-validation
• update-api-rate-limits
• remove-legacy-endpoints

検証：競合がないか確認します。

ls spec/changes/ | grep -i "<proposed-id>"

ステップ 3：ディレクトリ構造を用意する

標準的な構造で変更用フォルダーを作成します。

# Replace {change-id} with actual ID
mkdir -p spec/changes/{change-id}/specs/{capability-name}

例：

mkdir -p spec/changes/add-user-auth/specs/authentication

ステップ 4：proposal.md の草案を作成する

出発点として、templates/proposal.md のテンプレートを使用します。

必須セクション：

• Why：この変更の原動力となる問題または機会
• What Changes：変更内容の箇条書き
• Impact：影響を受ける仕様、コード、API、ユーザー

文体：明確かつ簡潔で、意思決定を重視します。不要な背景説明は避けてください。

ステップ 5：実装チェックリスト tasks.md を作成する

実装を具体的でテスト可能なタスクに分割します。templates/tasks.md のテンプレートを使用してください。

形式：

# Implementation Tasks

1. [First concrete task]
2. [Second concrete task]
3. [Test task]
4. [Documentation task]

ベストプラクティス：

• 各タスクは単独で完了できるようにします
• テストと検証のタスクを含めます
• 依存関係の順に並べます（API より先にデータベースなど）
• 通常は 5～15 個のタスクが目安です。さらに必要な場合は分割してください

ステップ 6：EARS 形式で仕様差分を記述する

ここが最も重要なステップです。仕様差分には EARS 形式（Easy Approach to Requirements Syntax）を使用します。

EARS の完全なガイドラインについては、reference/EARS_FORMAT.md を参照してください。

差分操作：

• ## ADDED Requirements - 新しい機能
• ## MODIFIED Requirements - 変更された動作（更新後の全文を含めます）
• ## REMOVED Requirements - 非推奨となる機能

基本的な要件の構造：

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN a user with email "[email protected]" and password "correct123"
WHEN the user submits the login form
THEN the system creates an authenticated session
AND redirects to the dashboard

検証パターンについては、reference/VALIDATION_PATTERNS.md を参照してください。

ステップ 7：提案の構造を検証する

ユーザーに提示する前に、次のチェックを実行します。

Structure Checklist:
- [ ] Directory exists: `spec/changes/{change-id}/`
- [ ] proposal.md has Why/What/Impact sections
- [ ] tasks.md has numbered task list (5-15 items)
- [ ] Spec deltas have operation headers (ADDED/MODIFIED/REMOVED)
- [ ] Requirements follow `### Requirement: <name>` format
- [ ] Scenarios use `#### Scenario:` format (4 hashtags)

自動チェック：

# Count delta operations (should be > 0)
grep -c "## ADDED\|MODIFIED\|REMOVED" spec/changes/{change-id}/specs/**/*.md

# Verify scenario format (should show line numbers)
grep -n "#### Scenario:" spec/changes/{change-id}/specs/**/*.md

# Check requirement headers
grep -n "### Requirement:" spec/changes/{change-id}/specs/**/*.md

ステップ 8：ユーザーに提示して承認を得る

提案の概要を明確に説明します。

## Proposal Summary

**Change ID**: {change-id}
**Scope**: {brief description}

**Files created**:
- spec/changes/{change-id}/proposal.md
- spec/changes/{change-id}/tasks.md
- spec/changes/{change-id}/specs/{capability}/spec-delta.md

**Next steps**:
Review the proposal. If approved, say "openspec implement" or "apply the change" to begin implementation.

応用トピック

EARS 形式の詳細： reference/EARS_FORMAT.md を参照してください
検証パターン： reference/VALIDATION_PATTERNS.md を参照してください
完全な例： reference/EXAMPLES.md を参照してください

よくあるパターン

パターン 1：新機能の提案

新しい機能を追加する場合：

• ADDED Requirements の差分を使用します
• 肯定的なシナリオとエラー処理の両方を含めます
• シナリオではエッジケースを考慮します

パターン 2：破壊的変更の提案

既存の動作を変更する場合：

• MODIFIED Requirements の差分を使用します
• 更新後の要件の全文を含めます
• 何を、なぜ変更するのかを proposal.md に記載します
• tasks.md で移行タスクを検討します

パターン 3：非推奨化の提案

機能を削除する場合：

• REMOVED Requirements の差分を使用します
• 削除の理由を proposal.md に記載します
• クリーンアップタスクを tasks.md に含めます
• 影響のセクションでユーザーの移行を検討します

避けるべきアンチパターン

しないでください：

• 検証チェックを省略する（必ず grep パターンを実行してください）
• 既存の仕様を確認せずに提案を作成する
• 曖昧なタスクの説明を使う（「例のものを修正する」など）
• シナリオを含めずに要件を書く
• エラー処理のシナリオを忘れる
• 関連のない複数の変更を1つの提案にまとめる

してください：

• 変更 ID を作成する前に競合を確認する
• 具体的でテスト可能なタスクを書く
• 肯定的なシナリオと否定的なシナリオの両方を含める
• 提案ごとに懸案事項を1つにする
• 提示する前に構造を検証する

ファイルテンプレート

すべてのテンプレートは templates/ ディレクトリにあります：

• proposal.md - 提案の構成
• tasks.md - タスクチェックリストの形式
• spec-delta.md - 仕様差分のテンプレート

参考資料

• EARS_FORMAT.md - EARS 構文の完全ガイド
• VALIDATION_PATTERNS.md - Grep/bash による検証
• EXAMPLES.md - 実際の提案例

---

トークン予算：この SKILL.md は約 450 行で、推奨上限の 500 行以内です。参考ファイルは、段階的な情報開示のため、必要な場合にのみ読み込まれます。