project-stage-detect

项目阶段检测

此技能会扫描项目，以确定其当前开发阶段、产物的完整程度，以及需要关注的缺口。以下情况尤其适用：

• 开始着手已有项目
• 熟悉代码库
• 在里程碑之前检查缺少哪些内容
• 了解“我们目前进展如何？”

---

工作流

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

自动化模式：解析 modes.automation（project.local.yaml → project.yaml → 默认值 collaborative）。每次调用 AskUserQuestion 和 每次写入文件都遵循 .claude/docs/automation-modes.md （collaborative 始终询问 · guided 仅在重大事项上询问 · autonomous 记录后继续； automation_always_ask 类别始终提示）。

已在上方解析——按原样使用。若未被屏蔽 → 使用 .claude/docs/config-resolution.md 中的默认值。

解析层级——不要自行假设。 层级决定哪些内容算作缺口： 在 full 下，每份缺失的文档都是缺口；在 minimal 下，则都不算， 因为简报加引擎就是常规状态，而代码才是预期的下一步。擅自设定较高层级，会让一个游戏项目误以为自己缺少 GDD、艺术圣经和 ADR——而这正是 modes.rigor 要避免的那种“流程与我的项目不匹配”的体验。

workflow（依据 .claude/docs/workflow-modes.md）。层级决定 哪些缺失文档算作缺口（步骤 3）——低于 full 时，不会将可选文档 标记为缺失。

1. 扫描关键目录

先执行确定性检查——一次调用即可回答目录中每个已编目制品“是否存在”：

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

请严格按原样运行——从项目根目录运行，使用相对路径，不带参数，不使用 cd，也不使用 2>&1。此技能的权限授权与这种形式匹配；任何其他形式都需要用户批准。

不带 --phase 时，它会报告所有阶段，因此一次调用即可检查整个项目：对每一步，报告 PRESENT / ABSENT / SHORT（带有 count= 和 min=）/ PATTERN_MISS / NO_CHECK。请用它代替下面针对每个制品手动执行 glob 检查，并将其 NO_CHECK 总数视为存在性检查所能提供信息的真实上限。

它只报告观察结果——此技能仍需判断这些观察结果意味着什么阶段，而哪些缺失算作差距，仍由层级决定（参见下文的工作流层级说明）。

然后分析脚本无法判断的内容：内容质量、脚本未跟踪的数量，以及需要主观判断的事项。

设计文档（design/）：

• 统计 design/gdd/*.md 中的 GDD 文件数量
• 检查是否存在 game-concept.md（或 minimal 模式下的 design/game-brief.md）、game-pillars.md、systems-index.md
• 如果 systems-index.md 存在，统计系统总数和已设计系统数
• 分析完整性（概述、详细设计、边缘情况等）。按章节阅读 GDD：使用 Grep 工具查找所需标题（模式为 ^#，内容模式），再通过 offset 和 limit 读取相应范围。
• 统计 design/narrative/ 中的叙事文档数量
• 统计 design/levels/ 中的关卡设计数量

源代码（代码根目录——Godot 使用 src/，Unity 使用 Assets/，Unreal 使用 Source/；根据 .claude/docs/code-root-resolution.md 确定）：

• 统计源文件数量（与语言无关）
• 确定主要系统（包含 5 个或更多文件的目录）
• 检查是否存在 core/、gameplay/、ai/、networking/、ui/ 目录
• 粗略估算代码行数规模
• 如果代码根目录无法解析，说明 NOT ASSESSED — code root unresolved，切勿报告源文件数量为零——零个文件会让人误以为这是一个全新项目，而且没有数量就无法判定阶段表中的源文件行

制作制品（production/）：

• 检查是否存在进行中的冲刺计划。workflow: minimal 模式下没有冲刺：应根据项目简介中的构建顺序，读取故事文件的进度；绝不要将缺少冲刺计划、里程碑或路线图报告为差距
• 查找里程碑定义
• 查找路线图文档

原型（prototypes/）：

• 统计原型目录数量
• 检查是否有 README（已记录与未记录的原型）
• 评估原型是已归档还是仍在使用

架构文档（docs/architecture/）：

• 统计 ADR（架构决策记录）数量
• 检查是否有概览或索引文档

测试（tests/）：

• 统计测试文件数量
• 粗略估算测试覆盖率

2. 判断项目阶段

根据扫描到的产物确定阶段。优先检查 project.yaml 中的 project.stage（如果存在）；否则检查 production/stage.txt（旧版回退项）——两者都是来自 /gate-check 的显式覆盖值。否则，使用以下启发式自动检测（从最成熟的阶段开始，依次向前检查）：

即使已配置阶段，也始终运行启发式检测，然后进行比较。 配置值决定阶段是什么；它不能证明产物支持该阶段。报告两者；如有分歧，请明确指出：

“配置阶段：Release。观察到的产物表明阶段为 Pre-Production（2 个源文件、0 个 ADR、无架构文档、无史诗）。 两者不一致——配置阶段可能已过时，或相关工作存在于此仓库之外。”

读取配置并复述不是检测。此技能本身的描述承诺会“分析项目状态、检测阶段”，而无法反驳其输入的阶段检测器是绝不能成为的东西——它会将产物符合自身 Pre-Production 行（相差四个阶段）的项目报告为 Release，却只字不提。

存在分歧时，阶段置信度为 CONCERNS（步骤 4）——按定义，这表示信号模糊，无论产物多么完整。例外：在 workflow: minimal 下，不会运行 /gate-check，因此配置阶段保持 /start 设置的值。在这种情况下，报告观察到的阶段，并说明在此层级不会推进配置阶段；这种滞后是预期情况，不属于分歧。

阶段	指标
Concept	没有游戏概念文档，处于头脑风暴阶段
Systems Design	已有游戏概念，但系统索引缺失或不完整
Technical Setup	已有系统索引，但尚未配置引擎
Pre-Production	已配置引擎，代码根目录中的源文件少于 10 个
Production	代码根目录中有 10 个或更多源文件，正在积极开发
Polish	仅限显式设置（通过 /gate-check 的 Production → Polish 阶段门设置）
Release	仅限显式设置（通过 /gate-check 的 Polish → Release 阶段门设置）

3. 协作识别缺口

根据已确定的工作流层级提出缺口：

• full — 将每种缺失的文档类型（GDD、艺术圣经、UX 规范、ADR）都列为缺口。
• standard — 仅列出必需文档：已构建系统缺少 GDD，以及缺少关键（基础层）ADR。除非存在视觉资产故事，否则不要将缺少艺术圣经列为缺口；也不要将非核心 UX 规范列为缺口。
• minimal — 存在 design/game-brief.md 和引擎属于正常状态。不要将缺少 GDD、艺术圣经、UX 规范、ADR、史诗或冲刺计划列为缺口：简报中的构建顺序就是计划，预期的下一步是编写代码。

不要只是列出缺失文件。相反，提出澄清问题（仅针对上述层级要求指出的缺口）：

• “我看到有战斗代码（<code root>/gameplay/combat/），但没有 design/gdd/combat-system.md。这是先做了原型，还是应该补写文档？”
• “你有 15 个 ADR，但没有架构概览。要我创建一份来帮助新贡献者吗？”
• （仅限 standard/full）“我看到 <code root>/ 下有 [N] 个系统，但 docs/architecture/ 中没有 ADR。这些决策记录在其他地方了吗？还是应该使用 /architecture-decision 编写关键决策？”
• （仅限 standard/full）“production/ 中没有冲刺计划。你们是否在其他地方跟踪工作（Jira、Trello 等）？”
• “我找到了游戏概念，但没有系统索引。你们是否已将该概念分解为各个系统？还是应该运行 /map-systems？”
• “原型目录中有 3 个项目没有 README。这些是实验项目，还是需要补充文档？”

4. 生成阶段报告

使用模板：.claude/docs/templates/project-stage-report.md

报告结构：

# Project Stage Analysis

**Date**: [date]
**Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
**Stage Confidence**: [PASS — clearly detected / CONCERNS — ambiguous signals / NOT ASSESSED — a check the stage depends on did not run / FAIL — critical gaps block progress]

## Completeness Overview
- Design: [X%] ([N] docs, [gaps])
- Code: [X%] ([N] files, [systems])
- Architecture: [X%] ([N] ADRs, [gaps])
- Production: [X%] ([status] — at `minimal`: stories complete in the brief's build order, never "no sprint plan")
- Tests: [X%] ([coverage estimate])

## Gaps Identified
1. [Gap description + clarifying question]
2. [Gap description + clarifying question]

## Recommended Next Steps
[Priority-ordered list based on stage and role]

阶段置信度——优先匹配先命中： 如果关键缺口阻碍进展，则为 FAIL；否则，如果收集到的信号含糊不清——它们可能对应多个阶段，或配置的阶段与观察到的阶段不一致（步骤 2），则为 CONCERNS；否则，如果某项阶段判断所依赖的检查未运行，则为 NOT ASSESSED——注明是哪项检查（代码根目录未确定，且包含两个候选根目录，导致源文件数量以及表格中的 Production 行无法确定）；否则为 PASS。NOT ASSESSED 的优先级高于 PASS——无法检查的阶段不能算作明确检测到的阶段——但低于 CONCERNS 和 FAIL，因此已知问题不会被它掩盖。

5. 按角色筛选建议（可选）

如果用户提供了角色参数（例如，/project-stage-detect programmer）：

Programmer：

• 重点关注架构文档、测试覆盖率、缺失的 ADR
• 代码与文档之间的差距

Designer：

• 重点关注 GDD 的完整性、缺失的设计章节
• 原型文档

Producer：

• 重点关注冲刺计划、里程碑跟踪、路线图
• 跨团队协作文档

General（未指定角色）：

• 全面查看所有缺口
• 各领域中优先级最高的事项

6. 写入前请求批准

协作流程：

I've analyzed your project. Here's what I found:

[Show summary]

Gaps identified:
1. [Gap 1 + question]
2. [Gap 2 + question]

Recommended next steps:
- [Priority 1]
- [Priority 2]
- [Priority 3]

May I write the full stage analysis to production/project-stage-report.md?

等待用户批准后再创建文件。

---

使用示例

# General project analysis
/project-stage-detect

# Programmer-focused analysis
/project-stage-detect programmer

# Designer-focused analysis
/project-stage-detect designer

---

后续操作

生成报告后，建议相关后续步骤——仅针对已确定的工作流层级所揭示的缺口（步骤 3）。在 standard/minimal 层级下，不要建议编写可选文档（例如，在 minimal 层级下，GDD 缺失时不要建议运行 /reverse-document，因为此时下一步应是编写代码）：

• 在 minimal 层级下没有 design/game-brief.md？ → 当代码根目录中已有游戏（10 个或更多源文件）时，运行 /reverse-document design <code root>：它会根据已构建的内容编写简介。代码很少或没有代码时，运行 /brainstorm。
• 已有概念，但没有系统索引？ → 运行 /map-systems，将其分解为各个系统
• 缺少设计文档？ → 运行 /reverse-document design <code root>/[system]
• 缺少架构文档？ → 运行 /architecture-decision 或 /reverse-document architecture
• 原型需要编写文档？ → 运行 /reverse-document concept prototypes/[name]
• 没有冲刺计划？ → 运行 /sprint-plan（不适用于 rigor: minimal，此时简介中的构建顺序就是计划）
• 里程碑临近？ → 运行 /milestone-review

---

协作流程

此技能遵循协作设计原则：

1. 先提问：询问缺口，不要自行假设
2. 提供选项：“我应该创建 X，还是它已在其他地方跟踪？”
3. 由用户决定：等待用户指示
4. 展示草稿：显示报告摘要
5. 获得批准：“我可以写入 production/project-stage-report.md 吗？”

绝不默默写入文件。始终展示发现并在创建产物前征求同意。