# Feature Spec

> 既存プロダクトへの機能追加の仕様を対話で固め、既存コード・既存仕様との整合を調査して REQ-# 契約付きの docs/dev/<対象>/spec.md を作成・改訂するスキル。/feature-spec <対象名> で明示的に呼び出されたときのみ使用する。

- **Type:** Skill
- **Install:** `agentstack add skill-yasunori0418-skills-feature-spec`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yasunori0418](https://agentstack.voostack.com/s/yasunori0418)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yasunori0418](https://github.com/yasunori0418)
- **Source:** https://github.com/yasunori0418/skills/tree/main/skills/product/feature-spec

## Install

```sh
agentstack add skill-yasunori0418-skills-feature-spec
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`](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`](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` モードで自分に対して実行する。

```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）: 要求・テスト条件・ケース・欠陥の間の対応関係。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yasunori0418](https://github.com/yasunori0418)
- **Source:** [yasunori0418/skills](https://github.com/yasunori0418/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yasunori0418-skills-feature-spec
- Seller: https://agentstack.voostack.com/s/yasunori0418
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.