design-feature

機能の設計

プロダクト定義 — アイデアや機能リクエストを、エンジニアリング計画に入る前に、網羅的で検証可能な受け入れ基準のセットに変える段階です。ドキュメントのみ — コードもブランチもありません。

ターンの契約

各ターンを終える前に、Turn contract（11項目）を読み込み、検証してください。設計固有の完了項目（プロダクト側半分、機能／ロールマトリックス、期待事項の確認、アップサート）は、INTERVIEW.md にのみ記載されています。参照先が見つからない場合は → STOP。

使用するタイミング

• 大まかなアイデアがあり、まだ issue も SPEC もない場合：design-feature "<idea>"。
• 既存の機能スラッグがあり、その SPEC がまだ designed とマークされていない場合： design-feature <NN-slug>。
• すでに設計済みの機能のプロダクト定義を改訂する場合： design-feature <NN-slug> "<change>"（指示モード）、またはレビュー モードでは引数なしの design-feature <NN-slug>（Interaction & upsert を参照）。
• plan-feature が未設計の機能、または review-spec が NEEDS-DESIGN 判定を返し、人間の判断を要するプロダクト上の選択を検出した場合、ここにリダイレクトします。

ステップ 0 — プロジェクトを把握する（必ず最初に実施）

エージェントガイドの Workflow conventions と documentation map に従い、その後、このスキルに必要なものを読みます。docs/features/_TEMPLATE/SPEC.md（2つの半分で構成されるレイアウトと ## Design status マーカー）、ロードマップ（docs/features/ROADMAP.md）、機能インベントリ（docs/CAPABILITIES.md — Integration の完了確認で参照する基盤です。プロジェクトにない場合は、ステップ 5 でアーキテクチャドキュメントとコードベースから暫定インベントリを作成し、テンプレートからファイルを用意することを提案してください）を読みます。また、スラッグに対応するフォルダーがすでにある場合は、その SPEC.md と decisions.md をすべて読みます（アップサートは何も知らない状態から始めません）。アイデアの領域に関係するアーキテクチャおよびドメインのドキュメントは、プロジェクトの実際のエンティティとロールに基づいて機能の完了確認を行える範囲に限って確認してください。詳細なエンジニアリング調査は Engineering 側の担当であり、このスキルの範囲ではありません。

内部の evidence-grounding 機能を利用して、順序付きの各パスと準備状況の事前確認を行います：インベントリ → エビデンス → 草案 → 削減 → 準備状況。その結果（READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN | NEEDS-REPLAN）は作成時のゲートであり、承認ではありません。Product 側半分を承認できるのは review-spec のみです。

リサーチゲート（必須、フェイルクローズ）

Product の部分を出力する前に、エビデンスパス（順序付きパスのステップ 2）でリサーチゲートを実行します。

• ドメインを調査する — 能力のドメインに関する外部取得済みの情報源を少なくとも 2 つ（fetch／WebFetch／ブラウザー）入手します。この能力がドメインでどのように定義され、解決されるかを調べます。リポジトリのエビデンスだけでは設計の根拠として不十分です。このゲートは、リポジトリがすでに前提としている考え方に基づいて設計してしまう偏りを防ぎます。取得した各情報源は、エビデンス行（URL とアクセス日）になります。
• 定義全体を網羅する — 各行には、その能力が何であり、何ではないか、およびユーザーが何を期待するかを記載します。受け入れられる入力と拒否される入力、境界、セマンティクスを含め、プロジェクトの現状の捉え方だけにとどめないでください。
• 明示された期待をすべて分解する — Product の部分を確定する前に、ユーザーが明示する各期待を、その期待が暗に含むケースの分解へと展開します。これには、有効値と無効値および制限、インタラクションの状態、縮退モード、バックエンドでの検証／フィルタリング／解析、代替となるユーザー経路が含まれます。典型的なケースは「電話番号入力」です。これは単なるフィールドではなく、接頭辞／接尾辞、長さ、テキスト以外の入力の拒否、フォーカス、JavaScript の有無による動作、バックエンドでのフィルタリング／検証／解析から成るケースベクトル全体です。プロダクトオーナーの一言では、こうした要素が隠れてしまいます。
• フェイルクローズにする — オフラインの場合、または取得した情報では重要な疑問に答えられない場合は、担当者名と次に取得すべき情報源を明記して NEEDS-EVIDENCE を返します。推測や、出典の捏造は決してしません。
• 実装前にリサーチする — テストで検証するプラットフォームのセマンティクスは、テストを作成する前に、権威あるドキュメントで確認します（これは verification-contract のテスト不変性契約における予防側です）。

段階的な読み込み — Product の詳細に進む前にステータスを解決する

参照の許可リストは、以下にリンクされたパスのみです。ほかの references/ パスを決して作り出したり、読み込んだりしないでください。DEFER 列の名前だけの項目は、リンク先と同じディレクトリにあります。

未完了のアイデア聞き取りに対する厳格な停止条件： references/INTERVIEW.md のみを正確に読み込み、ほかの参照は読み込みません。次の質問を 1 つだけ尋ね、NEEDS_INPUT を返してターンを終了します。すべての必須聞き取り項目が解決するまで、WRITE_AND_UPSERT.md の読み込みは禁止です。その後の完了行と書き込みは、このリソースに従います。

現在の条件	今すぐ読み込む	今は保留／スキップ
既存のスラッグのみで、指示なし	インタラクションルールに従って聞き取りを行い、ステータスを報告して停止	WRITE_AND_UPSERT.md、UPSERT_EXAMPLE.md、REPAIR.md、PORTABILITY.md
新しいアイデアで、未解決の必須聞き取り項目がある	聞き取りのみ。次の質問を 1 つだけ正確に尋ねて停止	WRITE_AND_UPSERT.md、UPSERT_EXAMPLE.md、REPAIR.md、PORTABILITY.md
新しいアイデアで、すべての必須聞き取り項目が解決済み	聞き取り、続いて完了、書き込み、アップサート	形式が曖昧でない限り UPSERT_EXAMPLE.md、REPAIR.md、PORTABILITY.md
既存のスラッグと指示がある	聞き取り、続いて完了／書き込み／アップサート	形式が曖昧でない限りアップサートの例、REPAIR.md、PORTABILITY.md
既存のスラッグの progress.md に SPEC-REVIEW-FAIL または NEEDS-DESIGN がある	聞き取り、続いてレビューの修復	UPSERT_EXAMPLE.md、PORTABILITY.md
名前が挙げられたプラットフォームのプリミティブが存在しない	上記で該当する行と移植性	関係のない行のみ

聞き取り項目が未解決の間は、書き込み／アップサートを読み込まないでください。現在のタスクで使われていないというだけで、サポートされているプリミティブが存在しないことにはなりません。

すべてのリソースは、このファイルから 1 ホップ先にあります。完了行、ロールマトリクス、期待事項の数、固定ステータスブロック、Spec-lint は規範要件です。必須リソースが欠けている場合、または必須項目が未解決の場合は NEEDS_INPUT を返します。決して推測しないでください。

ガードレール

• レビュー権限はありません。 このスキルは Product 側を作成・修復しますが、承認はしません。## Design status: designed も、準備完了を示す READY-FOR-REVIEW の行もレビュー判定ではありません。レビュー判定は、これらのバイト列を書き込んでいないコンテキストで review-spec が行います。PreExecutionReviewReceipt を書き込んだり「同期」したりしてはいけません。レビュー担当者が自ら保存します。
• 書き込むたびにリビジョンを更新します。 Product 側を書き込むたびに、新しい artifactRevisionId が必要です。以前に公開されたバイト列への復元も対象で、終了時の引き継ぎにもこの ID を含めます。更新を怠ると、古い PASS が再び有効になります。
• ドキュメントのみです。コードやブランチは対象外です（ブランチは execute-phase の担当です）。エンジニアリングの内容（アーキテクチャ、設計、フェーズ、テストなど）も対象外です。これらは plan-feature の Engineering 側で扱います。答えが明白に思えても、先回りして記入してはいけません。
• Capability の完了確認行が空欄、インベントリのサブシステムをスキップ、ロールマトリクスが未完成、または Expectation の確認行が未解決の状態で、## Design status: designed を記載してはいけません。行をスキップすると、このスキルの目的そのものが暗黙のうちに損なわれます。
• Expectation の確認で列挙するのはドメインの慣例であり、新たなスコープではありません。各期待事項はスコープ内／スコープ外／延期のいずれかに振り分けるだけです。ユーザーが確認した範囲を超えて、機能の範囲を暗黙のうちに広げてはいけません。
• 市場調査や競合調査は行いません。上記の必須リサーチゲートが、このスキルで唯一許可される外部調査です。グローバルなスキル／MCP の検出調査（product-audit の担当）も行いません。--update フラグも使用しません。upsert はオプトインではなく、常にデフォルトの動作です。
• 独立した DESIGN.md を作成してはいけません。SPEC は常に 1 つ、半分ずつの 2 部構成です。
• 構成のティア。 このスキルは計画クラス（判断を伴う作業）です。最も高性能なモデル／最高の推論 effort で実行してください。薄い issue に対して plan-feature-from-issue がこのスキルをターン内で合成することは、このスキルと同等以上のティア（≥）で実行する場合に限り許可されます。それ以外の場合は、能力不足のまま進めず、run /design-feature <slug> を実行するよう引き継ぐ必要があります。
• その他については、プロジェクトのワークフロー規約（docs-language）に従います。

正規化されたリポジトリ状態

docs/workflow/REPOSITORY_STATE.md から凍結された事実と決定を取り込みます。事実が記載されていない場合は調査してもかまいません。矛盾があれば、矛盾の解決担当者に引き継ぎます。ドキュメントや推論は、実装の証拠にはなりません。

アーキテクチャ上の不変条件

Capability を定義する前に、ドキュメントマップで指定された任意のプロジェクト不変条件ドキュメント（通常は docs/architecture/ARCHITECTURAL_INVARIANTS.md）を探します。存在しない場合は、SPEC に n/a: no project invariants declared と記録して続行します。該当する各ルールについて、その ID とリポジトリ上の根拠を示し、提案を preserves、violates、introduces、changes のいずれかに分類します。Capability の完了確認に進めるのは preserves の場合だけです。違反、新たなルール、ルールの変更がある場合は、プロジェクトで定められた権限者による明示的なアーキテクチャ判断が行われるまで設計を中止します。SPEC、実装計画、テストによって、後から承認を正当化してはいけません。NRS が存在する場合は、まずその凍結された事実を取り込みます。リポジトリが引き続き権威ある情報源であり、矛盾があれば解決担当者に引き継ぎます。

移植性

対応プラットフォームでは 移植性 を読まないでください。名前付きのインタラクションプリミティブが存在しないと検出した場合に限り、読みます。インタビュー、完了確認、upsert、固定出力の各契約は変わりません。

他のスキルとの関係

• review-spec はこのスキルから引き継ぐゲートです。設計済みの半分は個別にレビューされ、その後で初めて plan-feature が利用できます。plan-feature は最新のレビュー記録がなければ処理を中止するため、引き継ぎ先を plan-feature ではなくここにすることで、パイプラインの整合性が保たれます。
• 機能のプロダクト側が designed とマークされていない場合、または最新のレビューがない場合、plan-feature は（回避フラグなしで）ここにリダイレクトします。review-spec の審査に通ると、plan-feature がエンジニアリング側を埋め、成果物のひな型を作成します。
• plan-feature-from-issue は、情報が少ないイシューに対して、このスキルを同じターン内で組み込む場合（≥ tier の場合のみ。ガードレール を参照）と、直接引き継ぐ場合があります。このスキルはプロダクト側と review-spec で処理を終え、同じターン内にエンジニアリング計画へ進むことはなくなりました。
• evidence-grounding は、このスキルが利用するパスと準備状況の用語を管理します。また、レビュー判定を出すことはありません。
• triage-issue の promote-to-feature 判定は plan-feature に引き継がれます。昇格したイシューがまだ設計されていない場合、plan-feature はここにリダイレクトします。
• execute-phase はこのスキルを呼び出しません。すでに計画済みの SPEC のエンジニアリング側を実行するだけです。

完了条件

• SPEC のプロダクト側が記入され、すべての Capability クロージャ行が解決済み（対象範囲が記入済み、または明示的に n/a）であること。

• ## Design status が結果を正確に反映していること（クロージャが完了した場合にのみ designed）。

• ロードマップの行が存在し（まったく新しい機能の場合は idea で作成）、そのステータスが結果に一致していること（designed の場合は defined、NEEDS_INPUT の場合は idea のまま）。

• 準備状況の事前チェックが実行され、READY-FOR-REVIEW が返されているか、ターンがその正確なブロック結果で終了していること。

• 引き継ぎに現在の artifactRevisionId が記載されていること。

• 最後の → Next: ブロックが出力されていること：

  → Next: /review-spec <slug> — product half designed and readiness-clean; it needs an
      independent review before any engineering planning
    · more to design → re-run /design-feature <slug> "<instruction>" (upsert, destroys nothing,
      rotates the artifact revision)
    · recurring gap in this project's capability closure → /product-audit (a systemic pattern,
      not a one-off design fix)
  

  代わりに NEEDS_INPUT で終了する場合：

  → Next: answer the pending question, then re-run /design-feature <slug>
    · unsure how to scope it → propose the smallest version and confirm
  

  準備状況の結果が NEEDS-EVIDENCE または NEEDS-REPLAN の場合：

  → Next: /design-feature <slug> "<the missing evidence>" — readiness returned
      NEEDS-EVIDENCE for <rows>; do not invoke /review-spec on an artifact that is
      not readiness-clean
    · the gap is engineering, not product → it belongs to plan-feature's evidence, not here