Spec-Gatekeeper: 仕様駆動開発ワークフロー
このスキルは、ソースコードの記述が spec-gatekeeper によってブロックされた場合、または新機能、サービス、大規模リファクタリングを開始する際に使用します。
仕様駆動開発 (SDD) は、実装前に合意された構造化されたアーキテクチャ契約を要求することで、明確性を確保し、仕様のずれを排除します。
ワークフローステップ
ステップ 1: 4つの質問による開発者インタビューの実施
コードを記述したりファイルをスタブ化したりする前に、開発者に以下の4つの質問を行います(または既存の要件から回答を抽出し、確認を求めます)。
-
スコープとセキュリティ:
- このタスクの核となる目標と、明示的に対象外とするものは何ですか?
- どのアーキテクチャコンポーネントやシステム境界が関与しますか?
- セキュリティ、権限、認証、サンドボックス制約は何ですか?
-
データ契約:
- 正確なスキーマ、APIインターフェース、型、プロトコルの形状は何ですか?
- 精密な入力パラメータと期待される出力ペイロードは何ですか?
-
エッジケースと回復力:
- 主要な障害モード、ネットワーク/IO中断、不正な入力は何ですか?
- どのようなエラーハンドリング、検証、フォールバックメカニズムが必要ですか?
-
受け入れ基準:
- 「完了」を定義する決定論的な検証マトリックスとテストケースは何ですか?
- 各受け入れ基準はどのように検証されますか?
ステップ 2: SPEC.md のドラフト作成
解決されたプロジェクトルート(<repo_root>/SPEC.md)に SPEC.md を作成または更新します。
必須構造
仕様ファイルは以下を満たす必要があります:
- サイズ要件: 少なくとも 300 UTF-8 バイト の実質的な内容。
- 正規のセクション見出し: コードブロック外のレベル1から3のMarkdown見出しで、4つの必須セクションのそれぞれに対応していること:
- スコープとセキュリティ:
Scope、Security、Architecture、Overview、Boundaries、Threat Model、Permissionsを含む見出し。 - データ契約:
Data Contract、Data Contracts、Schema、Schemas、Interface、Interfaces、API、Types、Payload、Protocolを含む見出し。 - エッジケース:
Edge Case、Edge Cases、Error Handling、Failure Mode、Failure Modes、Resilience、Constraints、Fallbacksを含む見出し。 - 受け入れ基準:
Acceptance Criteria、Acceptance Test、Test Matrix、Verification、Testing、Definition of Done、Validationを含む見出し。
- スコープとセキュリティ:
テンプレート
# 仕様書: <機能名またはサービス名>
## 1. スコープとセキュリティ
### 目標とアーキテクチャ境界
- 詳細なスコープの説明...
### セキュリティと脅威モデル
- 権限チェックとセキュリティ境界...
## 2. データ契約
### スキーマとインターフェース
- 型、APIシグネチャ、リクエスト/レスポンス形式...
## 3. エッジケースと回復力
### エラーハンドリングとフォールバック
- 境界条件、入力検証、障害モード...
## 4. 受け入れ基準
### 検証とテストマトリックス
- AT-01: ...
- AT-02: ...
ステップ 3: 開発者の承認と実装
- ドラフト
SPEC.mdを開発者に提示し、レビューと明示的な承認を得ます。 SPEC.mdがコミットされ、有効(300バイト以上で4セクションすべてを含む)になると、spec-gatekeeperフックが自動的に実装ソースファイルの作成を許可します。