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. 主要なディレクトリをスキャンする

まず、決定論的なチェックを実行します。カタログに登録されているすべての成果物について、「何が存在するか」を1回の呼び出しで確認できます。

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

記載どおりに実行してください。プロジェクトのルートから相対パスで実行し、引数や cd、2>&1 は使用しません。このスキルの権限付与はこの形式に一致しており、ほかの形式ではユーザーに承認を求めます。

--phase を指定しない場合はすべてのフェーズが報告されるため、1回の呼び出しでプロジェクト全体を確認できます。各ステップの結果は、PRESENT／ABSENT／SHORT（count= と min= を含む）／PATTERN_MISS／NO_CHECK です。以下の成果物を個別に手動でグロブ検索する代わりにこのスクリプトを使い、存在チェックで分かることの正直な限界として、NO_CHECK の合計を扱ってください。

このスクリプトは観察結果のみを報告します。それらの観察結果がどの段階を示すかは、このスキルが判断し、どの欠落が不足に該当するかは引き続き階層によって決まります（以下のワークフロー階層に関する注記を参照）。

次に、スクリプトで確認できない内容、すなわちコンテンツの品質、追跡対象外の数、判断を要する事項を分析します。

設計ドキュメント（design/）：

• design/gdd/*.md にあるGDDファイルの数を数える
• game-concept.md（または minimal の場合は design/game-brief.md）、game-pillars.md、systems-index.md の有無を確認する
• systems-index.md がある場合は、システムの総数と設計済みのシステム数を数える
• 完全性を分析する（概要、詳細設計、エッジケースなど）
• 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 個、ADR 0 件、アーキテクチャドキュメントなし、エピックなし）。 これらは食い違っています。設定されたステージが古いか、作業が このリポジトリの外で行われている可能性があります。」

設定を読み取ってそのまま報告することは、検出ではありません。このスキルの 説明では「プロジェクトの状態を分析し、ステージを検出する」とうたっています。入力と 矛盾する判断ができないステージ検出器は、決してあってはなりません。 それでは、成果物が 4 段階下の Pre-Production の行に該当するプロジェクトに対して Release と報告し、何も指摘しないことになります。

食い違いがある場合、成果物がどれほど揃っていても、Stage Confidence は 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 と、 重要な（Foundation レイヤーの）ADR が欠けている場合に限ります。ビジュアルアセットのストーリーがない限り アートバイブルの不足は指摘せず、コア以外の UX 仕様書も指摘しません。
• minimal — design/game-brief.md とエンジンがある状態が通常です。GDD、アートバイブル、UX 仕様書、ADR、エピック、 スプリント計画がないことはギャップとして指摘しないでください。ブリーフの構築順序が計画であり、次に想定されるステップはコードです。

不足ファイルを列挙するだけではいけません。 代わりに、確認の質問をしてください（上記のティアで提示対象となるギャップに限ります）。

• 「戦闘コード（<code root>/gameplay/combat/）はありますが、design/gdd/combat-system.md がありません。まずプロトタイプを作成したのでしょうか。それとも、後からドキュメント化しますか？」
• 「ADR は 15 件ありますが、アーキテクチャの概要がありません。新しいコントリビューターのために作成しましょうか？」
• （standard／full のみ）「<code root>/ にシステムが [N] 個ありますが、docs/architecture/ に ADR がありません。これらの決定は別の場所に記録されていますか。それとも、重要なものを /architecture-decision で作成しますか？」
• （standard／full のみ）「production/ にスプリント計画がありません。作業は Jira、Trello など、別の場所で管理していますか？」
• 「ゲームコンセプトは見つかりましたが、システムインデックスがありません。コンセプトを個々のシステムに分解しましたか。それとも /map-systems を実行しますか？」
• 「Prototypes ディレクトリに README のないプロジェクトが 3 件あります。これらは実験用でしたか。それともドキュメントが必要ですか？」

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（未解決のコードルート、候補となる 2 つのルート、ソースファイル数が不明なままであり、そのため表の Production の行も確定できないことを明記します）、それ以外は PASS です。NOT ASSESSED は PASS より優先されます — チェックできなかったステージは、明確に検出されたステージではないためです — また、CONCERNS と FAIL よりは下位です。そのため、既知の問題が後ろに隠れることはありません。

5. 役割別の推奨事項（任意）

ユーザーが役割の引数を指定した場合（例：/project-stage-detect programmer）：

プログラマー：

• アーキテクチャ文書、テストカバレッジ、ADR の不足に重点を置きます
• コードと文書の不整合

デザイナー：

• GDD の網羅性、デザインセクションの不足に重点を置きます
• プロトタイプの文書化

プロデューサー：

• スプリント計画、マイルストーンの追跡、ロードマップに重点を置きます
• チーム間の調整に関する文書

全般（役割の指定なし）：

• すべての不足を包括的に確認します
• 各領域で優先度の高い項目を提示します

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 を提案しないでください）。

• コンセプトはあるが、システムのインデックスがない場合 → システムに分解するために /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 に書き込んでもよいですか？」

ファイルを決して黙って書き込まないでください。必ず調査結果を示し、成果物を作成する前に確認してください。