specsfy-03-specify

単一の仕様書を作成する

必須の準備

このスキルを実行する前に、プロジェクトのルートで $specsfy-setup を必ず読み込んでください。自動ハンドオフの場合は、このステップの前にもう一度読み込んでください。会話で確認済みのルートを再利用し、セットアップで未解決の問題が示された場合は先に進まないでください。

対話モード

対話モード：perguntas。 質問を作成する前に、.specsfy/Spec.md の Contrato de perguntas numeradas を読んで適用してください。

パッケージ specs/draft/<NNNN>-<slug>/ を作成または更新してください。このパッケージでは、spec.md が SDD フロー全体の唯一の規範的な情報源です。番号を付けるのはディレクトリのみとし、ファイル名は常に spec.md にしてください。発見、リサーチ、明確化、プロダクト、技術計画、データモデル、契約、TDD、BDD、検証、タスク、決定、完了を、明示的な3つの行為に統合してください。参照した外部の根拠資料は research/ に保存してください。plan.md、research.md、data-model.md、tasks.md、チェックリスト、または2つ目の仕様書は生成しないでください。

Laravel の仕様書を統合する前に、.specsfy/PACKAGES.md、 docs/packages/README.md および docs/packages/ 内のパッケージ資料を読んでください。依頼にパッケージの GitHub URL が含まれる場合、または Composer ライブラリに依存する場合は、パッケージがすでに存在するか確認し、依存関係を重複させずに必要性を記録するため、$specsfy-specialist-laravel-package-manager を読み込んでください。

会話をオーケストレーションする

このステップを完了したとき、または別のステップに属する作業を検出したときは、Pendência detectada: <descrição> — ação: resolvendo nesta etapa と告知し、それがこのステップのスコープに属する場合は解決してください。担当を切り替える場合は、Transição automática: $specsfy-03-specify → $<destino> — motivo: <motivo> — resultado esperado: <resultado> と告知し、確認を求めたりコマンドを繰り返したりせず、直ちに移行先のスキルを読み込んでください。同じ会話を続けてください。このステップに必要な修正を行った後は、Retomada automática: $<destino> → $specsfy-03-specify — pendência resolvida: <resultado> と告知し、直ちにこのステップに戻ってください。サイクルを避けるため、ハンドオフのたびに状態を再評価してください。ハンドオフの確認は求めないでください。ただし、機微な操作には引き続き個別の許可が必要です。

準備

1. ユーザーが指定したディレクトリ、または別の指定がない場合は Path.cwd() からプロジェクトのルートを解決してください。Git ルートを探したり、そこへルートを変更したりしないでください。
2. 仕様書を作成するときは、このスキルのディレクトリを解決し、書き込み前に次を実行してください。

node <diretório-da-skill>/scripts/iniciar_spec.mjs \
  --title "<nome da especificação>" [--slug <slug>] [--root <raiz>]

3. スクリプトが出力した絶対パスを使用してください。スクリプトは次のローカル ID を割り当て、.specsfy/templates/custom/Spec.md を優先し、管理対象のテンプレート .specsfy/templates/Spec.md をフォールバックとして使用し、specs/draft/<NNNN>-<slug>/spec.md のみを作成します。ファイル名に ID を含める形でファイルをリネームしないでください。このリポジトリを開発する際は、スクリプトは skills/templates/Spec.md をフォールバックとして使用します。利用者のプロジェクトでテンプレートがない場合は、specsfy install が必要です。
4. 更新する場合は、指定された既存の仕様書パス、または現在のルート配下で見つかった仕様書パスを使用してください。初期化スクリプトを再実行しないでください。
5. specs/inbox/ のソース記録、バックログ項目、バックログの精緻化ブリーフ、現在の依頼、そのパスにある仕様書、その research/、および実際の制約を示すリポジトリ内のファイルを読んでください。
6. 問題、アクター、結果を特定する情報が不足している場合は、未解決事項を告知し、サイクルを実行するために $specsfy-02-backlog を読み込んでください。サイクルの終了時にこのスキルに戻り、作成された完全または部分的なブリーフを使用してください。
7. 精緻化する対象が報告、ストーリー、トランスクリプト、または仕様書である場合は、references/mcr-10.md を読んでください。
8. .specsfy/DATABASE.md が存在する場合は読んでください。ジャーニーが保存情報に依存しており、そのファイルにプロダクトが何を記憶する必要があるか、誰がその情報を使うか、いつ不要になるかが記載されていない場合は、$specsfy-data-discovery を読み込んでください。記録が確定した後、このスキルに戻ってください。

MCR-10 を適用する

1. 元の表現を保持し、目的、アクター、結果を特定します。
2. 曖昧な用語、用語上の同等性、派生語を分析します。
3. 実体、量、質、関係、場所、時間、位置、所有、行為、被作用を、質問票ではなく柔軟な視点として使います。
4. 分析中に生じた推論、仮説、決定、対立、未解決の問いと、本人による各発言を区別します。
5. 該当する不足がある場合は、$specsfy-02-backlog を読み込み、領域ごとに最大 8 件の質問に制限したサイクルを実行し、サイクルの最後にこのスキルに戻ります。本人が avançar を選択した場合は、中央の契約で定められた確認と記録を適用します。該当する点が残っている場合は、Status: Draft と Definition Gate: Pending を維持し、仕様を Defined に昇格させず、この再開時に同じサイクルを再開しないでください。
6. 決定を、主語、条件、アクション、観察可能な効果を含む記述に再構成し、ルール、ストーリー、Gherkin、境界、失敗を導き出します。
7. 結果は spec.md の既存のセクションに記録します。MCR 専用のレポートは生成せず、参照をスライスのパッケージにコピーしないでください。

作成する

• <raiz>/specs/draft/<NNNN>-<slug>/spec.md に必ず保存します。ID はディレクトリに属し、ファイル名は必ず spec.md のままにします。
• <raiz>/specs/draft/<NNNN>-<slug>/research/ は、実際に参照したコピー、スナップショット、契約、スキーマ、例、出典メモにのみ使用します。このディレクトリに本番コード、テスト、規範文書を置かないでください。
• API または外部ドキュメントを調査する際は、許可された証拠を research/ に保存し、パス、出典、バージョン／日付、ライセンス、影響を「保存された調査成果物」に記録してください。ライセンスまたは規約によりコピーが禁止されている場合は、メタデータ、URL、アクセス日、入手可能であればチェックサム／バージョン、および独自のメモを保存し、保護対象の内容を複製しないでください。
• spec.md と research/ 以外に、feature パッケージ内の別の項目を作成しないでください。
• specs/backlog/<NNNN>-<slug>.md を昇格させる場合は、そのパスを spec に記録し、項目を Status: Promoted に更新して、作成した spec のパスを記載してください。backlog は出典情報を保持しますが、動作を規定するものではなくなります。
• specs/inbox/<data-hora>-<slug>.md から直接派生させる場合は、そのパスを spec に記録し、取り込み時の記録を変更せずに保持してください。初期分析は文脈であり、確認済みの要件ではありません。
• ヘッダーは、Campo と Valor の2列からなる Markdown テーブルのまま保持してください。メタデータを **Campo**: valor 形式の行に変換しないでください。
• テーブルでは ID を SPEC-NNNN、Slug を <NNNN>-<slug> とし、slug は親ディレクトリと同じものにしてください。
• 解決済みのテンプレートの3つの節と18のセクションを正確に保持してください。テンプレートは、存在する場合は .specsfy/templates/custom/Spec.md、それ以外の場合は .specsfy/templates/Spec.md を使用します。
• 精緻化の際は、モデルに残っている編集用コンテンツを置き換えてください。Defined に昇格した spec に、例やプレースホルダーを残さないでください。
• 更新する場合は既存のファイルを編集し、引き続き有効な ID と決定を保持してください。
• 新しい項目には番号を付け、削除済みの ID を再利用したり、番号を振り直したりしないでください。
  • ストーリー：US-001；
  • 機能要件：FR-001；
  • 非機能要件：NFR-001；
  • 受け入れシナリオ：AC-001；
  • 決定事項：DEC-001。
• 各要件は、検証可能な動作として記述してください。
• 各シナリオは Given/When/Then 形式で記述し、少なくとも1つの要件に関連付けてください。
• feature 全体、および各 US、FR、NFR に対して、異なる AC を最低3つ定義してください。**Cobre** に ID が記載されている場合にのみ、カバレッジとして数えます。シナリオが同等の内容で重複しないようにしながら、基本フロー、重要なバリエーション／ルール、および重大なエラーや制約を含めてください。
• 関連する場合は、スコープ外の事項、エラー、制約、セキュリティ、アクセシビリティを含めてください。
• ヘッダーで Interface para pessoas: Sim と宣言する場合は、セクション10に、テンプレートの9つの項目すべてを記入してください。スタックとローカル規約、画面、情報フロー、メニューと主要ナビゲーション、フォームと操作、構成、React ブロックと shadcn/ui／ReUI コンポーネント、状態、アクセシビリティを含めます。スタックと既存システムの情報源として、INTERFACE.md、.specsfy/STACK.md、manifests、既存の画面とコードを使用し、維持するものと変更するものを記録してください。互換性のないライブラリを提案したり、既存画面を調査せずに再構成したりしないでください。$specsfy-specialist-ux-design、$specsfy-specialist-ui-design、およびインターフェーススタックの専門家を読み込んでください。API、データベース、サービスしか記載されていない CRUD の説明は受け入れないでください。 Laravel と React を使用する場合は、shadcn/ui と ReUI、予定する React ブロックすべて、それぞれの役割、ファイル、元になるコンポーネント、再利用ルールを明記してください。ページはこれらのブロックを組み合わせるだけにしてください。
• インターフェースがない場合は、Interface para pessoas: Não と宣言し、その成果物が画面上で人に利用されない理由を説明してください。
• 技術セクションは、内部的な選択とユーザーにとっての結果を混同せず、ファイルパスを含むタスクを作成できるだけの具体性を保ってください。
• 変更可能なデフォルト値は Suposições に記録してください。妥当な選択肢によってスコープ、データ、セキュリティ、UX、テストが大きく変わる場合に限り、明確化を求めてください。
• Defined とマークされたファイルには、プレースホルダー、テンプレートの例、TBD、TODO、明確化用マーカーを残さないでください。
• 今後のタスクは 14. Tarefas セクションに記載してください。後続の skill は別ファイルではなく、必ず同じセクションを更新します。
• 別個のレポートを作成せず、メタデータ Definition Gate、Plan Gate、Delivery Gate を使って準備状況を表してください。

すでに承認済みの仕様を尊重する

仕様がすでに Definition Gate: Passed となっており、追加、削除、修正、変更を求められた場合は、保留中の作業を伝え、自動的に $specsfy-update-spec を読み込んでください。このスキルは影響を分類し、規範となるソースを更新して、影響を受けるゲートのみを無効化します。変更によって仕様が初期の定義状態に戻った場合に限り、このスキルを再開してください。

トレーサビリティを維持する

各 FR と NFR について、最低3つの AC シナリオを示し、NFRの検証方法を明記してください。各ストーリーについて、その価値を実現する要件と、最低3つの AC を特定してください。TDDのテストケースとセクション14でも、同じIDを使用してください。

リサーチを管理する

• 計画の前に、インデックス済みのエビデンスのみを読み込み、以下で主張を検証してください。

node .agents/skills/specsfy-03-specify/scripts/load_research.mjs \
  specs/<estado>/<NNNN>-<slug>/spec.md

• 重要な調査については、R-ID、重大度、主張、判定、信頼度、ローカルエビデンス、予算をセクション2に記録してください。未検証の critical な主張がある場合、ハンドオフをブロックします。反証された主張も記録に残してください。IDは一意にし、支出が上限を超えないようにしてください。また、引用するMarkdownアンカーがローカルファイルに存在することを確認してください。

自動検証する

ファイルが Draft の間は、中間的な構造検証を実行してください。

node .agents/skills/specsfy-04-validate/scripts/validate_spec.mjs specs/<estado>/<NNNN>-<slug>/spec.md --allow-draft

構造上の不備は、最大3サイクル以内に修正してください。specsfy-04-validate スキルが意味的なレビューを行い、その結果をセクション13に記録して、Definition Gate: Passed と Status: Defined に更新します。それまでは Status: Draft と Definition Gate: Pending を維持し、ブロック要因となる判断を報告してください。

報告する

以下を報告してください。

• パス specs/<estado>/<NNNN>-<slug>/spec.md；
• 保存したリサーチのパス、または外部ソースがなかった旨；
• ステータス；
• US、FR、NFR、AC の件数；
• 重要な前提；
• $specsfy-04-validate への自動移行と、その理由および期待される結果。

必要に応じて専門家を呼び出す

要件、NFR、データ、技術的な判断で専門知識が必要な場合は、references/specialists.md を読んでください。仕様に要件を記録し、専門家の読み込みを提案してください。インストールされていない場合は、インストールする前に個別の許可を求めてください。