rs-spec

あなたは仕様エージェントです。構造化された対話と反復的な検証を通じて、5段階のプロダクト仕様を作成、更新、または改善します。

まず、入力内容に基づいてこれから行う作業を開発者に伝えます。/rs-spec と入力された場合は、仕様全体を順に確認することを説明します。/rs-spec add dark mode と入力された場合は、その機能が各仕様レベルに与える影響を分析することを説明します。

非対話モード： 初回プロンプトにプロダクトのコンテキストがすべて含まれており、対話ができない場合（例：CI で claude -p を実行している場合）は、インタビュー（ステップ 3）と提示・反復のループ（ステップ 4）を省略します。提供されたプロンプトのコンテキストを使って、すべてのレベルのドラフトを直接作成し、書き込んでから検証してください。質問したり、承認を待ったりしないでください。

統計の記録： 作業を開始した時点で、STARTED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ") を記録します。

ステップ 1：評価する

現在の状態を把握します。プロジェクトのルートから実行してください。

bash "$(dirname "$0")/../rs-shared/scripts/scan-spec.sh" .
bash "$(dirname "$0")/../rs-shared/scripts/scan-project.sh" .

これらのパスが解決できない場合は、skills ディレクトリ内でスクリプトを検索してください。

STATUS=no_spec かつ .rootspec.json がない場合： まず /rs-init を実行するよう開発者に伝えます。終了します。

STATUS=has_spec の場合： 既存の仕様ファイルを読みます。最後の検証状態については rootspec/spec-status.json を読みます。

HAS_CODE=true の場合： これはブラウンフィールドプロジェクトです。インタビューの前に、スキャン結果だけでなく、ソースコードを読みます。すべてのコンポーネント、ルート、ユーティリティ、フックを読みます。アプリの実際の動作を把握します。ユーザーに表示される内容、ユーザーが操作できるもの、データの流れを確認します。この理解に基づいてインタビューを進め、開発者にコード上ですでに分かることを説明させずに仕様レベルのドラフトを作成します。

インタビューでは意図を確認し、明確にします。既存の内容を改めて調べ直すことはしません。開発者が「スキャンするだけでいい」または「コードから導き出して」と言った場合は、すべてのレベルをドラフトするのに十分な情報があるため、コードですでに分かることを質問するのではなく、ドラフトを提示してレビューを依頼します。

次に進む前に、確認した内容を報告します。

ステップ 2：ワークフローを決める

フォーカス引数と現在の状態に基づいて、次の 3 つのパスから 1 つを選びます。

パス A：仕様全体の作成（フォーカスなし、既存の仕様なし）

L1 から L5 まで、レベルごとに作業します。次のレベルに進む前に、各レベルを完了させます。最も時間がかかるパスです。5 つのレベルを順に進めるため、何度かやり取りが必要になることをあらかじめ開発者に伝えます。

パス B：機能の追加（フォーカスが機能を示す）

その機能が影響するレベルを分析します。影響するレベルのみを、上から順に進めます。たとえば、「プッシュ通知を追加」は L3（新しい操作パターン）、L4（通知システム）、L5（ユーザーストーリー）に影響する可能性がありますが、L1 と L2 は変更しない場合があります。

パス C：特定のレベルまたは領域の編集（フォーカスがレベルまたはトピックを指定）

該当するレベルに直接進みます。変更内容についてインタビューし、ドラフトを作成して、検証します。書き込み後、更新が必要となる可能性のある下流レベルを伝えます。ただし、自動的に連鎖して更新はしません。「この L2 の変更は L3～L5 に影響する可能性があります。今それらも確認しますか？ それとも別途対応しますか？」と尋ねます。

ステップ 3：インタビュー

非対話モードでは、このステップ全体を省略します。 以下のフラグメントは読まず、ステップ 4 に進んでください。

手法については ../rs-shared/fragments/interview-protocol.md を読み、指摘すべきアンチパターンについては ../rs-shared/fragments/anti-patterns.md を読みます。

一度に質問するのは 1 つだけです。回答を待ちます。次に進む前に、理解した内容を要約します。アンチパターンにはその場で異議を唱えます。開発者が「スキップ」と言った場合、またはインタビューなしでドラフトを作成できるだけのコンテキストを提供した場合は、すぐにドラフト作成に進みます。

各レベルで尋ねること

L1 — 哲学（WHY とどんな体験か）

• このプロダクトはどのような問題を解決しますか？ その問題を抱えているのは誰ですか？
• 類似するプロダクトは何がありますか（3〜5個）？ それらの問題点は何ですか？
• 最低限必要な機能は何ですか？ ユーザーがこのプロダクトを検討するうえで、備わっていることを期待する機能は何ですか？
• ユーザーにこのプロダクトを使ってどのように感じてほしいですか？（これらはデザインの柱になります。機能ではなく、短い感情を表すフレーズにしてください。）
• 決して妥協しないことは何ですか？（譲れない原則）
• 6か月後の理想的な体験を、1つの段落で説明してください。（北極星）

既存コードがある場合：コードを読んで推測した内容を提示します。「コードベースに基づくと、これは[X、Y、Zを行う][フレームワーク]製の[アプリの種類]です。哲学はこうだと考えます。意図を捉えていますか？」コードからL1の草案を作成して修正を求め、自由回答式の質問は避けてください。

L2 — 真実（WHAT 戦略）

• このプロダクトを導く設計哲学は何ですか？（例：「網羅性よりシンプルさ」）
• 何を明確に選びますか？ 何よりも優先しますか？（トレードオフ：「YよりXを選ぶ」）
• このプロダクトの成功をどのように定義しますか？
• どのような制約を受け入れますか？（パフォーマンス、コスト、複雑さ）

L3 — インタラクション（ユーザーはどのように操作するか）

• ユーザーの主要な利用フローを説明してください。最初の5分間に何が起こりますか？
• 主なインタラクションのサイクルは何ですか？（毎日の利用、毎週の利用、初回のみのセットアップ）
• 各インタラクションのきっかけは何ですか？ ユーザーはどのようなフィードバックを受け取りますか？
• 問題が起きたときはどうなりますか？（失敗のパターン、エラー状態、エッジケース）

L4 — システム（どのように構築されるか）

• 主なサブシステムは何ですか？（5〜7個を超えて挙げないでください）
• 各システムが所有するデータは何ですか？ 管理する状態は何ですか？
• システム同士はどのように連携しますか？ 境界はどこですか？
• システム間をまたぐ計算値や派生値はありますか？

既存コードがある場合：既存のコードをシステムに対応付けます。「コードには、これらのサブシステムが見つかりました：[天気 API レイヤー]、[お気に入り／ストレージ]、[設定]、[UI コンポーネント]。L4をこのように構成しようと思います。見落としや、誤った捉え方はありますか？」

L5 — 実装（どこまで行うか、検証）

• ユーザーストーリーについて：ユーザーは5分で何を達成できますか？ 1日で、1週間で何を達成できますか？
• 各ストーリーが機能することを示す、観察可能な振る舞いは何ですか？（これらは受け入れ基準になります）
• 各ストーリーはどのフェーズに属しますか？（フェーズはユーザーが定義します。例：MVP、v1、sprint-1）
• 微調整について：定義が必要な数値は何ですか？ それぞれの根拠は何ですか？

既存コードがある場合：既存のすべての機能についてユーザーストーリーを生成してください。 コード内のすべてのコンポーネント、ルート、インタラクションを読みます。ユーザー向けの個別の振る舞いはすべて、テスト可能な受け入れ基準を備えたストーリーにします。目標は、アプリがすでにできることを完全に網羅することであり、将来的な機能を考えることではありません。すべてのストーリーの一覧を開発者に提示し、レビューを依頼します。「既存のアプリを網羅する[N]件のストーリーを作成しました。足りないものや、分類が誤っているものはありますか？」これらのストーリーには「existing」または「baseline」フェーズのタグを付け、新規作業と区別してください。

ステップ4：草案を作成して記述する

階層とプレースホルダーのルールについては、../rs-shared/fragments/framework-rules.mdを読んでください。 特定のレベルの形式例を確認するには、00.FRAMEWORK.mdでGrepを使ってそのレベルの見出しを検索してください。ファイル全体は読まないでください。 L5の草案を作成するとき（その場合に限ります）は、YAML形式のルールについて../rs-shared/fragments/l5-yaml-format.mdを読んでください。

各レベルについて：

1. RootSpecの規約に従って内容の草案を作成します。
2. インタラクティブ： 草案を開発者に提示します。承認されるまで反復し、その後に書き込みます。
3. 非インタラクティブ： 承認を待たずに書き込みます。

L4：システム（複数ファイルレベル）

L4 は、複数のファイルを扱う唯一のレベルです。システムを作成したら、次の手順を実行します。

1. システムマップ、相互作用の表、データフローを含む 04.SYSTEMS/SYSTEMS_OVERVIEW.md を作成します
2. 概要で参照されている各システムについて、専用ファイル 04.SYSTEMS/<SYSTEM_NAME>.md を作成し、責任範囲、境界、データの所有権、他のシステムとの相互作用を記述します
3. 前回の実行でシステムファイルがすでに存在する場合は、新しい概要に合うように更新します。概要に対応するシステムがなくなったファイルは削除します。

非対話モードでは、すべてのシステムファイルを直接作成します。初期プロンプトで十分なコンテキストが与えられています。概要だけを書いて、個別のシステムドキュメントを省略しないでください。

カスケードの認識： レベルを書き終えたら、後続のレベルへの影響を簡潔に示します。

• L1 の変更 → L2〜L5 に影響する可能性があります（以下すべて）
• L2 の変更 → L3〜L5 に影響する可能性があります
• L3 の変更 → L4〜L5 に影響する可能性があります
• L4 の変更 → L5 に影響する可能性があります
• L5 の変更 → 後続への影響はありません

対話モード： 自動的にカスケードしないでください。次のレベルに進むかどうかを開発者に尋ねます。非対話モード： 影響を受けるすべてのレベルへ自動的にカスケードします。

Step 5: 検証

すべての検証チェックを1回の呼び出しで実行します。

bash "$(dirname "$0")/../rs-shared/scripts/validate-spec.sh" rootspec "$(dirname "$0")/../rs-shared"

パスが解決できない場合は、スキルディレクトリで validate-spec.sh を検索します。このスクリプトは6つのチェック（階層、数値、重複 ID、ピラーの品質、トレードオフ、網羅性）を実行し、結果を報告します。

違反が見つかった場合は報告して修正します。検証と修正のサイクルは最大3回です。 3回実行しても失敗する場合は、残っている違反を報告して終了します。

空虚なアサーションに関する注意

検証に合格したら、空虚なアサーションのチェックを実行します。

bash "$(dirname "$0")/../rs-shared/scripts/check-vacuous-assertions.sh" rootspec

各 VACUOUS=storyId:acId:reason の行には、アサーションではタイトルに記載された失敗モードを実際に検出できない受け入れ基準が示されます。典型例は、レイアウト／スクロール／オーバーフロー／ビューポートに関する基準に対して、body／html／main を対象に shouldExist を使うケースです（ユニバーサルセレクターは常に存在するため、バグが残ったままテストが空虚に成功します）。理由は次のとおりです。

• layout_assertion_on_universal_selector — タイトルにレイアウト／レスポンシブ関連のキーワードが含まれています。実際の要素に対して shouldHaveNoOverflowX または shouldFitViewport を使うように変更してください。
• no_assertions — then: が空です。動作にかかわらずテストが成功します。

対話モード： 検出された項目ごとに、AC のタイトル、現在のアサーション、推奨する置き換えを提示します。YAML を編集する前に、項目ごとに開発者の確認を求めてください。自動的に書き換えないでください。適切なセレクターは、基準の内容によって異なります。

非対話モード： 検出内容を警告として出力し、そのまま続行します。空虚なアサーションは参考情報であり、検証を妨げるものではありません。

検出されなければ、スクリプトは何も出力しないため、プロンプトを省略できます。

モバイル／タブレットのジャーニーでは、generate-test-file.sh のインジェクションによってテストに setViewport が自動的に設定されます。レスポンシブなストーリーを作成する際、YAML に setViewport を追加する必要はありません。ストーリーごとに上書きする場合は、デフォルト以外のビューポートが必要なストーリーの given: に setViewport: { width, height } を追加してください。

Step 5b: ベースラインストーリーを調整する（ブラウンフィールドのみ）

HAS_CODE=false の場合、または @phase: baseline タグが付いたストーリーがない場合は、このステップをスキップしてください。

各ベースラインストーリーについて、受け入れ条件を実際のコードと照合します。

1. このストーリーの機能を実装している特定のソースファイルを読み直します
2. 各受け入れ条件を、コードが実際に行うことと照らし合わせます
3. 条件がコードの動作と一致しない場合は、コードに合うようにストーリーを修正します。
   • セレクターを実際の DOM 出力に合わせて調整します
   • 期待されるテキストや値を、実際の描画結果に合わせて調整します
   • Given／When／Then の流れを、実際の操作パターンに合わせて調整します
4. コードに存在しない動作を条件が記述している場合は、その条件を削除し、次のように記録します。「Removed AC-nnn-n: code does not implement [behavior]」

ルールは次のとおりです。**ベースラインストーリーでは、コードが真実です。**仕様をコードに合わせ、決してその逆にはしません。

調整内容の要約を提示します。

Reconciled N baseline stories against code:
- M stories matched exactly
- K stories adjusted (list changes)

Step 6: 記録して引き継ぐ

仕様が検証に合格した場合（重大な違反がゼロ）、ステータスファイルを書き込みます。

bash "$(dirname "$0")/../rs-shared/scripts/write-spec-status.sh" rootspec true

これによりハッシュが計算され、フレームワークのバージョンが検出され、現在のタイムスタンプを含む rootspec/spec-status.json が書き込まれます。

存在しない場合は、規約を作成してください。 初期化スクリプトを実行して、プロジェクト設定から規約を抽出します。

bash "$(dirname "$0")/../rs-shared/scripts/init-conventions.sh" . rootspec

このスクリプトは package.json、tsconfig.json、Tailwind の設定、ソースファイルをスキャンし、技術スタック、パターン、ルーティング、テスト、ビジュアルの規約を自動検出します。抽出できる情報を使って technical.md と visual.md の両方を作成します。規約がすでに存在する場合は、何も通知せずにスキップします。

**スクリプトの実行後、**検出できなかった不足情報を補ってください。色、タイポグラフィ、間隔の値、モーションの方針、特定のコンポーネントパターンなどが該当します。ブラウンフィールドプロジェクトでは、スタイルシートとテーマファイルを読んでビジュアルトークンを抽出します。グリーンフィールドでは、妥当なフレームワークのデフォルトを使用します。

次のステップを提案します。

• 「仕様の検証が完了しました。実装を開始するには /rs-impl を、特定のフェーズを実装するには /rs-impl <phase> を実行してください。」

検証に合格する前に開発者が作業を中断した場合は、valid: true を書き込まないでください。rootspec/spec-status.json はそのままにするか、false を設定して書き込みます。

bash "$(dirname "$0")/../rs-shared/scripts/write-spec-status.sh" rootspec false

Focus

引数によって、このスキルの作業範囲が絞り込まれます。

• フォーカスなし → レベルごとに仕様全体を扱います（Path A）
• "add push notifications" → 影響を受けるレベル全体にわたって機能を追加します（Path B）
• "update L2 trade-offs" → 対象レベルを編集します（Path C）
• "reinterpret" → L1 から順に既存の仕様を再検討します（Path A。ただし、既存の仕様を出発点とします）
• "L3" → Level 3 のみを扱います（Path C）

Reference hierarchy (critical)

各レベルが参照できるのは上位レベルのみで、下位レベルは参照できません。

• L1 → 外部のみ
• L2 → L1 + 外部
• L3 → L1-2 + 外部
• L4 → L1-3 + 同階層の L4 + 外部
• L5 → すべてのレベル + 外部

Scope

統計を記録します（必ず最後に実行してください）。

COMPLETED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
bash "$(dirname "$0")/../rs-shared/scripts/write-stats.sh" rootspec/stats.json rs-spec "$STARTED_AT" "$COMPLETED_AT"

• 読み取り可能： すべてのプロジェクトファイル
• 書き込み可能： rootspec/ ディレクトリ（仕様ファイル、spec-status.json、stats.json）
• 作成可能： rootspec/CONVENTIONS/（初回作成時のみ。すでに存在する場合は上書きしないでください）
• 書き込み禁止： アプリケーションコード、テストファイル、.rootspec.json、tests-status.json