Back to Details

quick-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Quick Design

快速设计

This is the lightweight design path for changes that don't need a full GDD. Full GDD authoring via 
/design-system
is the heavyweight path. Use this skill for work under approximately 4 hours of implementation — tuning adjustments, minor behavioral tweaks, small additions to existing systems, or standalone features too small to warrant a full document.
Output: 
design/quick-specs/[name]-[date].md
When to run: Anytime a change is too small for 
/design-system
but too meaningful to implement without a written rationale.
这是针对无需完整GDD的改动所设计的轻量级设计流程。 通过
/design-system
撰写完整GDD是重量级流程。当改动的实现工作量约为4小时以内时，使用本skill——包括参数调优、微小行为调整、现有系统的小功能添加，或是无需完整文档的独立小型功能。
输出文件：
design/quick-specs/[name]-[date].md
运行时机：当改动过小无需使用
/design-system
，但又需要书面依据才能实施时，随时可以运行。

1. Classify the Change

1. 分类改动类型

First, read the argument and determine which category this change falls into:
  • Tuning — changing numbers or balance values in an existing system with no behavioral change (most minimal path). Example: "increase jump height from 5 to 6 units", "reduce enemy patrol speed by 10%".
  • Tweak — a small behavioral change to an existing system that introduces no new states, branches, or systems. Example: "make dash invincible on frame 1", "allow combo to cancel into roll".
  • Addition — adding a small mechanic to an existing system that may introduce 1-2 new states or interactions. Example: "add a parry window to the block mechanic", "add a charge variant to the basic attack".
  • New Small System — a standalone feature small enough that it has no existing GDD and is under approximately one week of implementation work. Example: "achievement popup system", "simple day/night visual cycle".
If the change does NOT fit these categories — it introduces a new system with significant cross-system dependencies, requires more than one week of implementation, or fundamentally alters an existing system's core rules — stop and redirect to 
/design-system
instead.
If there is no argument, ask the user to describe the change (plain text prompt), then classify it using the criteria above.
Present the inferred classification using 
AskUserQuestion
:
  • Prompt: "I've classified this as [inferred type] — [brief reason]. Is that correct?"
  • Options: 
    • [A] Yes — [inferred type] is correct
    • [B] Tuning — changing numbers or balance values only
    • [C] Tweak — small behavioral change to an existing system
    • [D] Addition — adding a small mechanic to an existing system
    • [E] New Small System — standalone feature, under one week of work
    • [F] This is too large — redirect me to /design-system
If [F]: stop. Verdict: REDIRECTED — use 
/design-system
for this change. Otherwise: proceed with the selected type.
首先，阅读改动说明并确定其所属类别：
  • 调优（Tuning）——仅修改现有系统中的数值或平衡参数，不改变行为逻辑（最简化流程）。示例："将跳跃高度从5单位提升至6单位"、"将敌人巡逻速度降低10%"。
  • 微调（Tweak）——对现有系统进行微小行为调整，不引入新状态、分支或系统。示例："让冲刺动作在第1帧处于无敌状态"、"允许连招取消并衔接翻滚"。
  • 新增（Addition）——为现有系统添加微小机制，可能引入1-2个新状态或交互。示例："为格挡机制添加招架窗口"、"为基础攻击添加蓄力变体"。
  • 小型新系统（New Small System）——独立功能，规模足够小，无现有GDD，且实现工作量约为一周以内。示例："成就弹窗系统"、"简单的昼夜视觉循环"。
如果改动不符合上述类别——比如引入具有显著跨系统依赖的新系统、实现工作量超过一周，或是从根本上改变现有系统的核心规则——请停止操作，转而使用
/design-system
。
如果没有改动说明，请要求用户描述改动内容（纯文本提示），然后根据上述标准进行分类。
使用
AskUserQuestion
呈现推断出的分类：
  • 提示语："我将此改动归类为**[推断类型]**——[简要理由]。是否正确？"
  • 选项： 
    • [A] 是——[推断类型]分类正确
    • [B] 调优——仅修改数值或平衡参数
    • [C] 微调——对现有系统进行微小行为调整
    • [D] 新增——为现有系统添加微小机制
    • [E] 小型新系统——独立功能，工作量一周以内
    • [F] 改动规模过大——转至/design-system
若选择[F]：停止操作。结论：已重定向——请使用
/design-system
处理此改动。 否则：根据所选类型继续操作。

2. Context Scan

2. 上下文扫描

Before drafting anything, read the relevant context:
  • Search 
    design/gdd/
    for the GDD most relevant to this change. Read the sections that this change would affect.
  • Check whether 
    design/gdd/systems-index.md
    exists. If it does, read it to understand where this system sits in the dependency graph and what tier it belongs to. If it does not exist, note "No systems index found — skipping dependency tier check." and continue.
  • Check 
    design/quick-specs/
    for any prior quick specs that touched this system — avoid contradicting them.
  • If this is a Tuning change, also check 
    assets/data/
    for the data file that holds the relevant values.
Report what was found: "Found GDD at [path]. Relevant section: [section name]. No conflicting quick specs found." (or note any conflicts found.)
在起草文档前，先查阅相关上下文：
  • 在
    design/gdd/
    中搜索与本次改动最相关的GDD，阅读改动涉及的章节。
  • 检查是否存在
    design/gdd/systems-index.md
    。若存在，阅读该文件以了解此系统在依赖图中的位置及其所属层级。若不存在，记录"未找到系统索引——跳过依赖层级检查"并继续操作。
  • 检查
    design/quick-specs/
    中是否有之前针对该系统的快速规范——避免出现冲突。
  • 如果是调优类改动，还需检查
    assets/data/
    中存储相关数值的数据文件。
报告查找结果："找到GDD位于[路径]。相关章节：[章节名称]。未发现冲突的快速规范。"（若发现冲突则需注明。）

3. Draft the Quick Design Spec

3. 起草快速设计规范

Use the appropriate spec format for the change category.
根据改动类别选择合适的规范格式。

For Tuning changes

调优类改动

Produce a single table:
markdown
undefined
生成单个表格：
markdown
undefined

Quick Design Spec: [Title]

Quick Design Spec: [标题]

Type: Tuning System: [System name] GDD Reference: 
design/gdd/[filename].md
— Tuning Knobs section Date: [today]
Type: Tuning System: [系统名称] GDD Reference: 
design/gdd/[文件名].md
— 调优参数章节 Date: [今日日期]

Change

改动内容

ParameterOld ValueNew ValueRationale
[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.]
对应GDD中的调优参数：[参数名称及其记录的范围]。 新值[在范围内/处于范围边缘/超出范围]。 [若超出范围：说明为何需要扩展范围。]

Acceptance Criteria

验收标准

  • [Parameter] reads [new value] from 
    assets/data/[file]
  • Behavior difference is observable in [specific context]
  • No regression in [related behavior]
undefined
  • [参数]从
    assets/data/[文件]
    中读取[新值]
  • 在[特定场景]下可观察到行为变化
  • [相关行为]无回归问题
undefined

For Tweak and Addition changes

微调与新增类改动

markdown
undefined
markdown
undefined

Quick Design Spec: [Title]

Quick Design Spec: [标题]

Type: [Tweak / Addition] System: [System name] GDD Reference: 
design/gdd/[filename].md
Date: [today]
Type: [Tweak / Addition] System: [系统名称] GDD Reference: 
design/gdd/[文件名].md
Date: [今日日期]

Change Summary

改动摘要

[1-2 sentences describing what changes and why.]
[1-2句话描述改动内容及原因。]

Motivation

动机

[Why is this change needed? What player experience problem does it solve? Reference the relevant MDA aesthetic or player feedback if applicable.]
[为何需要此改动？解决了哪些玩家体验问题？ 若适用，可参考相关MDA美学或玩家反馈。]

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.]
当前GDD描述（引用
design/gdd/[文件名].md
，[章节]）：
[相关规则或描述的精确引用]
本规范将其修改为：
[新规则或描述，撰写精度需与GDD的详细规则章节一致。程序员应仅通过此文本即可完成实现。]

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

受影响系统

SystemImpactAction Required
[system][how it is affected][update GDD / update data file / no action]
系统影响需执行操作
[系统名][影响方式][更新GDD / 更新数据文件 / 无需操作]

Acceptance Criteria

验收标准

  • [Specific, testable criterion 1]
  • [Specific, testable criterion 2]
  • [Specific, testable criterion 3]
  • No regression: [the original behavior this must not break]
  • [具体、可测试的标准1]
  • [具体、可测试的标准2]
  • [具体、可测试的标准3]
  • 无回归：[原行为需保持正常，不得破坏]

GDD Update Required?

是否需要更新GDD？

[Yes / No] [If yes: which file, which section, and what the update should say.]
undefined
[是 / 否] [若是：说明需更新的文件、章节及更新内容。]
undefined

For New Small System changes

小型新系统类改动

Use a trimmed GDD structure. Include only the sections that are directly necessary — skip Player Fantasy, full Formulas, and Edge Cases unless the system specifically requires them.
markdown
undefined
使用简化版GDD结构。仅包含必要章节——除非系统特别需要，否则跳过玩家愿景、完整公式和边缘情况章节。
markdown
undefined

Quick Design Spec: [Title]

Quick Design Spec: [标题]

Type: New Small System Scope: [1-2 sentence description of what this system does and doesn't do] Date: [today] Estimated Implementation: [hours]
Type: New Small System Scope: [1-2句话描述该系统的功能范围，包括能做什么和不能做什么] Date: [今日日期] Estimated Implementation: [小时数]

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

调优参数

KnobDefaultRangeCategoryRationale
[name][value][min–max][feel/curve/gate][why this default]
All values must live in 
assets/data/[appropriate-file].json
, not hardcoded.
KnobDefaultRangeCategoryRationale
[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]
  • [功能标准：执行正确操作]
  • [功能标准：处理边缘情况]
  • [体验标准：手感符合预期——需通过 playtest 验证]
  • [回归标准：不破坏相邻系统]

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."]

---
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. Approval and Filing

4. 审批与归档

Present the draft to the user in full. Then use 
AskUserQuestion
:
  • Prompt: "Here's the Quick Design Spec draft. How do you want to proceed?"
  • Options: 
    • [A] Approve — write it as shown
    • [B] Revise — I'll describe what to change
    • [C] This grew too large — redirect to /design-system instead
If [B]: collect the requested changes, revise the draft, and re-present this widget. If [C]: stop. Verdict: REDIRECTED — use 
/design-system
for this change.
If [A]: ask "May I write this Quick Design Spec to 
design/quick-specs/[kebab-case-title]-[YYYY-MM-DD].md
?"
Use today's date in the filename. The title should be a kebab-case description of the change (e.g., 
jump-height-tuning-2026-03-10
, 
parry-window-addition-2026-03-10
).
If yes, create the 
design/quick-specs/
directory if it does not exist, then write the file.
If a GDD update is required (flagged in the spec), ask separately after writing the quick spec:
"This spec modifies rules in [System Name]. May I update 
design/gdd/[filename].md
— specifically the [section name] section?"
Show the exact text that would be changed (old vs. new) before asking. Do not make GDD edits without explicit approval.
向用户完整展示草稿，然后使用
AskUserQuestion
：
  • 提示语："这是快速设计规范草稿。您希望如何处理？"
  • 选项： 
    • [A] 批准——按此内容撰写
    • [B] 修改——我将描述需改动的内容
    • [C] 规模过大——转至/design-system
若选择[B]：收集所需修改内容，修订草稿后重新展示此交互组件。 若选择[C]：停止操作。结论：已重定向——请使用
/design-system
处理此改动。
若选择[A]：询问"是否允许我将此快速设计规范写入
design/quick-specs/[短横线分隔标题]-[YYYY-MM-DD].md
？"
文件名中使用今日日期。标题应为改动内容的短横线分隔描述（例如：
jump-height-tuning-2026-03-10
、
parry-window-addition-2026-03-10
）。
若同意，若
design/quick-specs/
目录不存在则创建该目录，然后写入文件。
若规范中标记需要更新GDD，在写入快速规范后单独询问：
"本规范修改了[系统名称]中的规则。是否允许我更新
design/gdd/[文件名].md
——特别是[章节名称]章节？"
在询问前展示具体的修改内容（旧内容 vs 新内容）。未经明确批准不得修改GDD。

5. Handoff

5. 交接

After writing the file, output:
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. Reference this spec in the story's GDD Reference field.
写入文件后，输出：
快速设计规范已写入：design/quick-specs/[文件名].md
类型：[Tuning / Tweak / Addition / New Small System]
系统：[系统名称]
GDD更新：[需更新——待审批 / 已应用 / 无需更新]

下一步：本规范已准备好通过`/story-readiness`验证，之后即可实施。请在故事的GDD参考字段中引用本规范。

Pipeline Notes

流程说明

Verdict: COMPLETE — quick design spec written and ready for implementation.
Quick Design Specs bypass 
/design-review
and 
/review-all-gdds
by design. They are for small, low-risk, well-scoped changes where the cost of the full review pipeline exceeds the risk of the change itself.
Redirect to the full pipeline if any of the following are true:
  • The change adds a new system that belongs in the systems index
  • The change significantly alters cross-system behavior or a system's contracts with other systems
  • The change introduces new player-facing mechanics that affect the game's MDA aesthetic balance
  • Implementation is likely to exceed one week of work
In those cases: "This change has grown beyond quick-spec scope. I recommend using 
/design-system
to author a full GDD for this."
结论：完成——快速设计规范已撰写完成，可用于实施。
快速设计规范默认跳过
/design-review
和
/review-all-gdds
流程。它们适用于小型、低风险、范围明确的改动，此类改动中完整审查流程的成本高于改动本身的风险。
若出现以下任一情况，请重定向至完整流程：
  • 改动添加了需纳入系统索引的新系统
  • 改动显著改变跨系统行为或系统与其他系统的协作规则
  • 改动引入影响游戏MDA美学平衡的新玩家机制
  • 实现工作量可能超过一周
在这些情况下："此改动已超出快速规范的适用范围。建议使用
/design-system
撰写完整GDD。"

Recommended Next Steps

推荐后续步骤

  • Run 
    /story-readiness [story-path]
    to validate the story before implementation begins — reference this spec in the story's GDD Reference field
  • Run 
    /dev-story [story-path]
    to implement once the story passes readiness checks
  • If the change is larger than expected, run 
    /design-system [system-name]
    to author a full GDD instead
  • 运行
    /story-readiness [故事路径]
    在实施前验证故事——请在故事的GDD参考字段中引用本规范
  • 故事通过就绪检查后，运行
    /dev-story [故事路径]
    进行实施
  • 若改动规模超出预期，运行
    /design-system [系统名称]
    撰写完整GDD