RaamPrashathT/spec-it

spec-it は何をしますか？

$ARGUMENTS を、フォローアップ質問なしでコーディングエージェントが構築できる仕様と、すべての要件とエッジケースを示すモックアップに変換します。

アイデア → 1. コンテキスト（質問なし） → 2. 製品質問 → 3. 技術質問
     → 4. REQUIREMENTS.md → 5. モックアップ → 6. チェック

references/… のようなパスは ${CLAUDE_SKILL_DIR} からの相対パスです。出力先は spec-it/<kebabケース名>/ です：

spec-it/<名前>/
├── REQUIREMENTS.md      成果物: 意図、決定事項、フェーズ、FR、EC、前提条件
└── mockups/             index.html + 画面、または api.html + openapi.yaml、または cli.html + transcripts.md
    └── assets/          theme.css, fixtures.js, app.js

ルール

1. 事実はあなたのもの、決定は彼らのもの。 リポジトリ、添付ファイル、ウェブ、または標準で答えられることを決して尋ねないでください。開発者のためにスコープ、優先順位、トレードオフを決して決めないでください。
2. すべての質問はその存在価値を証明しなければなりません。 各質問の前に references/questions.md の質問ゲートを実行してください。弁護可能な標準的なデフォルト値がある詳細は、質問ではなく前提条件 (A-n) です。
3. クォータはありません。 最低数はありません。典型的な実行では5～12個の質問を行います。開発者の次の回答を予測できるようになった時点で止めてください。
4. ピッカーを使用して質問する（AskUserQuestion; それなしのプレーンな番号付きテキスト）。呼び出しごとに最大3つの独立した質問まで。ある質問の選択肢が別の未回答の質問に依存する場合、それらをまとめて尋ねないでください。
5. 各質問は一度だけ表示され、メッセージの最後に表示されます。その後、質問を要約しないでください。
6. 状態をディスクに書き込む。 コンテキストステップの後、REQUIREMENTS.md を作業ファイルとして保持します: セクション1～2を早期にドラフトし、決定が確定するにつれて埋めていきます。コンテキスト圧縮後は、動作前にそれを再読してください。
7. モックアップはオフラインで動作します。 CDN、ネットワーク、ウェブフォントは使用しないでください。
8. チェックスクリプトが完了をゲートします: node ${CLAUDE_SKILL_DIR}/scripts/check.mjs spec-it/<名前> が終了コード0で終了する。

ID: FR-n 要件、EC-n エッジケース、D-n 決定、A-n 前提条件。モジュールがある場合、FR/EC/A はモジュールプレフィックスを取ります (BOOK-FR-3)。IDは永続的です: 番号を振り直さないでください。削除する場合は "(removed)" を付けて引退させてください。

1. コンテキスト（まだ質問はありません）

何かを尋ねる前にこれを行ってください。両方のルックアップを並行して実行し、利用可能な場合は新しいコンテキストのサブエージェントを使用します:

• コードベーススキャン（フォルダが空の場合はスキップ）: スタック、アイデアと重複する既存の機能、データモデル、認証、UIキットとデザイントークン、APIとCLIの慣習、中途半端に構築されたもの。最大25行まで。
• 先行技術スキャン（ウェブ検索、2～4回の検索）: 2～3の確立された製品または標準がこれをどのように解決しているか；ドメインの既知の困難な問題（実際の使用でうまくいかないこと）；標準的な機能セット；関連する仕様（RFC、clig.dev、WCAG、支払いまたはプライバシールール）。最大25行まで、ソースリンク付き。

次に、開発者にコンテキスト概要を最大15行で表示します:

調査結果
- リポジトリ: <これが触れるまたは再利用するもの>
- 他の製品のやり方: <製品AはXを行う、製品BはYを行う>
- このドメインの困難な問題: <2～4個、例: 無断キャンセルで部屋が空いたまま; 繰り返し予約>
- 私の見解: <あなたが何を望み、なぜかを一文で仮説> · 確信度 <n>%

タイプ（UI、API、CLI、混合）を分類し、assets/requirements-template.md から REQUIREMENTS.md を作成し、セクション1とコンテキストセクションを記入します。見つけた困難な問題は、最良の質問のための素材です。

2. 製品質問

references/questions.md を読んでください。最もリスクの高い未知のものから取り組みます: これは正しい問題か、誰のためか、何を最初に出荷するか、何が範囲外か、次にドメインの困難な問題を具体的なシナリオとして。各回答を D-n としてセクション「決定事項」に記録します。

次の3つすべてが成り立ったら、技術質問に切り替えます:

• 開発者の言葉で再説明（成果、ユーザー、なぜ今、成功、範囲外）を書ける；
• フェーズ1のスコープと非目標が合意されている；
• 残っているのは 方法 についてであり、何を、誰に、なぜ ではない。

例外: スコープを変えるハードな制約（"オフラインで動作必須"、"既存のAuth0テナントを再利用"、"データはEU内に留める"）は、それが表面化した時点で尋ねます。なぜなら製品質問の形を変えるからです。

3. 技術質問

分岐点でのみ: リポジトリと標準がそれを解決せず、回答がデータモデル、契約、またはユーザーから見える振る舞いを変える場所。リストは references/questions.md のセクション「技術」にあります。多くの実行では0～4個必要です。リポジトリが既に固定しているホスティング、CI、フレームワーク、ベンダーの選択肢については決して尋ねないでください。

確認ゲート。 1つのメッセージ: 再説明（6行）、次にあなたが取ったすべての前提条件（A-n、各行1つ、デフォルト値付き）。確認するか、変更するものを指定するかを尋ねます。変更を反映します。明示的な「はい」の後にのみ、仕様のステータス行に Status: Confirmed を書き込みます。

フェーズとモジュール

フェーズ（常に検討）。 「何を最初に出荷するか」という製品質問がそれらを決定します。フェーズ1は、ユーザーがコアジョブをエンドツーエンドで完了する最も薄いスライス（ウォーキングスケルトン）です。開発者がすべてを一度に望む場合、1つのフェーズがあります。すべてのFRは Phase: n を持ちます。フェーズ1は完全に仕様化されます。後のフェーズは、--next-phase がそれらを詳細化するまで、セクション「デリバリープラン」の各機能につき1つの箇条書きです。

モジュール（シグナルのみ）。 次の2つ以上に該当する場合のみ、領域をモジュールとして扱います: 異なる人または語彙；独自のデータを持つ；単独で出荷された場合に有用；独自の10以上の質問が必要。2つ以上の該当領域がある場合、一度尋ねます: モジュールセクション付きの1つの仕様 (推奨)、または最も重要なモジュールを今仕様化し、残りを概説する。アイデアの大きさからモジュールを推測しないでください。モジュールは同じ REQUIREMENTS.md に ## セクションとしてセクション「機能要件」の下にIDプレフィックス付きで残ります。

サイズ制限。 フェーズ1が約25個のMust FRまたは12個のモックアップアーティファクトを超える場合、どれをフェーズ2に移動するかを尋ねます。

4. REQUIREMENTS.md を書く

テンプレートを埋めてください。すべてのFRにはID、優先度、フェーズ、Given/When/Then、および Source: 決定IDがあります；提起されたすべてのエッジケースは、具体的なフィクスチャ値を持つ EC-n になります。FRはユーザーが観察することを述べます；テクノロジーはセクション「技術決定事項」に入ります。その後、次のリストに対して自己レビューを一度行い、失敗するものを修正します:

• 両方が成り立たない2つの文；2回述べられた1つのルール。
• 開発者が2つの異なる方法で構築できるFR（欠落した制限、単位、役割、または障害動作）。
• 観察によって合格または不合格にならない基準、または数値のない曖昧な単語。
• FRのない役割、エンティティ、またはフロー；何も引用していない決定。
• 用語集に反して使用された単語。

5. モックアップ

アーティファクト（画面、エンドポイントグループ、またはコマンドグループ）を最大12個リストアップし、それぞれの状態と、すべてのECを状態にマッピングします。リストを1つのメッセージで表示し、開発者が反対しない限り先に進みます。次に references/screens.md（UI）または references/api-cli.md（API、CLI）を読み、構築します:

1. 最初に mockups/assets/fixtures.js を書く: 任意のアーティファクトが表示するすべての名前、ID、金額、日付。
2. UI: デザインの方向性をセクション「デザインの方向性」に書く。リポジトリにデザインシステムまたはトークンがある場合、それに従い、デザイン質問をスキップする；そうでなければ、選択肢プレビューにASCIIスケッチを含む1つのデザイン方向性の質問をする。
3. ${CLAUDE_SKILL_DIR}/assets/theme.css と app.js を mockups/assets/ にコピーし、トークンを設定し、コントラストが合格するまでチェックを実行する。
4. references/renderer.md から各アーティファクトを構築する: 4つ以上のアーティファクトとサブエージェントツールがある場合、各アーティファクトに対して並行して1つのサブエージェント；そうでなければここで一度に1つ。CLI: mockups/transcripts.md を書き、次に node ${CLAUDE_SKILL_DIR}/scripts/cli-render.mjs spec-it/<名前> を実行する。
5. ${CLAUDE_SKILL_DIR}/assets/index.html から mockups/index.html を埋める。
6. ブラウザツールを使用するUI: オプションで references/critic.md を実行し、そのトップ修正を一度適用する。

6. チェックと報告

チェックスクリプトが終了コード0で終了するまで実行します；曖昧さの警告は、文言を明確にする必要があるものとして扱います。最大10行で報告する: パス、カウント（質問数、FR、EC、前提条件、アーティファクト）、チェックサマリー行、モックアップの表示方法（mockups/index.html を開く、または node ${CLAUDE_SKILL_DIR}/scripts/serve.mjs spec-it/<名前>）、そして次のフェーズがあればそれ。node ${CLAUDE_SKILL_DIR}/scripts/export.mjs spec-it/<名前> は、要求に応じて共有用の単一ファイルコピーを書き出します。

後続の実行

• --next-phase: 仕様を読み、次のフェーズの箇条書きを取得し、それらに対してのみステップ2～6を実行します（質問はフェーズ1が未解決のままにしたものから始まります）。新しいFRは番号を継続します；以前のIDは決して変更されません。
• --revise（または変更リクエスト）: 新しい決定を記録し、影響を受けるFRとECを更新し、影響を受けるアーティファクトのみを再レンダリングし、チェックを再度実行します。

正当化

考え	現実
「すべての領域をカバーすべきなので、統合について尋ねよう。」	回答が仕様を変える場合のみ尋ねること。"v1にはなし" は前提条件です。
「どの時間ステップを希望するか尋ねよう。」	標準的なデフォルト値が存在します。A-n を記録；確認ゲートがそれを表示します。
「アイデアは明確だ。コンテキストステップをスキップしよう。」	コンテキストステップこそ、良い質問が生まれる場所です。常に実行してください。
「アイデアが大きそうなので、モジュールだ。」	モジュールにはシグナルが必要であり、次に開発者の選択が必要です。
「彼らはすべての推奨を受け入れた。素晴らしい。」	推奨は安全すぎるかもしれません。あなたの次の質問は、彼らが同意しない可能性があるものであるべきです。