feature-spec

feature-spec: 機能追加の仕様作成・改訂

既存プロダクトへ機能を足すときの 仕様書 1 本 を作る単機能スキル。成果物は docs/dev/<対象>/spec.md で、全機能要求に一意 ID（REQ-#）を付ける。この ID は 下流のテスト工程・設計工程・レビュー工程が参照する トレーサビリティ鎖の上流起点 になる。

product-spec との住み分け

	product-spec	feature-spec（本スキル）
対象	新規プロダクトの立ち上げ	既存プロダクトへの機能追加
調査の軸	競合・類似プロダクト調査（市場に何があるか）	既存コード・既存仕様との整合調査（自分たちの中に何があるか）
成果物	軽量ワンページの仕様ドラフト	REQ-# 契約を持つ spec.md
ID 契約	なし	あり（REQ-# / AC-#）

新規プロダクトのコンセプト固めなら /product-spec を使う。本スキルは 「動いているプロダクトがあり、そこへ機能を足す」場面専用で、競合調査の枠を 既存資産との整合調査 に置き換えている。

このスキルがやらないこと

• 実装しない。コードの作成・修正はこのスキルの範囲外。
• 基本設計を書かない。モジュール構成・インターフェース・データフローは /basic-design の領分。仕様は「何を満たすか」まで、設計は「どう実現するか」。
• テスト成果物を作らない・直さない。docs/test/<対象>/ 配下は testing スキル群の担当。 改訂モードでテスト成果物の改善提案を 読む ことはあるが、その提案の削除・更新はしない （testing 側の横断原則が担う）。
• 意味の検証を機械検査に委ねない。曖昧語の排除・記述品質は本スキルの責務（後述）。

このスキルが従う原則

1. 単体動作（graceful degradation）

• 成果物の既定パスは docs/dev/<対象>/spec.md。<対象> は機能を表す kebab-case の 短い名前（英数字・ハイフンへ正規化）。
• プロジェクト側（CLAUDE.md / AGENTS.md 等）に成果物の配置規約があればそちらを優先する。
• 任意入力（あれば精度が上がるが、無くても成立する）:
  • docs/dev/definition-of-done.md（完成の定義。受け入れ条件の粒度合わせに使う）
  • docs/test/<対象>/ 配下のテスト成果物（改訂モードの改善提案の収集元）
  • 任意のレビュードキュメント・ユーザーの直接指示
• 任意入力が無いことを理由に中断しない。無い入力は「無い」と明示して先へ進む。

2. 調査優先 + 決定のみ質問

• 事実はリポジトリ調査で埋める。既存の実装・規約・命名・依存関係は、利用者に訊く前に 自分で調べる。
• 利用者にしか決められない判断だけ を AskUserQuestion（推奨案を先頭）で確認する。 本スキルでは スコープの線引き・要求の取捨選択・優先度・改訂提案の採否 がこれに当たる。
• 流れは 調査 → ドラフト提示 → 承認 → 規約パスへ書き込み。承認前に確定ファイルを書かない。

3. 記述品質は本スキルの責務

ゲート（機械検査）は形式契約しか見ない。曖昧さの排除は書き手の責任 であり、 以下を仕様文から排する:

• 曖昧語: 「適宜」「など」「柔軟に」「必要に応じて」「可能な限り」「基本的に」「等」
• 主語・目的語の省略: 誰が・何に対して・いつ、が読み取れない文
• 検証不能な形容: 「高速に」「使いやすく」「安定して」（→ 数値・条件・観測手段へ開く）
• 定義なしの略号・コードネーム: 初出で正式名称を併記するか平易な表現に開く

各要求は 「この文を読んだ第三者がテストケースを書けるか」 を通過基準にする。 書けないなら分割するか、条件を足す。

4. Progressive disclosure

• 本文は簡潔に保ち、雛形は references/ に置く。
• テンプレ: references/template.md（spec.md の雛形）。
• 参考実例: このリポジトリの docs/dev/shift-left-process/spec.md は本テンプレの先行適用 （dogfooding）であり、実寸の記入例として読める。

REQ-# 契約（下流が依存する形式）

この契約は本スキルの成果物が満たすべき 形式 であり、下流工程の機械検査が検証する。

• 機能要求: ### REQ-01: <名称> の見出し + 箇条書き。番号は 2 桁ゼロ埋め、 一意・連番・欠番なし。1 要求 1 見出しで、複数の要求を 1 見出しに詰めない。
• 受け入れ条件: | ID | 対象 | 条件 | のテーブル。ID は AC-01 形式、 対象列に必ず REQ-# を書く（1 つの AC が複数要求にまたがるなら REQ-09/10 のように併記）。
• 非機能要求: NFR-01 形式。機能要求と ID 空間を分ける。
• ID は下流の鎖の起点: REQ-# → テスト条件 TC-# → テストケース CASE-# → 欠陥 D#。 下流成果物が REQ-# を参照するため、既存 ID の意味変更・削除は下流の参照を壊す。

手順

引数は <対象名>。省略されたら docs/dev/ 配下の既存ディレクトリを一覧して選択を求めるか、 新規なら一言で対象を確認する。

docs/dev/<対象>/spec.md の存在で 作成モード（無い）と 改訂モード（ある）に分岐する。

作成モード

手順 1: 要求を固める（grilling 連携）

grilling スキルを呼び出し、渡された対象名・依頼内容を起点に対話で要求の芯を固める。 呼び出し時の brief には、少なくとも以下のトピックを必ずカバーすることを明記する:

• 解く課題（今どう困っていて、この機能で何が変わるか）
• 対象ユーザー・利用シーン（既存プロダクトの誰が使うか）
• 既存の代替手段（今どう回避しているか。運用回避・手作業も含む）
• 満たすべき条件（何が成立したら「できた」と言えるか = 受け入れ条件の種）
• やらないこと（スコープ外の宣言。ここを詰めないとスコープドリフトの原因になる）

grilling の対話で合意に達するまで次の手順へ進まない。合意内容はメインセッションが 「要求要約」として簡潔にまとめて引き継ぐ（grilling 自体はドキュメントを生成しないため）。

手順 2: 既存資産との整合調査

要求要約をもとに、リポジトリを調査して以下を洗い出す。利用者に訊く前に自分で調べる。

• 重複機能: 同じ課題を既に解いている実装・設定・ドキュメントは無いか。 あるなら「新設ではなく拡張」が正解の可能性を提示する。
• 影響範囲: 変更が波及するモジュール・呼び出し元・設定・公開契約（API・CLI 引数・ ファイル書式）。破壊的変更になる箇所を特定する。
• 既存規約: 命名・配置・エラーハンドリング・ログ・テスト配置の慣習。新機能はこれに従う。
• 既存仕様との矛盾: 既存の仕様書・設計書・README と衝突する要求が無いか。 矛盾があれば 仕様を書く前に 利用者へ提示して解消する。

調査結果は要約して提示する（ファイル一覧の羅列ではなく、判断に効く所見にまとめる）。

手順 3: 仕様の作成

references/template.md の構成でドラフトを作り、承認後に docs/dev/<対象>/spec.md へ書き込む。必須セクションは 目的 / スコープ / 機能要求 / 非機能要求 / 受け入れ条件 / スコープ外 の 6 つ。

• 機能要求は REQ-# 契約に従って付番する。
• 受け入れ条件は各行が REQ-# を参照する。要求に紐づかない AC を作らない。
• 「スコープ外」は空にしない。検討して落としたものを明示的に書く（後の議論の再燃を防ぐ）。
• 原則 3 の記述品質を書き終わりに自分で通す（曖昧語の検索は機械的にできる）。

手順 4: セルフ機械検査

後述の「セルフ機械検査」を実行し、NG があればその場で直してから完了宣言する。

改訂モード

既存の docs/dev/<対象>/spec.md を検出したら改訂モードに入る。

手順 1: 未反映の改善提案を収集

以下の入力源を横断して、まだ仕様へ反映されていない 指摘・提案を集める。 入力源は疎結合で、どれか 1 つでもあれば成立する:

• docs/test/<対象>/ 配下のテスト成果物の「改善提案」セクション （test-analysis.md / test-design.md / test-plan.md 等）
• docs/test/<対象>/test-review-*.md の「未解消の指摘」
• ユーザーの直接指示（この会話で渡された変更要望）
• 任意のレビュードキュメント（パスを渡されたもの）

既に現行 spec.md へ反映済みの提案は候補から外す（二重反映を防ぐ）。

手順 2: 取捨選択

収集した提案を一覧で提示し、AskUserQuestion（推奨案を先頭）で採否を確認する。 提案が多いときは論点ごとに分けて訊く。各提案には「反映すると REQ-# がどう変わるか」 （追加 / 条件の変更 / 削除）を添える。

手順 3: 反映

採用された提案だけを spec.md へ反映する。

• REQ-# は追番。既存の最大番号の次から採番する。
• 既存 ID の意味を変えない。「REQ-03 の内容を別物に差し替える」ような改訂は下流の TC-# の参照先を silently 壊す。内容が別物になるなら 新しい ID を採る。
• 削除は下流破壊。要求を落とすときは利用者へ次を警告した上で行う: 既存のテスト条件がその REQ-# を参照していると 孤児参照 になり、 セルフ機械検査（下流参照の破壊検査）で FAIL する。落とすなら下流成果物側の更新が要る。
• テスト成果物側の改善提案の 削除はしない（testing スキルの責務）。反映したことは 報告で伝え、テスト成果物の掃除は該当 testing スキルの再実行に委ねる。

手順 4: セルフ機械検査

作成モードと同じ（下記）。

セルフ機械検査

終了前に、test-review の決定論スクリプトを spec モードで自分に対して実行する。

<review-check.sh のパス> spec docs/dev/<対象> [docs/test/<対象>]

• 第 2 引数は開発ドキュメントのディレクトリ（docs/dev/<対象>）。
• 第 3 引数のテストドキュメントディレクトリは省略可（省略時は docs/dev/<対象> から docs/test/<対象> を自動導出する）。
• 検査内容: 必須セクションの存在 / REQ-# の一意性・形式・重複欠番 / 受け入れ条件の空欄と REQ-# 紐づけ / 下流参照の破壊検査（既存 test-analysis.md の TC-# が参照する REQ-# を仕様改訂で消していないか = 孤児参照検出）。

スクリプトの探索

次の順で探し、最初に見つかったものを使う:

1. 作業リポジトリ内の skills/testing/test-review/scripts/review-check.sh
2. install 済み testing-skills プラグインの同一パス （~/.claude/plugins/ 配下等。プラグインの配置は環境で変わるため実在確認をしてから使う）

どちらにも無ければ検査をスキップし、その旨を利用者へ明示する（例: 「review-check.sh が見つからないためセルフ機械検査をスキップした。testing-skills を install するか、/test-review <対象> spec で別途ゲートを通してほしい」）。 スクリプトの不在を理由に仕様作成を失敗させない（原則 1: graceful degradation）。

NG が出たとき

NG は形式契約の違反であり事実なので、利用者判定を待たずにその場で直す。 直したら再実行して NG ゼロを確認する。SKIP（突合先の成果物が無い等）は問題ではない。

終了条件

以下を全て満たしたら 「<対象> の仕様は完了」と明言 して閉じる。満たしていない項目が あれば、何が残っているかを列挙して先へ進めない。

1. 作成モードなら grilling で要求合意済み・整合調査済み（手順 1・2）。 改訂モードなら提案の収集と取捨選択が利用者確認済み（手順 1・2）。
2. docs/dev/<対象>/spec.md が規約パスへ書き込み済みで、必須 6 セクションを持つ。
3. 全機能要求に一意な REQ-# が付き、受け入れ条件の各行が REQ-# を参照している。
4. セルフ機械検査が NG ゼロ、またはスクリプト不在によるスキップを利用者へ明示済み。

完了後の次の一手として、以下を 提案するに留める（本スキルは実行しない）:

• 正式ゲート: /test-review <対象> spec
• テスト計画・分析: /test-plan <対象> / /test-analyze <対象>
• 基本設計: /basic-design <対象>

用語

• 要求（requirement）: プロダクトが満たすべきこと。本スキルでは REQ-# で一意識別する。
• 受け入れ条件（acceptance criteria）: 要求が満たされたと判断する条件。AC-#。
• 孤児参照（orphan reference）: 下流成果物が参照している ID が上流から消えた状態。
• トレーサビリティ（traceability）: 要求・テスト条件・ケース・欠陥の間の対応関係。