spec-runner 1.0.7 → 1.0.8

package/templates/.spec-runner/steps//343/203/206/343/202/271/343/203/210/350/250/255/350/250/210.md

@@ -1,50 +1,57 @@
+---
+step_id: test_design
+phase: 5
+primary_output: project.json の test_design.dir（既定 tests）
+---
+
+# テスト設計（Phase 5: TEST DESIGN）
+
+**やること**: UC 仕様と受入条件に基づき、**PENDING 状態のテストコード**を `test_design.dir`（既定 `tests`）に作成する。続けて analyze / checklist → 人間承認 → review-pass のち Phase 6 へ。
+
+**機械的な前提**（`project.json` の `test_design.require_uc_prefixed_tests` が true のとき）: ファイル名は **`UC-N-<slug>.spec.<ext>`**（ブランチの UC 番号と一致）にすること。**これが無いと「次のステップ」は実装フェーズに進みません**（TDD で先にテストを置く流れを強制）。
 
-> **Phase 5: TEST DESIGN（テスト設計）**  
-> UC 仕様書と受入条件に基づき、**テスト用ディレクトリ**（`.spec-runner/project.json` の `test_design.dir`、既定: `tests`）に、`test_design.pattern`（既定: `*.spec.*`。Python は `test_*.py` 等に変更可）に合う PENDING 状態のテストコードを作成します。続けて analyze / checklist → 人間が承認 → review-pass ののち、Phase 6（実装）へ進みます。
+| 項目 | 内容 |
+|------|------|
+| **出力先** | `.spec-runner/project.json` の `test_design.dir`（既定: `tests`）、パターンは `test_design.pattern`（既定: `*.spec.*`）。Python は `test_*.py` 等に変更可 |
+| **ドキュメント** | **読み取り専用**（test_design.dir への**追加のみ**）。UC 仕様の修正は「曖昧さ解消」等で別途 |
+| **命名** | spec.md **8-2** に厳守: `UC-N-{ユースケース名}.spec.{拡張子}` |
+| **ピラミッド** | spec セクション 14: Unit : Integration : E2E ≈ 70 : 20 : 10。E2E は UC 1 本あたり最大 2 本目安 |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
-
-## 概要
-
-1. **セットアップ**: リポジトリルートから `.spec-runner/scripts/lib/uc-context.sh --json --paths-only` を実行する。現在ブランチは `feature/UC-NNN-xxx`。JSON から FEATURE_SPEC（UC 仕様書）、FEATURE_DIR をパースする。
-
-2. **UC 仕様の読み込み**:
-   - FEATURE_SPEC から受入条件・成功基準・ユーザーストーリーを抽出する。
-   - `docs/03_アーキテクチャ/命名規則.md` の SOURCE_EXTENSIONS でテスト拡張子を決める（例: ts → .spec.ts）。
-   - ブランチ名から UC 番号とユースケース名（kebab）を取得する（例: feature/UC-001-order-placement → UC-001, order-placement）。
+## 実行フロー
 
-3. **テストファイルの配置と命名**（spec.md セクション 8-2 に従う）:
-   - ベースディレクトリは **`project.json` の `test_design.dir`**（未設定時は `tests`）。パターンは `test_design.pattern`（未設定時は `*.spec.*`）。Python の場合は `pattern: "test_*.py"` 等に変更する。
-   - **ユニット / UC 対応**: `{test_design.dir}/unit/UC-NNN-{ユースケース名}.spec.{拡張子}`（例: `tests/unit/UC-001-order-placement.spec.ts`）
-   - **E2E**: `{test_design.dir}/e2e/UC-NNN-{ユースケース名}.e2e.spec.{拡張子}`（例: `tests/e2e/UC-001-order-placement.e2e.spec.ts`）
-   - 集約の不変条件がある場合: `{test_design.dir}/unit/{集約名}.invariants.spec.{拡張子}`
-   - 既存のテストディレクトリ構造（unit / integration / e2e）に合わせて配置する。
+1. **セットアップ**  
+   リポジトリルートで `.spec-runner/spec-runner.sh 次のステップ --json`。ブランチ `feature/UC-N-xxx`。JSON の `feature_spec`・`feature_dir` を使用。
 
-4. **PENDING 状態でテストを記述する**:
-   - 各受入条件・成功基準に対応するテストケースを **スキップまたは TODO 状態**で作成する（例: `it.todo('...')` / `test.skip('...')` / `@pending` 等、言語・フレームワークに合わせる）。
-   - テストの説明文は UC 仕様の受入条件・成功基準と対応させる。
-   - 実装がまだないため、アサーションは仮でよい。Phase 6（実装）でグリーンにする。
-   - **E2E**: 当該 UC のハッピーパス（例: トップ → 主要画面 → 主操作 1 回）を 1 本以上 PENDING で作成する。Phase 6 完了時には**少なくとも 1 本をグリーンにする**ことを目標とする（起動・主要画面・主操作が通ることで「実際に動く」を保証する）。
+2. **UC 仕様の読み込み**
+   - FEATURE_SPEC から受入条件・成功基準・ユーザーストーリーを抽出
+   - `docs/04_アーキテクチャ/命名規則.md` の SOURCE_EXTENSIONS でテスト拡張子（例: ts → `.spec.ts`）
+   - ブランチ名から UC 番号と kebab 名（例: `feature/UC-1-order-placement` → UC-1, order-placement）
 
-5. **コンパイル・テスト実行の確認**:
-   - プロジェクトのテストコマンド（`npm test` / `docker compose run --rm app npm test` 等）でコンパイルが通り、PENDING のテストがスキップされて実行できることを確認する。
-   - Gate 5 では「テストコード存在 + コンパイル通過」が要求される。
+3. **配置と命名**（spec.md 8-2）
+   - ベース: **`project.json` の `test_design.dir`**、パターンは `test_design.pattern`
+   - ユニット/UC: `{dir}/unit/UC-N-{名}.spec.{ext}`（例: `tests/unit/UC-1-order-placement.spec.ts`）
+   - E2E: `{dir}/e2e/UC-N-{名}.e2e.spec.{ext}`
+   - 集約不変条件: `{dir}/unit/{集約名}.invariants.spec.{ext}`
+   - 既存の unit / integration / e2e 構造に合わせる
 
-6. **成果物の報告**:
-   - 作成したテストファイル一覧と、対応する UC ・受入条件の対応表を簡潔に報告する。
-   - 続けて「分析」「チェックリスト」を実行し、人間の承認後に **AI が** phase-locks.json の該当を更新してから Phase 6（実装）へ進む旨を案内する。
+4. **PENDING で記述**
+   - 受入条件・成功基準ごとに **スキップ/TODO**（`it.todo` / `test.skip` / `@pending` 等）
+   - 説明文は UC の受入・成功基準と対応。アサーションは仮で可（Phase 6 でグリーン）
+   - **E2E**: 当該 UC のハッピーパスを 1 本以上 PENDING。Phase 6 完了時は**少なくとも 1 本グリーン**を目標
 
-## 重要ルール
+5. **コンパイル・実行確認**  
+   プロジェクトのテストコマンドでコンパイル通過、PENDING がスキップされて実行できること。Gate 5 は「テストコード存在 + コンパイル通過」。
 
-- テスト設計は **読み取り専用でドキュメントを変更しない**（test_design.dir への追加のみ）。UC 仕様書の修正は別途「曖昧さ解消」等で行う。
-- 命名規則は **spec.md 8-2**（UC 対応テスト: `UC-NNN-{ユースケース名}.spec.{拡張子}`）に厳守する。
-- テストピラミッド方針（spec セクション 14）: Unit : Integration : E2E ≈ 70 : 20 : 10。E2E は UC 1 本につき最大 2 本までを目安とする。
+6. **報告**  
+   作成ファイル一覧と UC・受入条件の対応表。続けて「分析」「チェックリスト」→ 人間承認後 **AI が phase-locks 更新** → Phase 6 へ、と案内。
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。

package/templates/.spec-runner/steps//343/203/211/343/203/241/343/202/244/343/203/263/350/250/255/350/250/210.md

@@ -1,32 +1,52 @@
-> **Phase 1: DOMAIN DESIGN（ドメイン設計）**  
-> 成果物は docs/02_ドメイン設計/ の各ファイルです。完了後、レビュー通過して .spec-runner/phase-locks.json の domain セクションに completed: true を設定します。
+---
+step_id: domain
+phase: 1
+primary_output: docs/03_ドメイン設計/
+---
+
+# ドメイン設計（Domain）
 
-## フォルダの作成
+**やること**: `docs/03_ドメイン設計/` にユビキタス言語・ドメインモデル・集約等を整備する。完了後、レビュー通過で `phase-locks.json` の `domain` に `completed: true`。
 
-- **`docs/02_ドメイン設計/` が存在しない場合**: このフェーズで **`docs/02_ドメイン設計/` を新規作成**し、その中にユビキタス言語辞書・ドメインモデル・集約の各ファイルを配置する。spec-runner はフェーズごとにフォルダを1つずつ作っていく流れを想定している。
+| 項目 | 内容 |
+|------|------|
+| **成果物** | `docs/03_ドメイン設計/` 配下の各ファイル |
+| **テンプレ** | 無い場合は `.spec-runner/templates/` から `ユビキタス言語辞書.md`, `ドメインモデル.md`, `集約.md` 等を生成してから編集 |
+| **ロック** | 設計書本文に `status: reviewed` は書かない（phase-locks のみ） |
 
 ## ユーザー入力
 
+`$ARGUMENTS`（空でなければ必ず考慮）
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
+## 前提条件
+
+| 状況 | 行動 |
+|------|------|
+| `docs/03_ドメイン設計/` が無い | このフェーズで**新規作成**し、各ファイルを配置する（フェーズごとにフォルダを1つずつ作る想定） |
+| ファイルが無い | テンプレから生成してから編集 |
 
-## 概要
+## 実行フロー
 
-1. **成果物の確認**: 以下が存在し、内容が spec.md の Phase 1 に沿っているか確認する。
-   - `docs/02_ドメイン設計/ユビキタス言語辞書.md`（禁止語欄付き）
-   - `docs/02_ドメイン設計/ドメインモデル.md`
-   - `docs/02_ドメイン設計/集約.md`（各集約に「対応テーブル」欄があること）
+1. **成果物の確認**（spec.md Phase 1 に沿っているか）
+   - `ユビキタス言語辞書.md`（禁止語欄付き）
+   - `ドメインモデル.md`
+   - `集約.md`（各集約に**「対応テーブル」**欄）
    - 必要に応じて `エンティティ.md`・`値オブジェクト.md`
 
-2. **編集・追記**: ユーザーの指示や UC で発見した新概念に基づき、上記ファイルを編集・追記する。骨格（主要集約と境界）を確定する。詳細は Grade A の UC ループで肉付けする。
+2. **編集・追記**  
+   ユーザー指示や UC で発見した新概念に基づき上記を更新。骨格（主要集約と境界）を確定。Grade A の UC ループで肉付け。  
+   不明は推測で確定せず **`[要確認: ...]`** を残す（例: `[要確認: 集約境界の決め手（更新頻度/整合性要件）]`）。
+
+3. **レビュー通過後**  
+   **AI が** `.spec-runner/phase-locks.json` の `domain` に `completed: true` と `locked_at` を設定。
 
-3. **レビュー通過**: 人間の承認を得たあと、**AI が** `.spec-runner/phase-locks.json` の `domain` に `completed: true` と `locked_at` を設定する。設計書本体に `status: reviewed` は書かない（phase-locks のみで管理）。
 ## 重要ルール
 
-- 集約.md の各集約には **対応テーブル（schema.dbml との対応）** 欄を必ず含める（spec.md  Phase 1 ゲート）。
+- **集約.md** の各集約に **対応テーブル（schema.dbml との対応）** 欄を必ず含める（spec.md Phase 1 ゲート）。
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。

package/templates/.spec-runner/steps//344/273/225/346/247/230/347/255/226/345/256/232.md

@@ -1,219 +1,173 @@
-> **Phase 3: SPECIFICATION（UC 仕様書）**  
-> UC 仕様書を docs/05_ユースケース仕様/ に作成したのち、clarify（曖昧さ解消）→ analyze / checklist → review-pass の品質フローに進みます。
+---
+step_id: spec
+phase: 3
+primary_output: docs/02_ユースケース仕様/<カテゴリ>/UC-N-xxx.md
+---
 
-**main にいる場合**: このステップで**必ず UC 用ブランチを作成してから**仕様を書く。main で直接編集しない。
+# ユースケース仕様（UC 仕様書）
 
-## フォルダの作成
+**やること**: 機能説明（`$ARGUMENTS`）から UC ブランチと UC 仕様書を作成し、テンプレに沿って埋める。その後 clarify → analyze / checklist → review-pass。
 
-- **`docs/05_ユースケース仕様/`** が存在しない場合: このフェーズで **`docs/05_ユースケース仕様/` を新規作成**する。**カテゴリごとにフォルダ**（例: タスク管理、認証）を切り、その中に **UC-NNN-xxx.md を 1 本ずつ**置く。`create-uc-branch.sh` 実行時にカテゴリを指定すると、そのカテゴリフォルダ内に UC 仕様書が作成される。
+| 項目 | 内容 |
+|------|------|
+| **成果物** | `docs/02_ユースケース仕様/<カテゴリ>/UC-N-xxx.md`（1 UC = 1 本） |
+| **main** | **必ず UC 用ブランチを作成してから**仕様を書く。main で直接編集しない |
+| **品質フロー** | clarify → analyze / checklist → review-pass |
+| **判断ログ（任意）** | `docs/02_.../<カテゴリ>/判断記録/UC-N-MMDD-題名.md`。テンプレ: `.spec-runner/templates/UC-N-MMDD-判断記録テンプレ.md` |
 
 ## ユーザー入力
 
+`$ARGUMENTS` が機能説明。空でコマンドしていない限り、繰り返し入力を求めない。
+
 ```text
 $ARGUMENTS
 ```
 
-（空でない場合）処理を進める前にユーザー入力を**必ず**考慮すること。
-
-## 概要
-
-トリガーメッセージでユーザーが「仕様策定」コマンドの後に続けて入力したテキスト**が**機能説明である。`$ARGUMENTS` がそのまま表示されていても、この会話では常に利用可能であるとみなす。ユーザーが空でコマンドを実行していない限り、繰り返し入力を求めてはならない。
-
-その機能説明に基づき、以下を実行する。
-
-1. **ブランチ用の短い名前（2〜4語）を生成する**
-   - 機能説明を分析し、意味のあるキーワードを抽出する
-   - 機能の本質を表す 2〜4 語の短い名前を作成する
-   - 可能なら「動詞-名詞」形式（例: "add-user-auth", "fix-payment-bug"）
-   - 技術用語・略語（OAuth2, API, JWT 等）はそのまま残す
-   - 簡潔かつ、一見して分かる程度に説明的にする
-   - 例:
-     - 「ユーザー認証を追加したい」→ "user-auth"
-     - 「API に OAuth2 連携を実装する」→ "oauth2-api-integration"
-     - 「分析用ダッシュボードを作る」→ "analytics-dashboard"
-     - 「決済処理のタイムアウトバグを修正」→ "fix-payment-timeout"
-
-2. **UC 用ブランチと仕様書を spec-runner で作成する。**
-
-   - 次に使う UC 番号を取得: `.spec-runner/scripts/branch/uc-next-id.sh` を実行し、出力（例: UC-001）を UC_ID とする。
-   - 機能説明から 2〜4 語の短い名前（kebab-case）を決め、DESC とする（例: order-placement, user-auth）。
-   - ブランチと UC 仕様書を作成: `.spec-runner/scripts/branch/create-uc-branch.sh "$UC_ID" "$DESC" --json` を実行する。
-   - 出力 JSON から BRANCH_NAME と SPEC_FILE（＝FEATURE_SPEC）を取得する。SPEC_FILE が UC 仕様書のパス（docs/05_ユースケース仕様/<カテゴリ>/UC-NNN-xxx.md）である。
-   - このスクリプトは機能ごとに 1 回だけ実行する。
-   - "I'm Groot" のようにシングルクォートを含む場合はエスケープ（例: 'I'\''m Groot'）またはダブルクォートを使う。
-
-3. 必須セクションを把握するため `.spec-runner/templates/UC-NNN-ユースケース名.md` を読み込む。
-
-4. 以下の実行フローに従う。
-
-    1. 入力からユーザー説明をパースする。空なら ERROR「機能説明が指定されていません」
-    2. 説明から重要概念を抽出する（アクター、アクション、データ、制約）
-    3. 不明な点について:
-       - 文脈と業界標準に基づいて合理的に推測する
-       - 次の場合のみ [要確認: 具体的な質問] を付ける:
-         - 選択が機能スコープや UX に大きく影響する
-         - 解釈が複数あり、影響が異なる
-         - 妥当なデフォルトが存在しない
-       - **上限: [要確認] は合計 3 個まで**
-       - 影響の大きい順: スコープ > セキュリティ/プライバシー > UX > 技術詳細
-    4. 「ユーザーシナリオとテスト」セクションを埋める。明確なユーザーフローがなければ ERROR「ユーザーシナリオを特定できません」
-    5. 機能要件を生成する。各要件はテスト可能であること。未指定の詳細は妥当なデフォルトを使い、仮定は「仮定」セクションに記載する
-    6. 成功基準を定義する。測定可能で技術に依存しない結果にする。定量的指標（時間・性能・量）と定性的指標（満足度・タスク完了）の両方を含める。実装詳細なしで検証可能であること
-    7. （データが関わる場合）主要エンティティを特定する
-    8. 戻り: SUCCESS（仕様は計画の準備完了）
-
-5. テンプレート構造に従い、機能説明（引数）から得た具体内容でプレースホルダを置き換え、セクション順と見出しを保ったまま SPEC_FILE に仕様を書き込む。
-
-6. **仕様品質検証**: 初稿を書いた後、品質基準で検証する。
-
-   a. **仕様品質チェックリスト（任意）**: checklists を使う場合のみ、`FEATURE_DIR/checklists/requirements.md` に検証項目のチェックリストを生成する。**UC のみで進める場合は checklists/ を作らなくてよい。** 以下は作成する場合の例。
-
-      ```markdown
-      # 仕様品質チェックリスト: [機能名]
-      
-      **目的**: 計画に進む前に仕様の完全性・品質を検証する
-      **作成日**: [日付]
-      **機能**: [spec.md へのリンク]
-      
-      ## コンテンツ品質
-      
-      - [ ] 実装詳細（言語・フレームワーク・API）が含まれていない
-      - [ ] ユーザー価値とビジネスニーズに焦点がある
-      - [ ] 非技術のステークホルダー向けに書かれている
-      - [ ] 必須セクションがすべて完了している
-      
-      ## 要件の完全性
-      
-      - [ ] [要確認] マーカーが残っていない
-      - [ ] 要件がテスト可能で曖昧でない
-      - [ ] 成功基準が測定可能
-      - [ ] 成功基準が技術に依存しない（実装詳細なし）
-      - [ ] 受入シナリオがすべて定義されている
-      - [ ] エッジケースが特定されている
-      - [ ] スコープが明確に境界づけされている
-      - [ ] 依存関係と仮定が特定されている
-      
-      ## 機能の準備状況
-      
-      - [ ] 全機能要件に明確な受入基準がある
-      - [ ] ユーザーシナリオが主要フローをカバーしている
-      - [ ] 成功基準で定義した測定可能な結果を満たしている
-      - [ ] 仕様に実装詳細が混入していない
-      
-      ## 注記
-      
-      - 未完了の項目は「曖昧さ解消」または「実装計画」の前に仕様を更新すること
-      ```
-
-   b. **検証チェックを実行**: 各チェック項目に対して仕様を確認し、合格/不合格を判定し、見つかった問題を（該当仕様セクションを引用して）記録する。
-
-   c. **検証結果の扱い**:
-
-      - **全項目合格**: チェックリストを完了とし、ステップ 7 へ進む
-
-      - **不合格がある場合（[要確認] 以外）**:
-        1. 不合格項目と具体的な問題を列挙する
-        2. 各問題に対応するよう仕様を更新する
-        3. 全項目が合格するまで検証を繰り返す（最大 3 回）
-        4. 3 回後も不合格が残る場合は、チェックリストの注記に残りを記載し、ユーザーに警告する
-
-      - **[要確認] マーカーが残っている場合**:
-        1. 仕様から [要確認: ...] をすべて抽出する
-        2. **上限確認**: 3 個を超える場合は、スコープ/セキュリティ/UX の影響が大きい 3 個だけ残し、残りは合理的に推測する
-        3. 必要な確認ごと（最大 3 件）、次の形式でユーザーに選択肢を提示する:
-
-           ```markdown
-           ## 質問 [N]: [トピック]
-           
-           **文脈**: [該当仕様セクションの引用]
-           
-           **確認したいこと**: [要確認マーカーからの具体的な質問]
-           
-           **回答案**:
-           
-           | 選択肢 | 回答 | 影響 |
-           |--------|------|------|
-           | A | [第1案] | [機能への影響] |
-           | B | [第2案] | [機能への影響] |
-           | C | [第3案] | [機能への影響] |
-           | 独自 | 自分で回答する | [独自入力の方法] |
-           
-           **選択**: _[ユーザー応答を待つ]_
-           ```
-
-        4. **重要 - 表の書式**: マークダウン表のパイプを揃え、セルは `| 内容 |` のようにスペースを入れる。区切り線は `|--------|` で 3 本線以上。プレビューで正しく表示されることを確認する
-        5. 質問は Q1, Q2, Q3 と連番（最大 3 件）
-        6. 回答を待つ前に全質問を一度に提示する
-        7. ユーザーが全質問への選択を返すまで待つ（例: "Q1: A, Q2: 独自 - [詳細], Q3: B"）
-        8. 各 [要確認] をユーザーの選択または入力で置き換えて仕様を更新する
-        9. 確認がすべて解消されたら再度検証する
-
-   d. **チェックリスト更新**: 検証の反復ごとに、チェックリストファイルを現在の合格/不合格で更新する
-
-7. 完了報告: ブランチ名、仕様ファイルパス、チェックリスト結果、次のフェーズ（「曖昧さ解消」または「実装計画」）への準備状況を報告する。
-
-**注:** スクリプトは書き込み前に新規ブランチの作成・チェックアウトと仕様ファイルの初期化を行う。
-
-## ガイドライン
-
-- **WHAT**（何を）と **WHY**（なぜ）に集中する
-- HOW（実装方法）は書かない（技術スタック・API・コード構造なし）
-- 開発者ではなくビジネス担当者向けに書く
-- 仕様に埋め込んだチェックリストは作らない。別コマンドで行う
-
-### セクション要件
-
-- **必須セクション**: 全機能で必ず完了する
-- **任意セクション**: 機能に該当する場合のみ含める
-- 該当しないセクションは「N/A」で残さず削除する
-
-### AI 生成時の注意
-
-ユーザープロンプトから仕様を作成する際:
-
-1. **合理的に推測する**: 文脈・業界標準・一般的なパターンで穴を埋める
-2. **仮定を記録する**: 妥当なデフォルトを「仮定」セクションに書く
-3. **確認は絞る**: [要確認] は最大 3 個。次のような重要な判断にだけ使う:
-   - 機能スコープや UX に大きく影響する
-   - 複数の解釈があり影響が異なる
-   - 妥当なデフォルトがない
-4. **優先順位**: スコープ > セキュリティ/プライバシー > UX > 技術詳細
-5. **テスター目線**: 曖昧な要件は「テスト可能で曖昧でない」チェックで不合格にできるようにする
-6. **確認が必要になりやすい領域**（妥当なデフォルトがない場合のみ）:
-   - 機能スコープと境界（含める/含めないユースケース）
-   - ユーザー種別と権限（解釈が複数あり得る場合）
-   - セキュリティ/コンプライアンス要件（法的・金銭的に重要な場合）
-
-**推測してよい例**（これらについては質問しない）:
-
-- データ保持: ドメインの業界標準
-- 性能目標: 特記がなければ一般的な Web/モバイルの期待値
-- エラー処理: 分かりやすいメッセージと適切なフォールバック
-- 認証方式: Web アプリではセッションまたは OAuth2
-- 連携パターン: プロジェクトに合わせる（REST/GraphQL、ライブラリは関数呼び出し、CLI は引数など）
-
-### 成功基準のガイドライン
-
-成功基準は次を満たすこと:
-
-1. **測定可能**: 具体的な指標（時間・割合・件数・率）を含める
-2. **技術に依存しない**: フレームワーク・言語・DB・ツールに言及しない
-3. **ユーザー中心**: ユーザー/ビジネス視点の結果であり、システム内部ではない
-4. **検証可能**: 実装詳細を知らなくてもテスト/検証できる
-
-**良い例**:
-
-- 「ユーザーは 3 分以内にチェックアウトを完了できる」
-- 「システムは 1 万同時ユーザーをサポートする」
-- 「検索の 95% が 1 秒以内に結果を返す」
-- 「タスク完了率が 40% 向上する」
-
-**悪い例**（実装寄り）:
-
-- 「API 応答が 200ms 未満」（技術的すぎる → 「ユーザーが結果を即座に見る」など）
-- 「DB が 1000 TPS を処理」（実装詳細 → ユーザー向け指標にする）
-- 「React コンポーネントが効率的に描画」（フレームワーク依存）
-- 「Redis キャッシュヒット率 80% 以上」（技術依存）
+## フォルダの作成
+
+- **`docs/02_ユースケース仕様/`** が無ければ新規作成。**カテゴリごとにフォルダ**（例: タスク管理、認証）を切り、その中に **UC-N-xxx.md を 1 本**。
+- `uc-next-start.sh` でカテゴリ指定するとそのフォルダ内に作成される。
+
+## 実行フロー
+
+### 1. ブランチ用短名（2〜4 語）
+
+- 機能説明からキーワード抽出。**ブランチ名は ASCII のみ**、kebab-case（例: order-placement, user-auth）。
+- **UC ファイル名は日本語**（`UC-<N>-<題名>.md`）。未確定は `要確認`。
+- 技術略語（OAuth2, API, JWT）はそのまま。日本語のみで DESC が決まらない場合は日本語を渡してよい（スクリプトが `uc-N` 等にフォールバック）。
+- 例: 「ユーザー認証」→ user-auth / 「OAuth2 API」→ oauth2-api-integration 等。
+
+### 2. ブランチと仕様の作成
+
+- `.spec-runner/scripts/branch/uc-next-start.sh [UC-ID] "$DESC" [カテゴリ] [--yes]`
+- UC-ID 省略で自動採番。カテゴリで配置先が決まる（カテゴリ名は日本語可）。**機能ごとに 1 回だけ**。
+- シングルクォートはエスケープ（例: `'I'\''m Groot'`）またはダブルクォート。
+
+### 3. テンプレ読込
+
+`.spec-runner/templates/UC-N-ユースケース名.md` で必須セクションを把握。
+
+### 4. 本文生成の内訳
+
+1. 入力パース。空なら ERROR「機能説明が指定されていません」
+2. 重要概念（アクター・アクション・データ・制約）
+3. 不明点: **推測で確定しない** → **`[要確認: ...]`**。付けるのは影響大・解釈複数・デフォルト無しのときのみ。**上限 3 個**。優先: スコープ > セキュリティ > UX > 技術詳細
+4. 「ユーザーシナリオとテスト」を埋める。フロー特定できなければ ERROR
+5. 機能要件（テスト可能）。仮定は「仮定」セクションへ
+6. 成功基準（測定可能・技術非依存・定量+定性）
+7. データが関わる場合は主要エンティティ
+8. SUCCESS（計画の準備完了）
+
+### 5. 書き込み
+
+テンプレ構造を保ち、プレースホルダを具体内容で置換し **SPEC_FILE** に保存。
+
+### 6. 仕様品質検証
+
+**a. チェックリスト（任意）**  
+checklists を使う場合のみ `FEATURE_DIR/checklists/requirements.md` を生成。UC のみなら **checklists/ 不要**。作成例は **付録 A**。
+
+**b.** 各チェック項目で合格/不合格を判定し問題を記録。
+
+**c. 結果の扱い**
+
+- 全合格 → ステップ 7 へ
+- 不合格（[要確認] 以外）: 列挙→仕様更新→最大 3 回反復。残りは注記と警告
+- **[要確認] 残り**: 抽出→3 個超なら影響大 3 個に整理→ユーザーへ質問表（**付録 B** 形式）。Q1–Q3 まで一括提示→回答後に置換→再検証
+
+**d.** 反復ごとにチェックリストファイルを更新
+
+### 7. 完了報告
+
+ブランチ名・仕様パス・チェックリスト結果・次フェーズ（曖昧さ解消 / 実装計画）の準備状況。
+
+**注**: スクリプトは書き込み前にブランチ作成・チェックアウトと仕様の初期化を行う。
+
+## 付録 A: 仕様品質チェックリスト例
+
+```markdown
+# 仕様品質チェックリスト: [機能名]
+
+**目的**: 計画に進む前に仕様の完全性・品質を検証する
+**作成日**: [日付]
+**機能**: [spec.md へのリンク]
+
+## コンテンツ品質
+
+- [ ] 実装詳細（言語・フレームワーク・API）が含まれていない
+- [ ] ユーザー価値とビジネスニーズに焦点がある
+- [ ] 非技術のステークホルダー向けに書かれている
+- [ ] 必須セクションがすべて完了している
+
+## 要件の完全性
+
+- [ ] [要確認] マーカーが残っていない
+- [ ] 要件がテスト可能で曖昧でない
+- [ ] 成功基準が測定可能
+- [ ] 成功基準が技術に依存しない（実装詳細なし）
+- [ ] 受入シナリオがすべて定義されている
+- [ ] エッジケースが特定されている
+- [ ] スコープが明確に境界づけされている
+- [ ] 依存関係と仮定が特定されている
+
+## 機能の準備状況
+
+- [ ] 全機能要件に明確な受入基準がある
+- [ ] ユーザーシナリオが主要フローをカバーしている
+- [ ] 成功基準で定義した測定可能な結果を満たしている
+- [ ] 仕様に実装詳細が混入していない
+
+## 注記
+
+- 未完了の項目は「曖昧さ解消」または「実装計画」の前に仕様を更新すること
+```
+
+## 付録 B: [要確認] 用質問表フォーマット
+
+```markdown
+## 質問 [N]: [トピック]
+
+**文脈**: [該当仕様セクションの引用]
+
+**確認したいこと**: [要確認マーカーからの具体的な質問]
+
+**回答案**:
+
+| 選択肢 | 回答 | 影響 |
+|--------|------|------|
+| A | [第1案] | [機能への影響] |
+| B | [第2案] | [機能への影響] |
+| C | [第3案] | [機能への影響] |
+| 独自 | 自分で回答する | [独自入力の方法] |
+
+**選択**: _[ユーザー応答を待つ]_
+```
+
+表のパイプを揃え、区切りは `|--------|` 以上。**質問は Q1–Q3 を一度に出し**、全回答後に仕様を更新。
+
+## 付録 C: ガイドライン
+
+- **WHAT / WHY** に集中。**HOW（実装）**は書かない
+- ビジネス担当者向け。仕様に埋め込みチェックリストは作らない（別コマンド）
+- **必須セクション**は全機能で完了。**任意**は該当時のみ。N/A で残さず削除
+
+### AI 生成時
+
+1. 推測で確定しない → `[要確認]`
+2. 仮に進める場合のみ「仮定」に明示
+3. [要確認] は最大 3（スコープ・解釈・デフォルト無しの重要判断のみ）
+4. 優先: スコープ > セキュリティ > UX > 技術詳細
+5. テスター目線で曖昧要件は不合格にできるように
+
+**推測してよい例**（通常は質問しない）: データ保持の業界標準、一般 Web 性能目標、分かりやすいエラー表現、Web ならセッション/OAuth2、連携は REST/GraphQL 等プロジェクト準拠。
+
+### 成功基準
+
+- 測定可能（時間・割合・件数等）、技術非依存、ユーザー/ビジネス結果、実装を知らず検証可能
+
+**良い例**: 「3 分以内にチェックアウト」「1 万同時ユーザー」「検索 95% が 1 秒以内」
+
+**悪い例**: API 200ms、DB TPS、React 描画、Redis ヒット率（実装寄り）
 
 ---
-完了したら次のステップに進む。
+**次**: 完了後、次のステップへ進む。