speckit-analyze

ユーザー入力

$ARGUMENTS

空でない場合は、処理を進める前にユーザー入力を必ず考慮してください。

実行前のチェック

拡張フックを確認します（分析前）：

• プロジェクトのルートに .specify/extensions.yml が存在するか確認します。
• 存在する場合はそのファイルを読み、hooks.before_analyze キーの下にあるエントリを確認します。
• YAML を解析できない場合、または無効な場合は、黙ってスキップしないでください。.specify/extensions.yml を読み取れなかったこと（パーサーエラーを含む）と、そこに登録された必須（optional: false）フックも含めて、フックを一切確認していないことをユーザーに伝え、その後は通常どおり続行します。
• enabled が明示的に false になっているフックは除外します。enabled フィールドがないフックは、デフォルトで有効として扱います。
• 残りのフックについて、condition 式の解釈や評価は試みないでください。
  • condition フィールドがない場合、または null／空の場合は、そのフックを実行可能として扱います。
  • 空でない condition が定義されている場合は、そのフックをスキップし、条件の評価は HookExecutor の実装に委ねます。
• フックコマンド名からコマンド呼び出しを組み立てる際は、ドット（.）をハイフンに置き換えます。たとえば、speckit.git.commit → /speckit-git-commit です。
• 実行可能なフックごとに、optional フラグに応じて次の内容を出力します。

  • 任意のフック（optional: true）：

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 必須のフック（optional: false）：

    ## Extension Hooks
    
    **Automatic Pre-Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    
    Wait for the result of the hook command before proceeding to the Goal.
    

    上記のブロックを出力した後、続行する前に、フックを実際に呼び出して完了を待つ必要があります。エージェントまたはこのセッションでコマンドを実行する場合と同じ方法で実行してください（呼び出し方は、表示上の {command} と異なることがあります。たとえば、スキルモードのエージェントでは /skill:speckit-... または $speckit-... のように実行します）。ブロックを出力しただけでは、フックは実行されません。

• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何もせずにスキップします。

目標

実装に着手する前に、3 つの主要な成果物（spec.md、plan.md、tasks.md）全体にわたる矛盾、重複、曖昧さ、仕様不足の項目を特定します。このコマンドは、/speckit-tasks が完全な tasks.md を正常に作成した後にのみ実行する必要があります。

実行上の制約

厳格な読み取り専用：ファイルを変更しないでください。構造化された分析レポートを出力します。修正計画を任意で提示できます（後続の編集コマンドを手動で実行する前に、ユーザーの明示的な承認が必要です）。

憲章の優先性：プロジェクト憲章（.specify/memory/constitution.md）は、この分析の範囲内で変更できません。憲章との矛盾はすべて自動的に重大（CRITICAL）とし、原則を弱めたり、再解釈したり、黙って無視したりするのではなく、仕様、計画、またはタスクを修正する必要があります。原則そのものを変更する必要がある場合は、/speckit-analyze とは別に、明示的な憲章更新を行わなければなりません。

実行手順

1. 分析コンテキストを初期化する

リポジトリのルートから .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks を 1 回実行し、JSON を解析して FEATURE_DIR と AVAILABLE_DOCS を取得します。絶対パスを次のように導出します。

• SPEC = FEATURE_DIR/spec.md
• PLAN = FEATURE_DIR/plan.md
• TASKS = FEATURE_DIR/tasks.md

必須ファイルが欠けている場合は、エラーメッセージを出して中断します（不足している前提条件を満たすために、ユーザーに該当するコマンドを実行するよう指示してください）。 "I'm Groot" のように引数にシングルクォートを含める場合は、エスケープ構文を使用します。例：'I'\''m Groot'（可能であれば "I'm Groot" のようにダブルクォートを使用してもかまいません）。

2. アーティファクトを読み込む（段階的な開示）

各アーティファクトから必要最小限のコンテキストのみを読み込みます。

spec.md から：

• 概要／コンテキスト
• 機能要件
• 成功基準（パフォーマンス、セキュリティ、可用性、ユーザーの成功、ビジネスへの影響など、測定可能な成果）
• ユーザーストーリー
• エッジケース（存在する場合）

plan.md から：

• アーキテクチャ／スタックの選択
• データモデルの参照
• フェーズ
• 技術的制約

tasks.md から：

• タスク ID
• 説明
• フェーズのグループ分け
• 並列マーカー [P]
• 参照されているファイルパス

constitution から：

• 原則を検証するために .specify/memory/constitution.md を読み込みます

3. セマンティックモデルを構築する

内部表現を作成します（出力に生のアーティファクトを含めないでください）。

• 要件インベントリ：各機能要件（FR-###）と成功基準（SC-###）について、安定したキーを記録します。FR-/SC- 識別子が明示されている場合は、それを主キーとして使用し、必要に応じて読みやすさのために命令形フレーズのスラッグも生成します（例：「ユーザーはファイルをアップロードできる」→ user-can-upload-file）。実装作業が必要な成功基準（例：負荷テストのインフラ、セキュリティ監査ツール）のみを含め、リリース後の成果指標やビジネス KPI（例：「サポートチケットを 50% 削減する」）は除外します。
• ユーザーストーリー／アクションのインベントリ：受け入れ基準を伴う個別のユーザーアクション
• タスクのカバレッジマッピング：各タスクを 1 つ以上の要件またはストーリーに対応付けます（キーワード、ID やキーフレーズなどの明示的な参照パターンから推定）
• constitution のルールセット：原則名と MUST／SHOULD の規範的な記述を抽出します

4. 検出パス（トークン効率を重視した分析）

重要度の高い指摘に注目します。指摘は最大 50 件とし、残りは超過分の概要にまとめます。

A. 重複の検出

• 重複に近い要件を特定します
• 統合に向けて、品質の低い表現に印を付けます

B. 曖昧さの検出

• 測定可能な基準を伴わない、曖昧な形容詞（高速、スケーラブル、安全、直感的、堅牢）を指摘します
• 未解決のプレースホルダー（TODO、TKTK、???、<placeholder> など）を指摘します

C. 仕様の不十分さ

• 動詞はあるものの、目的語または測定可能な成果が欠けている要件
• 受け入れ基準との整合性が欠けているユーザーストーリー
• spec／plan で定義されていないファイルまたはコンポーネントを参照しているタスク

D. constitution との整合性

• MUST 原則と矛盾する要件または計画要素
• constitution で義務付けられているセクションまたは品質ゲートの欠落

E. カバレッジのギャップ

• 関連付けられたタスクが 1 つもない要件
• 対応する要件／ストーリーがないタスク
• タスクに反映されていない、実装作業が必要な成功基準（パフォーマンス、セキュリティ、可用性）

F. 不整合

• 用語の揺れ（ファイル間で同じ概念が異なる名称で呼ばれている）
• plan で参照されているが spec に存在しないデータエンティティ（またはその逆）
• タスクの順序に関する矛盾（例：依存関係の注記がないまま、基盤のセットアップタスクより先に統合タスクが実行される）
• 要件の競合（例：一方では Next.js を要求し、もう一方では Vue を指定している）

5. 重大度の割り当て

指摘の優先順位付けには、次の基準を使用します。

• CRITICAL：constitution の MUST に違反している、必須の主要な仕様アーティファクトが欠落している、またはベースライン機能を阻害するカバレッジゼロの要件
• HIGH：重複または競合する要件、曖昧なセキュリティ／パフォーマンス属性、テスト不能な受け入れ基準
• MEDIUM：用語の揺れ、非機能要件に関するタスクカバレッジの欠落、仕様が不十分なエッジケース
• LOW：スタイル／表現の改善、実行順序に影響しない軽微な冗長性

6. 簡潔な分析レポートを作成する

以下の構成で Markdown レポートを出力します（ファイルには書き込みません）。

仕様分析レポート

ID	カテゴリ	重大度	場所	概要	推奨事項
A1	重複	高	spec.md:L120-134	類似する要件が 2 つあります ...	表現を統合し、より明確な方を残します

（指摘事項ごとに 1 行追加します。カテゴリの頭文字を先頭に付けた、安定した ID を生成します。）

カバレッジ概要表：

要件キー	タスクあり？	タスク ID	備考

憲章との整合性に関する問題：（該当する場合）

未マッピングのタスク：（該当する場合）

指標：

• 要件の合計数
• タスクの合計数
• カバレッジ率（1 つ以上のタスクがある要件の割合）
• 曖昧さの件数
• 重複の件数
• 重大な問題の件数

7. 次のアクションを提示する

レポートの最後に、簡潔な「次のアクション」ブロックを出力します。

• 重大な問題がある場合：/speckit-implement の前に解決することを推奨します
• 低または中程度の問題のみの場合：ユーザーは続行できますが、改善案も提示します
• 具体的なコマンドの候補を提示します。例：「改善を加えて /speckit-specify を実行する」「アーキテクチャを調整するため /speckit-plan を実行する」「performance-metrics のカバレッジを追加するため tasks.md を手動で編集する」

8. 修正案を提示する

ユーザーに次のように尋ねます：「上位 N 件の問題に対する具体的な修正案を提示しましょうか？」（自動では適用しません。）

9. 拡張フックを確認する

レポートを出力した後、プロジェクトのルートに .specify/extensions.yml が存在するか確認します。

• 存在する場合は読み込み、hooks.after_analyze キー以下のエントリを探します
• YAML を解析できない場合、または無効な場合は、黙ってスキップしてはいけません。パーサーエラーを含め、.specify/extensions.yml を読み込めなかったこと、必須（optional: false）フックを含むフックを確認できなかったことをユーザーに伝え、その後通常どおり続行します
• enabled が明示的に false のフックを除外します。enabled フィールドがないフックは、デフォルトで有効として扱います
• 残りのフックについて、フックの condition 式を解釈または評価しないでください
  • condition フィールドがない場合、または null／空の場合は、実行可能なフックとして扱います
  • 空ではない condition が定義されている場合は、そのフックをスキップし、条件の評価は HookExecutor 実装に委ねます
• フックのコマンド名からコマンド呼び出しを組み立てる際は、ドット（.）をハイフンに置き換えます。例：speckit.git.commit → /speckit-git-commit
• 実行可能な各フックについて、optional フラグに応じて次の内容を出力します

  • 任意のフック（optional: true）：

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • 必須のフック（optional: false）：

    ## Extension Hooks
    
    **Automatic Hook**: {extension}
    Executing: `/{command}`
    EXECUTE_COMMAND: {command}
    

    上記のブロックを出力した後、続行する前に、フックを実際に呼び出し、完了するまで待たなければなりません。このエージェント／セッションで自分がコマンドを実行する場合と同じ方法で実行します（呼び出し方法は、表示されている {command} の ID そのものとは異なる場合があります。たとえば、skills モードのエージェントでは /skill:speckit-... または $speckit-... として実行します）。ブロックを出力するだけでは、フックを実行したことにはなりません。

• フックが登録されていない場合、または .specify/extensions.yml が存在しない場合は、何もせずにスキップします

運用原則

コンテキスト効率

• 最小限の高シグナルなトークン：網羅的なドキュメントではなく、実行可能な指摘に集中します
• 段階的な情報開示：成果物は段階的に読み込み、内容を一度にすべて出力しないでください
• トークン効率の高い出力：指摘事項の表は 50 行までとし、超過分は要約します
• 決定論的な結果：変更がない状態で再実行した場合、一貫した ID と件数が得られるようにします

分析ガイドライン

• ファイルを変更してはいけません（これは読み取り専用の分析です）
• 存在しないセクションを捏造してはいけません（欠落している場合は、正確に報告してください）
• 憲章違反を優先してください（これらは常に重大です）
• 網羅的なルールより例を優先してください（一般的なパターンではなく、具体的な事例を挙げてください）
• 問題がゼロの場合も適切に報告してください（カバレッジ統計を含む成功レポートを出力してください）

コンテキスト

$ARGUMENTS