specify

Name: specify
Author: ariadoss

github.com/ariadoss開発1262 回インストール3 日前に更新

リポジトリ

specify について

specify は、機能の説明から番号付き Git ブランチと構造化された仕様書を作成するワークフロースキルです。BuildBetter のコンテキスト収集や品質検証も扱い、計画に進める状態かを報告します。

主な機能

01機能ブランチ名の短縮
02ブランチと仕様ディレクトリの番号確認
03利用可能な場合の BuildBetter コンテキスト収集
04機能仕様書の作成と検証
05計画準備状況の報告

活用シーン

01記述された要望から機能開発を開始
02既存のブランチ番号との重複回避
03計画前の仕様書レビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/ariadoss/superskills --skill specify

インストール後、Claude Code で/specifyを入力して読み込まれたか確認します。

詳細

テンプレート： 以下で参照しているテンプレートファイル（spec-template.md、plan-template.md など）が必要な場合は、BB-Skills リポジトリの templates/ から入手できます。ローカルにインストールされている場合は、~/.bb-skills/templates/ またはプロジェクトの templates/ ディレクトリを確認してください。

ユーザー入力

$ARGUMENTS

作業を進める前に、ユーザー入力を必ず検討してください（空でない場合）。

概要

このスキルの呼び出し時にユーザーが入力したテキストが、機能の説明です。この会話では常にその説明を確認できるものとします。空のコマンドが入力された場合を除き、ユーザーに繰り返し説明するよう求めないでください。

その機能の説明に基づいて、次の手順を実行してください。

簡潔なブランチの短い名前を生成する（2～4語）：
- 機能の説明を分析し、最も重要なキーワードを抽出します
- 機能の要点を表す2～4語の短い名前を作成します
- 可能な場合は動詞＋名詞の形式を使います（例：「add-user-auth」、「fix-payment-bug」）
- 技術用語や頭字語（OAuth2、API、JWT など）はそのまま使用します
- 簡潔でありながら、機能の概要がひと目で分かる名前にします
- 例：
  - 「ユーザー認証を追加したい」→「user-auth」
  - 「API に OAuth2 統合を実装する」→「oauth2-api-integration」
  - 「分析用のダッシュボードを作成する」→「analytics-dashboard」
  - 「決済処理のタイムアウトバグを修正する」→「fix-payment-timeout」
新しいブランチを作成する前に既存のブランチを確認する：

a. まず、最新の情報を取得するため、すべてのリモートブランチをフェッチします。
```
git fetch --all --prune
```
b. 短い名前に対応するすべてのソースから、最も大きい機能番号を探します：
- リモートブランチ：git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'
- ローカルブランチ：git branch | grep -E '^[* ]*[0-9]+-<short-name>$'
- 仕様ディレクトリ：specs/[0-9]+-<short-name> に一致するディレクトリを確認します
c. 次に使用可能な番号を決定します：
- 3つすべてのソースから番号を抽出します
- 最も大きい番号を N とします
- 新しいブランチ番号には N+1 を使用します
d. 機能ブランチと仕様ディレクトリ構成を作成します：
- N+1-<short-name> という名前の新しいブランチを作成し、チェックアウトします
- 仕様ディレクトリを作成します：specs/N+1-<short-name>/
- 仕様ファイルを初期化します：specs/N+1-<short-name>/spec.md
重要：
- 最も大きい番号を特定するために、3つすべてのソース（リモートブランチ、ローカルブランチ、仕様ディレクトリ）を確認します
- 短い名前が完全に一致するパターンのブランチ／ディレクトリのみを対象にします
- この短い名前に一致する既存のブランチ／ディレクトリがない場合は、番号1から始めます
- 機能ごとに作成するブランチは1つだけです
BuildBetter のコンテキストを収集する（ベストエフォート）：
- 仕様ファイルのパスから FEATURE_DIR を導き出します。
- BuildBetter のコンテキスト収集が利用可能な場合は、機能の説明を使用して顧客のエビデンスを収集します。
- 収集ツールは次のファイルを作成します：
  - FEATURE_DIR/buildbetter-context.json
  - FEATURE_DIR/buildbetter-context.md
  - FEATURE_DIR/user-stories.md
- 収集ツールのステータスに応じて処理します：
  - ok：BuildBetter のエビデンスをそのまま使用します。
  - partial：利用可能なエビデンスを使用し、警告を保持します。
  - skipped：BuildBetter のデータなしで続行し、仕様の前提条件に注記を追加します。
  - error：BuildBetter のデータなしで続行し、明示的に警告したうえで、生成された成果物があれば保持します。
仕様テンプレートと BuildBetter の成果物（存在する場合）を読み込み、必要なセクションとエビデンスのコンテキストを把握します。
次の実行フローに従います。
1. Input からユーザーの説明を解析します空の場合：ERROR "機能の説明が指定されていません"
2. 説明と BuildBetter のエビデンスから主要な概念を抽出しますアクター、アクション、データ、制約を特定します
  - 利用可能な場合は、buildbetter-context.md から顧客の正確な引用を取得します
  - 利用可能な場合は、user-stories.md から既存のストーリーを取得します
  - 利用可能な場合は、各要件／ストーリーを1つ以上のエビデンス ID（BB-EXTRACTION-*）に対応付けます
3. 不明確な点について：
  - コンテキストと業界標準に基づいて、根拠のある推測をします
  - 次の場合に限り、[NEEDS CLARIFICATION: specific question] を付けます：
    - 選択によって機能の範囲またはユーザーエクスペリエンスが大きく変わる
    - 異なる影響をもたらす妥当な解釈が複数ある
    - 妥当なデフォルトが存在しない
  - 上限：[NEEDS CLARIFICATION] マーカーは最大3つまで
  - 影響度の高い順に確認事項を優先します：範囲 > セキュリティ／プライバシー > ユーザーエクスペリエンス > 技術的な詳細
4. User Scenarios & Testing セクションを記入します明確なユーザーフローがない場合：ERROR "ユーザーシナリオを特定できません"
  - エビデンスで裏付けられたユーザージャーニーを優先します
5. Functional Requirements を生成します各要件はテスト可能である必要があります指定されていない詳細には妥当なデフォルトを使用し、Assumptions セクションに前提を記載します
6. Success Criteria を定義します測定可能で、テクノロジーに依存しない成果を作成します定量的な指標（時間、パフォーマンス、量）と定性的な指標（ユーザー満足度、タスク完了）の両方を含めます各基準は、実装の詳細を参照せずに検証可能である必要があります
7. 主要なエンティティを特定します（データを扱う場合）
8. エビデンスのトレーサビリティ注釈を追加します：
  - 各主要ユーザーストーリーに Evidence References を含めます
  - 関連する場合は、要件にエビデンス ID を含めます
  - BuildBetter が利用できない場合は、エビデンスに裏付けられていない前提であることを明示します
9. 次を返します：SUCCESS（仕様の計画準備完了）
テンプレートの構成を使用して、仕様を仕様ファイルに書き込みます。セクションの順序と見出しを維持しながら、プレースホルダーを機能の説明と BuildBetter のコンテキストから導き出した具体的な内容に置き換えます。
仕様の品質検証：初期仕様を書き込んだ後、品質基準に照らして検証します。

a. 仕様品質チェックリストの作成：次の検証項目を含むチェックリストテンプレートの構成を使用して、FEATURE_DIR/checklists/requirements.md にチェックリストファイルを生成します。
```
# 仕様品質チェックリスト：[機能名]

**目的**：計画に進む前に、仕様の完全性と品質を検証します
**作成日**：[日付]
**機能**：[spec.md へのリンク]

## コンテンツの品質

- [ ] 実装の詳細（言語、フレームワーク、API）が含まれていない
- [ ] ユーザーの価値とビジネスニーズに焦点を当てている
- [ ] 技術的な知識を持たない関係者向けに書かれている
- [ ] 必須セクションがすべて記入されている

## 要件の完全性

- [ ] [NEEDS CLARIFICATION] マーカーが残っていない
- [ ] 要件がテスト可能で、曖昧さがない
- [ ] 成功基準が測定可能である
- [ ] 成功基準がテクノロジーに依存しない（実装の詳細が含まれていない）
- [ ] すべての受け入れシナリオが定義されている
- [ ] エッジケースが特定されている
- [ ] スコープが明確に定められている
- [ ] 依存関係と前提が特定されている

## 機能の準備状況

- [ ] すべての機能要件に明確な受け入れ基準がある
- [ ] ユーザーシナリオが主要なフローを網羅している
- [ ] 機能が Success Criteria で定義された測定可能な成果を満たしている
- [ ] 仕様に実装の詳細が紛れ込んでいない

## 備考

- 未完了の項目がある場合、bb-clarify または bb-plan スキルを使用する前に仕様を更新する必要があります
```
b. 検証チェックの実施：各チェックリスト項目に照らして仕様を確認します。
- 各項目が合格か不合格かを判定します
- 見つかった具体的な問題を記録します（関連する仕様のセクションを引用してください）
c. 検証結果への対応：
- すべての項目が合格の場合：チェックリストを完了済みにし、ステップ 8 に進みます
- 項目が不合格の場合（[NEEDS CLARIFICATION] を除く）：
  1. 不合格の項目と具体的な問題を列挙します
  2. 各問題に対応するよう仕様を更新します
  3. すべての項目が合格するまで検証を再実行します（最大 3 回）
  4. 3 回の反復後も不合格の場合は、チェックリストの注記に残る問題を記録し、ユーザーに警告します
- [NEEDS CLARIFICATION] マーカーが残っている場合：
  1. 仕様からすべての [NEEDS CLARIFICATION: ...] マーカーを抽出します
  2. 上限の確認：マーカーが 3 個を超える場合、最も重要な 3 個（スコープ／セキュリティ／UX への影響に基づく）のみを残し、残りについては妥当な推測を行います
  3. 明確化が必要な各項目について（最大 3 件）、次の形式でユーザーに選択肢を提示します。
```
## 質問 [N]：[トピック]

**背景**：[関連する仕様セクションを引用]

**確認事項**：[NEEDS CLARIFICATION マーカーに記載された具体的な質問]

**推奨される回答**：

| 選択肢 | 回答 | 影響 |
|--------|------|------|
| A      | [最初の推奨回答] | [機能に対する意味] |
| B      | [2 番目の推奨回答] | [機能に対する意味] |
| C      | [3 番目の推奨回答] | [機能に対する意味] |
| カスタム | 独自の回答を入力してください | [カスタム入力の方法を説明] |

**選択内容**： _[ユーザーの回答を待ちます]_
```
  4. 重要 — テーブルの書式：Markdown テーブルが正しく書式設定されていることを確認します。
    - パイプの位置を揃え、一貫したスペースを使用します
    - 各セルの内容の前後にスペースを入れます：| 内容 |。|内容| ではありません
    - ヘッダー区切りには 3 個以上のハイフンを使用します：|--------|
    - Markdown プレビューでテーブルが正しく表示されることを確認します
  5. 質問には順番に番号を付けます（Q1、Q2、Q3 — 最大 3 件）
  6. すべての質問をまとめて提示してから、回答を待ちます
  7. すべての質問への選択を含む回答をユーザーが返すまで待ちます（例：「Q1: A、Q2: カスタム — [詳細]、Q3: B」）
  8. 選択または入力された回答で各 [NEEDS CLARIFICATION] マーカーを置き換え、仕様を更新します
  9. すべての明確化が解決した後、検証を再実行します
d. チェックリストの更新：検証を反復するたびに、現在の合否状況でチェックリストファイルを更新します
ブランチ名、仕様ファイルのパス、BuildBetter のアーティファクトパス、チェックリストの結果、次のフェーズ（bb-clarify または bb-plan スキルを使用）に進む準備ができているかを報告します。

一般的なガイドライン

クイックガイドライン

ユーザーが何を必要としているか、そしてなぜ必要としているかに焦点を当てます。
実装方法については記述しません（技術スタック、API、コード構造を含めないでください）。
開発者ではなく、ビジネス関係者向けに記述します。
仕様に埋め込まれたチェックリストは作成しないでください。チェックリストは別のコマンドで作成します。

セクションの要件

必須セクション：すべての機能で記入する必要があります
任意セクション：その機能に関連する場合のみ含めます
セクションが該当しない場合は、完全に削除します（「該当なし」のまま残さないでください）

AI 生成の場合

ユーザープロンプトからこの仕様を作成する場合：

根拠に基づいて推測する：文脈、業界標準、一般的なパターンを活用して、不足している情報を補います
前提を記録する：妥当なデフォルト値を Assumptions セクションに記録します
確認を最小限にする：[NEEDS CLARIFICATION] マーカーは最大 3 個とし、次の条件に当てはまる重大な判断にのみ使用します。
- 機能の範囲やユーザーエクスペリエンスに大きな影響を与える
- 異なる影響をもたらす、複数の妥当な解釈がある
- 妥当なデフォルト値がない
確認の優先順位：範囲 > セキュリティ／プライバシー > ユーザーエクスペリエンス > 技術的な詳細
テスターの視点で考える：曖昧な要件はすべて、「テスト可能で曖昧さがないこと」のチェック項目に合格しないものとして扱います
確認が必要になりやすい一般的な項目（妥当なデフォルト値がない場合に限る）：
- 機能の範囲と境界（特定のユースケースを含めるか除外するか）
- ユーザーの種類と権限（複数の解釈が矛盾する可能性がある場合）
- セキュリティ／コンプライアンス要件（法務または財務に重大な影響がある場合）

妥当なデフォルト値の例（これらについては質問しないでください）：

データ保持：その分野の業界標準に基づく慣行
パフォーマンス目標：指定がなければ、一般的なウェブ／モバイルアプリの期待値
エラー処理：適切なフォールバックを含む、ユーザーにわかりやすいメッセージ
認証方式：ウェブアプリでは標準的なセッションベースまたは OAuth2
統合パターン：プロジェクトに適したパターンを使用する（ウェブサービスには REST／GraphQL、ライブラリには関数呼び出し、ツールには CLI 引数など）

成功基準のガイドライン

成功基準は次の条件を満たす必要があります。

測定可能：時間、割合、件数、率などの具体的な指標を含めます
テクノロジーに依存しない：フレームワーク、言語、データベース、ツールについて言及しません
ユーザーを重視する：システム内部ではなく、ユーザーやビジネスの観点から成果を記述します
検証可能：実装の詳細を知らなくてもテスト／検証できます

良い例：

「ユーザーは 3 分以内にチェックアウトを完了できます」
「システムは 10,000 人の同時ユーザーをサポートします」
「検索の 95% が 1 秒以内に結果を返します」
「タスク完了率が 40% 向上します」

悪い例（実装重視）：

「API の応答時間は 200ms 未満です」（技術的すぎます。「ユーザーは結果をすぐに確認できます」とします）
「データベースは 1000 TPS を処理できます」（実装の詳細です。ユーザー向けの指標を使用します）
「React コンポーネントは効率的にレンダリングされます」（フレームワークに依存しています）
「Redis のキャッシュヒット率は 80% を超えます」（特定の技術に依存しています）

Markdown 対応

ログインしてコメント

基本情報

作者: ariadoss
リポジトリ: ariadoss/superskills
カテゴリ: 開発
インストール数: 62
GitHub スター: 12

問題を報告