help

Studio 帮助 — 接下来该做什么？

此技能为只读技能——只报告发现，不写入任何文件。

此技能会准确判断你在游戏开发流程中的进度，并告知你下一步该做什么。它是轻量级的，并非完整审查。如需完整的差距分析，请使用 /project-stage-detect。

实时项目状态

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

这些值会在运行此技能前解析。请直接使用：

• 配置块中的 project.stage 是 Step 2 阶段的权威依据——它已应用 project.yaml → production/stage.txt 回退机制，并保留包含空格的值（Systems Design）。
• 配置块中的 workflow 是 Step 2 和 Step 5 所用的层级——不要重新读取。
• 如果未渲染配置块，则表示已禁用 Shell 预处理；请回退使用 .claude/docs/config-resolution.md 中的默认值。

---

Step 1：读取目录

读取 .claude/docs/workflow-catalog.yaml。这是所有阶段、各阶段步骤（按顺序排列）、每个步骤是否为必需项，以及表示已完成的产物 glob 模式的权威列表。

---

Step 1b：查找目录中未列出的技能

读取目录后，Glob .claude/skills/*/SKILL.md 以获取已安装技能的完整列表。对于每个文件，从其 frontmatter 中提取 name: 字段。

将其与目录中的 command: 值进行比较。凡是名称未出现在目录命令中的技能，都是未编入目录的技能——仍可使用，但不属于受阶段控制的工作流。

收集这些技能，供 Step 7 输出——以页脚区块的形式展示：

### Also installed (not in workflow)
- `/skill-name` — [description from SKILL.md frontmatter]
- `/skill-name` — [description]

仅当至少存在一个未编入目录的技能时，才显示此区块。根据用户当前阶段，最多列出 10 个最相关的技能（例如，生产阶段的 QA 技能，生产/打磨阶段的团队技能等）。

---

Step 2：确定当前阶段

首先，使用上方配置块中的 workflow。 如果值为 minimal，则项目采用的是最简路径，而非阶段阶梯：跳过本步骤其余内容，读取会话上下文（Step 3），然后前往 Step 4m。在该层级下，不要映射 project.stage——最简路径中的任何步骤都不会运行 /gate-check，因此无论项目进展到什么程度，阶段读取结果始终都是 Concept；若继续沿着 Concept 阶段推进，就会让已有故事的项目回头去制作概念文档、美术圣经和系统地图。

否则，请按以下顺序检查：

1. 使用上方配置块中的 project.stage——它已完成解析。将其值映射到目录中的阶段键：

   • "Concept" → concept
   • "Systems Design" → systems-design
   • "Technical Setup" → technical-setup
   • "Pre-Production" → pre-production
   • "Production" → production
   • "Polish" → polish
   • "Release" → release

2. 如果两者都未设置，则根据产物推断阶段（匹配到的最先进阶段优先）：

   • 代码根目录中有 10 个以上源文件 → production
   • 存在 production/epics/**/story-*.md → pre-production
   • 存在 docs/architecture/adr-*.md → technical-setup
   • 存在 design/gdd/systems-index.md → systems-design
   • 存在 design/gdd/game-concept.md（或 design/game-brief.md）→ concept
   • 无匹配项 → concept（新项目）

3. 按照本步骤开头所述，已获取 workflow（依据 .claude/docs/workflow-modes.md）。它决定是否将可选文档列为下一步（Step 5）。

---

第 3 步：读取会话上下文

如果 production/session-state/active.md 存在，请读取它，但只读取 STATUS 和 CHECKPOINT 块（架构：.claude/docs/templates/session-state.md）；下方的 叙述可能很长。查找标记 （Grep pattern="" path="production/session-state/active.md" output_mode="content" -n）， 并从第一个标记读到最后一个标记。没有标记的文件早于该架构：改为读取其中最后一个 ## Session Extract 块。提取：

• 最近处理的内容
• 正在进行的任务或待解决的问题
• STATUS 块中的当前 epic/feature/task（如有）

这能告诉你用户刚完成了什么，或正卡在哪儿——用它来调整输出。每个层级都会执行此步骤：在 minimal 层级中，这是 Step 4m 所依赖检查点的唯一读取内容（如果检查点写着“Next step: /story-done”，就表示工作已记录）。从这里开始，minimal 会进入 Step 4m，而不是 Step 4。

---

第 4 步：检查当前阶段的步骤是否完成

针对当前阶段（来自目录）中的每个步骤：

基于产物的检查

确定性地解析这些内容——只调用一次，而不是每个步骤都运行一次 glob：

Bash: bash .claude/scripts/artifact-check.sh --phase [current-phase]

严格按原样运行，无论此处还是下文均如此：从项目根目录开始，使用相对路径——不要使用绝对路径、cd 或 2>&1。此技能授予的权限与此形式匹配；使用其他形式则会要求用户批准。

该脚本会根据工作树评估目录中的每个 glob、pattern、min_count 和 any_of，并为每个步骤报告一行。将其状态对应如下：

状态	报告为
PRESENT	已完成
ABSENT	未完成
SHORT	未完成——说明还差多少（会提供 count=/min=）
PATTERN_MISS	未完成——文件存在，但缺少标记；请明确说明这一点，因为说“缺失”会让用户重新创建已有文件
NO_CHECK	如果该步骤包含 note=，则报告为 MANUAL；否则报告为 UNKNOWN——无法追踪是否完成（例如可重复的实现工作）

不要用 Glob/Grep 重新推导这些结果。尤其要注意，any_of 列出的是多个备选项——匹配其中一个就足够；手动评估可能会误判为“未完成”：engine-setup 只要在 project.yaml 中有 engine.name，或在 .claude/docs/technical-preferences.md 中有旧版 Engine: 行，就算满足条件。脚本会报告匹配的是哪个备选项（alt=/match=）。

NO_CHECK 绝不表示已完成。 脚本会在各行之前打印 NO_CHECK: 总数；如果某个阶段的大多数步骤都是 NO_CHECK，请明确说明，而不要暗示该阶段即将完成。

特殊情况：production 阶段——读取 sprint-status.yaml

如果当前阶段是 production，请先检查 production/sprint-status.yaml，再进行任何基于 glob 的 story 检查。如果文件存在，请直接读取：

• status: in-progress 的 story → 标记为“当前进行中”
• status: ready-for-dev 的 story → 标记为“接下来处理”
• status: done 的 story → 计为已完成
• status: blocked 的 story → 根据 blocker 字段标记为阻塞项

这样无需扫描 Markdown，就能准确获取每个 story 的状态。跳过 implement 和 story-done 步骤的 glob 产物检查——以 YAML 为准。

特殊情况：repeatable: true（非 production 阶段）

对于 production 阶段之外的可重复步骤（例如“System GDDs”），产物检查只能说明是否做过任何工作，不能说明工作是否完成。请使用不同的方式标记——展示检测到的内容，然后注明工作可能仍在进行。

Step 4m：最简路径（仅限 workflow: minimal）

在 minimal 模式下，路线是目录中的 paths.minimal，而非一个阶段：engine → design/game-brief.md → stories → /dev-story ↔ /story-done。一次调用即可解析：

Bash: bash .claude/scripts/artifact-check.sh --path minimal

状态映射与 Step 4 完全相同。按设计，implement 和 story-done 是 NO_CHECK——下面的 story 状态行就是它们的检查结果。下一步是以下首个适用项：

1. engine-setup 不为 PRESENT → /setup-engine
2. game-brief 不为 PRESENT → 如果代码根目录中已有游戏（包含 10 个或更多源文件，这是 Step 2 在 production 模式下使用的测试），则运行 /reverse-document design [code root]：在 minimal 模式下，它会根据已构建的内容写入 design/game-brief.md。否则运行 /brainstorm（在 minimal 模式下，它会写入一页简报）；如果游戏已经构建完成，这会开始一个新创意。
3. create-stories 不为 PRESENT → 不带参数运行 /create-stories（在 minimal 模式下，它会直接根据简报的 MVP 列表生成 stories）
4. 已存在 stories → 下面列出的内容是在你读取此技能前由 .claude/scripts/story-status.sh 输出的：每个未完成的 story 占一行，顺序已按路线排列——依构建顺序依次为 IN_REVIEW、IN_PROGRESS、TODO（Ready 或 Not Started 的 story），然后是 BLOCKED、OTHER、NO_STATUS，以及 COMPLETE 计数：

!bash "${CLAUDE_SKILL_DIR}/../../scripts/story-status.sh"

下一项是首个 IN_REVIEW、IN_PROGRESS 或 TODO 行对应的 story。 列表已是最新状态；不要再次运行脚本，也不要重新读取或排序 story 文件： In Review 的 story 要先关闭，才能继续处理 In Progress 的 story——其工作已经写好，而 /story-done 很快就能完成。

• IN_REVIEW → 工作已写好，正等待关闭： /story-done [path]
• IN_PROGRESS → 尚未完成——无论代码或提交记录显示什么，只有 /story-done 才会将 story 标记为 Complete。只有当用户、active.md 或 git 日志表明其实现已经写好时，才建议运行 /story-done [path]；否则运行 /dev-story [path] 继续推进
• TODO → /dev-story [path]
• BLOCKED story → 指出该 story 及其阻塞原因；它永远不会是下一项
• 没有 IN_REVIEW、IN_PROGRESS 或 TODO 行，但仍有 BLOCKED、OTHER 或 NO_STATUS 行 → 接下来无法构建任何内容，且构建顺序尚未完成。逐个列出这些 story 及其原样状态，并指出被阻塞 story 的阻塞原因（从该 story 的文件中读取）。下一步是先处理其中的第一项：解决其阻塞原因，或者为 OTHER 或 NO_STATUS story 添加路线可识别的 Status: 行（准备好构建时使用 Ready）
• 每个 story 都是 Complete（或 Done） → 简报中的构建顺序已完成。说明这一点，并提供三种后续选择：体验已构建的游戏；使用 /create-stories 根据简报添加后续 stories；或者，如果游戏内容已超出一页简报的范围，运行 /settings 提高 modes.rigor。

**在 minimal 模式下，绝不要将以下任何内容说成必需项或阻塞项：**游戏概念文档、美术圣经、系统图、GDD、/create-epics、冲刺计划、/gate-check 或冲刺收尾（/smoke-check、/team-qa、/retrospective）。简报取代设计文档，其构建顺序取代冲刺计划（.claude/docs/workflow-modes.md — minimal 下限）。用户提出要求时，这些内容仍都可以运行；只有当用户的问题涉及某项内容时，才提及它。

然后跳过 Step 5 和 Step 8，并按照 Step 7 中的 minimal 格式进行说明。

---

步骤 5：查找位置并确定后续步骤

根据完成情况，确定：

1. 最后一个已确认完成的步骤 — 已完成的最靠后必需步骤
2. 当前阻碍项 — 第一个未完成的必需步骤（这是用户接下来必须完成的事项）
3. 可选机会 — 可在阻碍项之前或同时完成的未完成可选步骤。根据工作流层级展示这些步骤：在 full 下，列出所有可选步骤；在 standard 下，仅当可选文档是当前系统／阶段所必需时才列出（不要将真正可选的文档标记为缺项）。在 minimal 下不执行此步骤 — 由步骤 4m 取代
4. 后续必需步骤 — 当前阻碍项之后的必需步骤（标为“即将开始”，方便用户提前规划）

如果用户提供了参数（例如“刚完成 design-review”），即使产物检查结果不明确，也应据此将进度推进到用户指定的步骤之后。

---

步骤 6：检查进行中的工作

如果 active.md 显示有正在进行的任务或史诗：

• 在顶部醒目展示：“看起来你之前正在处理 [X]”
• 建议继续处理，或确认是否已经完成

---

步骤 7：呈现输出

保持简短直接。这是快速指引，不是报告。

## Where You Are: [Phase Label]

**In progress:** [from active.md, if any]

### ✓ Done
- [completed step name]
- [completed step name]

### → Next up (REQUIRED)
**[Step name]** — [description]
Command: `[/command]`

### ~ Also available (OPTIONAL)
- **[Step name]** — [description] → `/command`
- **[Step name]** — [description] → `/command`

### Coming up after that
- [Next required step name] (`/command`)
- [Next required step name] (`/command`)

---
Approaching **[next phase]** gate → run `/gate-check` when ready.

**在 minimal 下改用此格式 — 不显示阶段标签或关卡行。N 仅统计状态行写有 Complete 或 Done 的故事，且只有这些故事才归入 ✓ Done。N 和 M 是 COMPLETE 行上的两个数字；该行不会列出已完成故事，因此 ✓ Done 应显示数量，而非故事标题：

## Where You Are: Minimal path — [N] of [M] stories complete

**In progress:** [from active.md, if any]

### ✓ Done
- Engine: [engine] · Game brief · [N] stories

### → Next up
**[Story NNN: title]** — [what it delivers]
Command: `/story-done [story-path]` for an In Review story, or an In Progress one whose work is written; otherwise `/dev-story [story-path]`

### Coming up after that
- [the next Ready stories in build order, at most 3]

格式规则：

• 使用 ✓ 表示已确认完成
• 使用 → 表示当前必需的下一步（仅一个 — 第一个阻碍项）
• 使用 ~ 表示当前可执行的可选步骤
• 命令以行内反引号代码形式显示
• 如果步骤没有命令（例如“实现故事”），请说明应如何操作，而不是显示斜杠命令
• 对于 MANUAL 步骤，询问用户：“我无法判断 [step] 是否已完成 — 它完成了吗？”

结论：COMPLETE — 已确定后续步骤。

---

步骤 8：关卡提醒（接近关卡时）

在 minimal 下跳过此步骤 — minimal 路径没有阶段关卡。

完成当前阶段的步骤后，检查用户是否可能即将到达关卡：

• 如果当前阶段的所有必需步骤均已完成（或即将完成），添加：“你即将到达 [当前阶段] → [下一阶段] 关卡。准备好后运行 /gate-check。”
• 如果仍有多个必需步骤未完成，则跳过关卡提醒 — 目前还不适用。

---

步骤 9：升级处理路径

给出建议后，如果用户看起来遇到了困难或感到困惑，请添加：

---
Need more detail?
- `/project-stage-detect` — full gap analysis with all missing artifacts listed
- `/gate-check` — formal readiness check for your next phase
- `/start` — re-orient from scratch
- `/settings` — if the process feels mismatched to your project, adjust
  `modes.rigor`. Apply the change-triggers in
  `.claude/docs/settings-guidance.md § 4`: a **lower** tier when the user sounds
  overwhelmed by process (and rigor isn't already `minimal`), or a **higher** tier
  when the project has outgrown it (many systems, or in Production on
  `workflow: minimal`)

仅当用户的输入表明其感到困惑时才显示此内容（例如“I don't know”“stuck”“lost”“not sure”）。对于简单的“下一步是什么？”之类的提问，不要显示。只有在 settings-guidance.md § 4 中的触发条件确实满足时，才显示 /settings 严谨度说明 — 即用户听起来不堪重负（且严谨度尚未设为 minimal），或项目已超出其层级；不要在每次用户感到困惑时都显示。在 minimal 下，省略 /gate-check 行：minimal 路径没有阶段关卡（步骤 4m）。

---

协作协议

• 绝不自动运行下一项技能。 提供建议，让用户自行调用。
• 询问 MANUAL 步骤的完成情况，不要假定已完成或未完成。
• 匹配用户的语气 — 如果用户听起来压力很大（“我完全迷失了”），请给予安慰并只提供一个行动建议，而不是列出六项。
• 只给出一个主要建议 — 用户应该明确知道接下来要做的一件事。可选步骤和“即将开始”的步骤仅作为补充信息。