quick-design

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

快速设计

这是用于无需完整 GDD 的变更的轻量级设计路径。 通过 /design-system 编写完整 GDD 属于重量级路径。对于实施工作约一周以内的任务，请使用此技能——例如调整参数、微调行为、为现有系统添加小功能，或规模太小、不值得编写完整文档的独立功能。大多数调整只需几小时；一周是新建小型系统的上限（见下文类别）。

输出： 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，且实施工作约一周以内。例如：“成就弹窗系统”，“简单的昼夜视觉循环”。

如果变更不属于这些类别——引入了与其他系统存在大量交叉依赖的新系统、实施时间超过一周，或从根本上改变了现有系统的核心规则——请停止并转到 /design-system。判定结果：已转向其他路径——对此变更使用 /design-system。

如果没有参数，请让用户描述变更（纯文本提示词），然后根据上述标准进行分类。

使用 AskUserQuestion 呈现推断的分类：

• 提示：“我将其归类为 [inferred type]——[brief reason]。这样正确吗？”
• 选项：
  • [A] 是——[inferred type] 正确
  • [B] 调整参数——仅更改数字或平衡数值
  • [C] 微调——对现有系统进行小幅行为变更
  • [D] 添加功能——为现有系统添加一项小机制
  • [E] 新建小型系统——独立功能，工作量不超过一周
  • [F] 规模太大——将我转到 /design-system

如果选择 [F]：停止。判定结果：已转向其他路径——对此变更使用 /design-system。 否则：按选定的类型继续。

---

2. 上下文扫描

起草任何内容之前，请先阅读相关上下文。按章节阅读 GDD 和系统索引：使用 Grep 工具（模式 ^#，内容模式）查找所需标题，再通过指定偏移量和行数读取这些范围。

• 在 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]：询问 "May I write this Quick Design Spec to 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（已在规格中标记），请在写入快速规格后单独询问：

"This spec modifies rules in [System Name]. May I update design/gdd/[filename].md — specifically the [section name] section?"

提问前，展示将要修改的确切文本（旧内容与新内容）。未经明确批准，不得修改 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 美学平衡、面向玩家的机制
• 实施工作预计超过一周

遇到这些情况时：「此变更已超出快速规范的适用范围。我建议使用 /design-system 为其编写完整的 GDD。」

---

推荐的后续步骤

• 运行 /story-readiness [story-path]，在开始实施前验证故事（rigor: minimal 时跳过 — 直接运行 /dev-story），并在故事的 GDD Reference 字段中引用此规范
• 故事通过就绪检查后，运行 /dev-story [story-path] 进行实施
• 如果变更规模超出预期，运行 /design-system [system-name]，改为编写完整的 GDD