quick-design

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation,workflow

クイックデザイン

これは、完全な GDD を必要としない変更向けの軽量な設計パスです。 /design-system を使った完全な GDD の作成は、より大規模なパスです。このスキルは、実装が約 1 週間以内に収まる作業に使用してください。調整、軽微な挙動の変更、既存システムへの小規模な追加、完全なドキュメントを作るほどではない独立した機能などが該当します。ほとんどの調整は数時間で済みます。1 週間という上限は、新規の小規模システム（以下のカテゴリーを参照）に適用されます。

出力： design/quick-specs/[name]-[date].md

実行するタイミング： /design-system を使うほど大きくはないものの、文書化した根拠なしで実装するには重要すぎる変更がある場合はいつでも実行します。

---

すべての AskUserQuestion 呼び出しは .claude/docs/automation-modes.md に従います（共同作業での質問は常に実施・ガイド付きは主要な変更のみ・自律モードでは記録して続行します。automation_always_ask カテゴリーでは常に質問します）。

1. 変更を分類する

まず引数を読み、変更がどのカテゴリーに当てはまるかを判断します。

• 調整 — 挙動を変えずに、既存システムの数値やバランス値を変更します（最も簡易なパス）。例：「ジャンプの高さを 5 ユニットから 6 ユニットに増やす」「敵の巡回速度を 10% 下げる」。
• 微調整 — 新しい状態、分岐、システムを導入せずに、既存システムの挙動を小規模に変更します。例：「ダッシュの 1 フレーム目に無敵状態にする」「コンボからローリングへのキャンセルを可能にする」。
• 追加 — 1～2 個の新しい状態やインタラクションを導入する可能性がある、小規模なメカニクスを既存システムに追加します。例：「ブロックのメカニクスにパリィの受付時間を追加する」「基本攻撃に溜め攻撃を追加する」。
• 新規の小規模システム — 既存の GDD がなく、実装作業が約 1 週間未満で済む規模の独立した機能です。例：「実績ポップアップシステム」「シンプルな昼夜のビジュアルサイクル」。

変更がこれらのカテゴリーに当てはまらない場合（システム間に大きく依存する新しいシステムを導入する、実装に 1 週間を超える、または既存システムの中核ルールを根本的に変える場合）は、ここで止めて /design-system に案内します。判定：リダイレクト — この変更には /design-system を使用してください。

引数がない場合は、ユーザーに変更内容を（プレーンテキストのプロンプトで）説明してもらい、上記の基準で分類します。

推定した分類を AskUserQuestion で提示します。

• プロンプト：「これは**[推定タイプ]**に分類しました — [簡潔な理由]。この分類で正しいですか？」
• 選択肢：
  • [A] はい — [推定タイプ]で正しい
  • [B] 調整 — 数値やバランス値のみを変更
  • [C] 微調整 — 既存システムの挙動を小規模に変更
  • [D] 追加 — 既存システムに小規模なメカニクスを追加
  • [E] 新規の小規模システム — 1 週間未満の作業で済む独立した機能
  • [F] 規模が大きすぎる — /design-system に案内する

[F] の場合：停止します。判定：リダイレクト — この変更には /design-system を使用してください。 それ以外の場合：選択されたタイプで続行します。

---

2. コンテキストの確認

何かを起草する前に、関連するコンテキストを読みます。GDD とシステムインデックスをセクションごとに確認します。Grep ツール（パターン ^#、コンテンツモード）で必要な見出しを探し、Read ツールで offset と limit を指定して該当範囲を読みます。

• design/gdd/ を検索し、この変更に最も関連する GDD を探します。この変更の影響を受けるセクションを読みます。このシステムを扱う GDD がない場合（通常は workflow: minimal のときで、この場合は design/game-brief.md とストーリーがデザイン記録となります）、代わりにブリーフの該当箇所と、この変更に関係するストーリーを読み、「No GDD for [system] — using the brief and [story path]」と報告し、ブリーフを仕様の GDD Reference として記載します。
• design/gdd/systems-index.md が存在するか確認します。存在する場合は、それを読んで、このシステムが依存関係グラフのどこに位置し、どのティアに属するかを把握します。存在しない場合は、「No systems index found — skipping dependency tier check.」と記載して続行します。
• design/quick-specs/ を確認し、このシステムに関する過去のクイックスペックを探します。それらと矛盾しないようにします。
• Tuning の変更の場合は、assets/data/ も確認し、関連する値を保持するデータファイルを探します。

見つかった内容を報告します。「Found GDD at [path]. Relevant section: [section name]. Prior quick specs for this system: [each path, and whether it agrees or conflicts with this change — or "none"].」合意している場合も過去のスペックを明記します。「no conflicts」だけでは「過去のスペックなし」と同じ意味に読めてしまいます。

---

3. クイックデザイン仕様書の草案作成

変更カテゴリに適した仕様書フォーマットを使います。

Tuning の変更の場合

単一の表を作成します。

# Quick Design Spec: [Title]

**Type**: Tuning
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md` — Tuning Knobs section
**Date**: [today]

## Change

| Parameter | Old Value | New Value | Rationale |
|-----------|-----------|-----------|-----------|
| [param]   | [old]     | [new]     | [why]     |

## Tuning Knob Mapping

Maps to GDD Tuning Knob: [knob name and its documented range].
New value is [within / at the edge of / outside] the documented range.
[If outside: explain why the range should be extended.]

## Acceptance Criteria

- [ ] [Parameter] reads [new value] from `assets/data/[file]`
- [ ] Behavior difference is observable in [specific context]
- [ ] No regression in [related behavior]

Tweak および Addition の変更の場合

# Quick Design Spec: [Title]

**Type**: [Tweak / Addition]
**System**: [System name]
**GDD Reference**: `design/gdd/[filename].md`
**Date**: [today]

## Change Summary

[1-2 sentences describing what changes and why.]

## Motivation

[Why is this change needed? What player experience problem does it solve?
Reference the relevant MDA aesthetic or player feedback if applicable.]

## Design Delta

Current GDD says (quoting `design/gdd/[filename].md`, [section]):

> [exact quote of the relevant rule or description]

This spec changes that to:

[New rule or description, written with the same precision as a GDD Detailed
Rules section. A programmer should be able to implement from this text alone.]

## New Rules / Values

[Full unambiguous statement of the replacement content. If this introduces
new states, list them. If it introduces new parameters, define their ranges.]

## Affected Systems

| System | Impact | Action Required |
|--------|--------|-----------------|
| [system] | [how it is affected] | [update GDD / update data file / no action] |

## Acceptance Criteria

- [ ] [Specific, testable criterion 1]
- [ ] [Specific, testable criterion 2]
- [ ] [Specific, testable criterion 3]
- [ ] No regression: [the original behavior this must not break]

## GDD Update Required?

[Yes / No]
[If yes: which file, which section, and what the update should say.]

New Small System の変更の場合

GDD の構成を簡略化して使います。直接必要なセクションのみ含めます。システム上特に必要でない限り、Player Fantasy、完全な Formulas、Edge Cases は省略します。

# Quick Design Spec: [Title]

**Type**: New Small System
**Scope**: [1-2 sentence description of what this system does and doesn't do]
**Date**: [today]
**Estimated Implementation**: [hours]

## Overview

[One paragraph a new team member could understand. What does this system do,
when does it activate, and what does it produce?]

## Core Rules

[Unambiguous rules for the system. Use numbered lists for sequential behavior
and bullet lists for conditions. Be precise enough that a programmer can
implement without asking questions.]

## Tuning Knobs

| Knob | Default | Range | Category | Rationale |
|------|---------|-------|----------|-----------|
| [name] | [value] | [min–max] | [feel/curve/gate] | [why this default] |

All values must live in `assets/data/[appropriate-file].json`, not hardcoded.

## Acceptance Criteria

- [ ] [Functional criterion: does the right thing]
- [ ] [Functional criterion: handles the edge case]
- [ ] [Experiential criterion: feels right — what a playtest validates]
- [ ] [Regression criterion: does not break adjacent system]

## Systems Index

This system is not currently in `design/gdd/systems-index.md`.
[If it should be added: suggest which layer and priority tier.]
[If it is too small to track: state "This system is below systems-index
tracking threshold — quick spec is sufficient."]

---

4. 承認とファイルへの保存

草案全体をユーザーに提示します。その後、AskUserQuestion を使います。

• プロンプト：「Here's the Quick Design Spec draft. How do you want to proceed?」
• 選択肢：
  • [A] Approve — write it as shown
  • [B] Revise — I'll describe what to change
  • [C] This grew too large — redirect to /design-system instead

[B] の場合：変更の要望を受け取り、草案を修正して、このウィジェットを再提示します。 [C] の場合：停止します。判定：REDIRECTED — この変更には /design-system を使用します。

[A] の場合：「このクイックデザイン仕様書を design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md に書き込んでもよいですか？」と尋ねます。

ファイル名には今日の日付を使います。タイトルは変更内容を表す kebab-case の説明にします（例：jump-height-tuning-2026-03-10、parry-window-addition-2026-03-10）。

許可された場合、存在しなければ design/quick-specs/ ディレクトリを作成してから、ファイルを書き込みます。

GDD の更新が必要な場合（仕様書で明示）、クイックスペックを書き込んだ後に別途尋ねます。

「この仕様書は [System Name] のルールを変更します。design/gdd/[filename].md の [section name] セクションを更新してもよいですか？」

尋ねる前に、変更する正確なテキストを提示します（変更前と変更後）。明示的な承認なしに GDD を編集してはいけません。

---

5. 引き継ぎ

ファイルを書き込んだ後、次を出力します。

Quick Design Spec written to: design/quick-specs/[filename].md
Type: [Tuning / Tweak / Addition / New Small System]
System: [system name]
GDD update: [Required — pending approval / Applied / Not required]

Next step: This spec is ready for `/story-readiness` validation before
implementation (at `workflow: minimal`, go straight to `/dev-story`). Reference this spec in the story's GDD Reference field.

パイプラインに関する注記

判定：完了 — 簡易設計仕様書を作成し、実装の準備が整いました。

簡易設計仕様書は、設計上、/design-review と /review-all-gdds を省略します。これは、完全なレビュー・パイプラインのコストが変更そのもののリスクを上回る、小規模で低リスク、かつ範囲が明確な変更を対象としています。

次のいずれかに該当する場合は、完全なパイプラインに切り替えてください。

• システムインデックスに追加すべき新しいシステムを導入する変更
• システム間の動作や、あるシステムと他のシステムとの契約を大幅に変更する変更
• ゲームのMDA上の美的バランスに影響する、新しいプレイヤー向けのメカニクスを導入する変更
• 実装に1週間を超える作業が見込まれる場合

その場合は、「この変更は簡易仕様書の範囲を超えています。完全なGDDを作成するために、/design-system の使用をおすすめします。」

---

次の推奨ステップ

• 実装を始める前に、/story-readiness [story-path] を実行してストーリーを検証します（rigor: minimal の場合は省略し、/dev-story を直接実行します）。ストーリーのGDD Referenceフィールドで、この仕様書を参照してください
• レディネスチェックに合格したら、/dev-story [story-path] を実行して実装します
• 変更が想定より大きい場合は、/design-system [system-name] を実行して完全なGDDを作成します