project-stage-detect

name	project-stage-detect
description	自动分析项目状态、检测开发阶段、识别缺失项，并根据现有工件推荐后续步骤。
argument-hint	[可选: 角色过滤器，如 'programmer' 或 'designer']
user-invocable	true
allowed-tools	Read, Glob, Grep, Bash

项目阶段检测

本技能扫描你的项目以确定其当前开发阶段、工件的完整性以及需要关注的缺失项。特别适用于以下场景：

• 接手一个现有项目
• 入职一个代码库
• 里程碑前检查缺失项
• 了解 "我们现在在哪里？"

---

工作流

1. 扫描关键目录

分析项目结构和内容：

设计文档（design/）：

• 统计 design/gdd/*.md 中的 GDD 文件数
• 检查 game-concept.md、game-pillars.md、systems-index.md
• 如果 systems-index.md 存在，统计总系统数与已设计系统数
• 分析完整性（概述、详细设计、边缘情况等）
• 统计 design/narrative/ 中的叙事文档数
• 统计 design/levels/ 中的关卡设计数

源代码（src/）：

• 统计源文件数（与语言无关）
• 识别主要系统（包含 5 个以上文件的目录）
• 检查 core/、gameplay/、ai/、networking/、ui/ 目录
• 估算代码行数（大致规模）

生产工件（production/）：

• 检查是否有活跃的 Sprint 计划
• 查找里程碑定义
• 查找路线图文档

原型（prototypes/）：

• 统计原型目录数
• 检查是否有 README（已文档化 vs 未文档化）
• 评估原型是已归档还是活跃的

架构文档（docs/architecture/）：

• 统计 ADR (Architecture Decision Record，架构决策记录) 数量
• 检查是否有概述/索引文档

测试（tests/）：

• 统计测试文件数
• 估算测试覆盖率（粗略启发式）

2. 分类项目阶段

根据扫描的工件确定阶段。先检查 production/stage.txt — 如果存在，使用其值（来自 /gate-check 的显式覆盖）。否则， 使用以下启发式规则自动检测（从最高阶段向前检查）：

阶段	指标
概念	无游戏概念文档，处于头脑风暴阶段
系统设计	游戏概念存在，系统索引缺失或不完整
技术搭建	系统索引存在，引擎未配置
预制作	引擎已配置，src/ 不到 10 个源文件
制作	src/ 有 10 个以上源文件，活跃开发中
打磨	仅限显式设置（由 /gate-check 制作 -> 打磨关卡设置）
发布	仅限显式设置（由 /gate-check 打磨 -> 发布关卡设置）

3. 协作式缺失项识别

不要只是列出缺失的文件。而是提出澄清问题：

• "我看到战斗代码（src/gameplay/combat/）但没有 design/gdd/combat-system.md。这是先做的原型，还是应该进行逆向文档化？"
• "你有 15 个 ADR 但没有架构概述。需要我创建一个来帮助新贡献者吗？"
• "production/ 中没有 Sprint 计划。你在其他地方跟踪工作吗（Jira、Trello 等）？"
• "我发现有游戏概念但没有系统索引。你是否已经将概念拆解为各个独立系统，还是需要我运行 /map-systems？"
• "原型目录有 3 个项目没有 README。这些是实验，还是需要文档化？"

4. 生成阶段报告

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

报告结构：

# 项目阶段分析

**日期**：[日期]
**阶段**：[概念/系统设计/技术搭建/预制作/制作/打磨/发布]

## 完整性概览
- 设计：[X%]（[N] 个文档，[缺失项]）
- 代码：[X%]（[N] 个文件，[系统]）
- 架构：[X%]（[N] 个 ADR，[缺失项]）
- 生产管理：[X%]（[状态]）
- 测试：[X%]（[覆盖率估算]）

## 识别的缺失项
1. [缺失项描述 + 澄清问题]
2. [缺失项描述 + 澄清问题]

## 推荐后续步骤
[根据阶段和角色按优先级排列的列表]

5. 角色过滤的推荐（可选）

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

程序员：

• 专注于架构文档、测试覆盖率、缺失的 ADR
• 代码与文档的差距

设计师：

• 专注于 GDD 完整性、缺失的设计章节
• 原型文档化

制作人：

• 专注于 Sprint 计划、里程碑追踪、路线图
• 跨团队协调文档

通用（无角色）：

• 所有缺失项的全景视图
• 各领域最高优先级的项目

6. 写入前请求批准

协作协议：

我已经分析了你的项目。以下是我的发现：

[展示摘要]

识别的缺失项：
1. [缺失项 1 + 问题]
2. [缺失项 2 + 问题]

推荐后续步骤：
- [优先级 1]
- [优先级 2]
- [优先级 3]

可以将完整的阶段分析写入 production/project-stage-report.md 吗？

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

---

用法示例

# 通用项目分析
/project-stage-detect

# 程序员视角分析
/project-stage-detect programmer

# 设计师视角分析
/project-stage-detect designer

---

后续行动

生成报告后，建议相关的后续步骤：

• 有概念但没有系统索引？ -> /map-systems 拆解为系统
• 缺失设计文档？ -> /reverse-document design src/[系统]
• 缺失架构文档？ -> /architecture-decision 或 /reverse-document architecture
• 原型需要文档化？ -> /reverse-document concept prototypes/[名称]
• 没有 Sprint 计划？ -> /sprint-plan
• 接近里程碑？ -> /milestone-review

---

协作协议

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

1. 先提问：对缺失项提问，不要假设
2. 提供选项："需要我创建 X，还是在其他地方跟踪了？"
3. 用户决定：等待指示
4. 展示草稿：显示报告摘要
5. 获取批准："可以写入 production/project-stage-report.md 吗？"

绝不要静默写入文件。始终先展示发现并询问再创建工件。