spec-writing

仕様書の作成

概要

仕様書では、ソフトウェアが何をすべきかを定義し、どのように実装するかは決して定義しません。このスキルでは、Jobs to Be Done（JTBD）手法を用いて要件を適切な範囲に分割し、自律的な実装を促すテスト可能な仕様書ファイルを作成します。各仕様書には、実装の詳細を含まないGiven／When／Then形式の受け入れ基準を記述します。

これは厳格なスキルです。 すべてのフェーズ、ゲート、形式に関するルールに正確に従う必要があります。

最重要ルール

[HARD-GATE:SPEC] 仕様書に実装の詳細を含めてはいけません。

禁止事項	許可される内容
コードブロックやスニペット	振る舞いの説明
変数名や関数シグネチャ	観察可能な結果
技術の選択（「Reactを使う」「PostgreSQLを使う」）	機能要件（「ブラウザーで表示する」「データを永続化する」）
アルゴリズムの提案（「K-meansクラスタリングを使う」）	成功基準（「主要な色を5〜10色抽出する」）
アーキテクチャパターン（「MVCを使う」）	ユーザー向けの振る舞い
ライブラリへの言及（「検証にZodを使う」）	検証要件（「不正な形式の入力を拒否する」）

理由： 実装の詳細を含まない仕様書により、柔軟性が保たれます。実装エージェントは、コードベース、技術、制約に応じて最適な方法を選択でき、仕様書を更新せずに方針を変更できます。

フェーズ1：Jobs to Be Done（JTBD）

次の形式で、ユーザーまたはシステムのジョブを特定します。

When [situation], I want to [motivation], so I can [expected outcome].

例：

• 「画像をアップロードしたとき、デザインに使えるよう、その画像からカラーパレットを抽出したい。」
• 「APIリクエストを受け取ったとき、処理前に不正な形式のデータを拒否できるよう、ペイロードを検証したい。」

次の質問を通じてジョブを洗い出します。

1. ユーザー／アクターは誰ですか？
2. どのような状況でこのニーズが生じますか？
3. どのような結果を求めていますか？
4. これを達成できない場合、何が起こりますか？

JTBDの特定後は停止し、トピックに分割する前に、すべてのジョブをユーザーに提示して確認を得ます。

フェーズ2：関心のあるトピック

各ジョブを個別のトピックに分割します。「『そして』を使わずに一文で表せるか」テストを適用します。

テスト	結果	対応
「この仕様書では色の抽出を扱います。」	PASS	単一トピック — 仕様書ファイルを1つ作成
「この仕様書では色の抽出とパレットの描画を扱います。」	FAIL	2つのトピック — 仕様書ファイルを2つ作成
「この仕様書ではユーザー認証とセッション管理を扱います。」	FAIL	2つの仕様書に分割
「この仕様書では登録フォームの入力検証を扱います。」	PASS	単一トピック — 仕様書ファイルを1つ作成

各トピックにつき、仕様書ファイルを1つ作成します。

トピックの分割後は停止し、仕様書を作成する前に、仕様書ファイルの一覧を確認します。

フェーズ3：仕様書ファイルの作成

ファイル名の規則： <int>-<descriptive-name>.md

specs/
├── 01-color-extraction.md
├── 02-palette-rendering.md
├── 03-export-formats.md
└── 04-color-accessibility.md

仕様書ファイルのテンプレート

# [Topic Name]

## Job to Be Done
When [situation], I want to [motivation], so I can [expected outcome].

## Acceptance Criteria

### [Criterion 1 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]
- And [additional observable outcome]

### [Criterion 2 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]

## Edge Cases
- [Describe boundary condition and expected behavior]
- [Describe error condition and expected behavior]

## Data Contracts
- Input: [Describe shape, constraints, valid ranges]
- Output: [Describe shape, guarantees, invariants]

## Non-Functional Requirements
- Performance: [measurable target, e.g., "responds within 200ms for 95th percentile"]
- Accessibility: [specific standard, e.g., "WCAG 2.1 AA"]
- Security: [specific requirement, e.g., "input sanitized against XSS"]

受け入れ基準の品質ルール

ルール	良い例	悪い例
観察可能な振る舞いの結果	「あらゆる画像から主要な色を5〜10色抽出する」	「k=8でK-meansクラスタリングを使う」
テスト可能	「色データはセッションをまたいで保持される」	「PostgreSQLのJSONBカラムに保存する」
具体的で測定可能	「パレットの変更が500ms以内に表示される」	「リアルタイム更新にWebSocketを使う」
独立している（単独で成立する）	「画像の読み込み時にパレットが描画される」	「ReactのuseEffectフックで実装する」
実装の詳細を含まない	「保存されたデータからパスワードを復元できない」	「ソルトラウンドを12回に設定してbcryptを使う」

仕様書の作成後は停止し、フェーズ4に進む前に監査チェックリストを実行します。

仕様監査チェックリスト

#	チェック項目	合格基準
1	実装の詳細がない	コード、関数名、技術選択が一切ない
2	「and」を使わない一文テスト	各仕様が扱うトピックは正確に1つ
3	すべての基準がGiven/When/Then形式	自由形式の基準がない
4	すべての基準がテスト可能	それぞれテストで検証できる
5	エッジケースが記載されている	各仕様に少なくとも2つある
6	データコントラクトが定義されている	入力と出力の形状が指定されている
7	命名に一貫性がある	<int>-<descriptive-name>.md 形式

フェーズ4：ストーリーマップの構成

リリース計画のため、仕様をストーリーマップにまとめます。

CAPABILITY 1    CAPABILITY 2    CAPABILITY 3    CAPABILITY 4
─────────────   ─────────────   ─────────────   ─────────────
basic upload    auto-extract    manual arrange  export PNG
bulk upload     palette gen     templates       export SVG
drag-drop       color names     grid layout     share link
                accessibility   animation       collaborate

• 横方向の行 = リリース候補
• 最上段 = 最小限の実用リリース
• 各行で全体にわたる機能を追加します

SLC リリース基準

横方向のスライスごとに、以下を評価します。

基準	質問	標準
シンプル	範囲を絞ってすばやくリリースできますか？	数週間。数か月ではありません
魅力的	実際に使いたいと思えるものですか？	単に機能するだけでなく、使っていて楽しい
完全	1つの作業を最後まで完遂できますか？	エンドツーエンド。中途半端ではありません

[HARD-GATE] リリースは3つすべてを満たす必要があります。「シンプルだが未完成」ではリリースできません。「完全だが魅力的でない」場合もリリースできません。

ストーリーマップを作成したら停止し、最終確定の前にリリースのスライス方法についてユーザーの確認を得てください。

フェーズ5：仕様監査モード

既存の仕様を監査する場合（新規作成ではなく）：

1. specs/ 内の仕様ファイルをすべて読みます
2. 各仕様が大原則（コードや実装の詳細を含めない）に沿っているか確認します
3. 「and」を使わない一文テストを確認します
4. 命名規則の一貫性を確認します
5. すべての受け入れ基準がGiven/When/Then形式であることを確認します
6. 違反を指摘し、可能であれば自動修正します

大規模な仕様セットでは、Agent ツール（subagent_type="Explore"）を使って、仕様ファイルごとに1つ、最大100個のサブエージェントを並行して稼働させます。

アンチパターン／よくある間違い

間違い	それが誤りである理由	代わりにすべきこと
仕様にコードスニペットを含める	実装方法を固定してしまう	仕組みではなく振る舞いを記述する
技術名を指定する（「Redisを使う」など）	より良い代替案を妨げる	機能を記述する（「結果をキャッシュする」など）
「and」でトピックを結合する	仕様の範囲が広すぎて、実装やテストが難しくなる	別々の仕様ファイルに分割する
あいまいな受け入れ基準（「適切に動作する」など）	テストを作成できない	測定可能な具体的な結果を示す
エッジケースを記載しない	境界条件でバグが発生する	各仕様に少なくとも2つのエッジケースを記載する
データコントラクトを省略する	入出力があいまいになる	常に形状と制約を定義する
コードを書いた後に仕様を作成する	仕様が実装を導くのではなく、実装を正当化してしまう	実装の前に仕様を作成する
UIレイアウトを説明する受け入れ基準	実装の詳細である	ユーザーが達成できることを記述する

正当化を防ぐためのガード

• [HARD-GATE] 実装の詳細を一切含めないでください。コード、技術名、アーキテクチャは含めません
• [HARD-GATE] 「and」を使わない一文テストを省略しないでください。複合したトピックはすべて分割してください
• [HARD-GATE] Given/When/Then形式でない受け入れ基準を認めないでください
• [HARD-GATE] 仕様を最終確定する前に、監査チェックリストを省略しないでください
• エッジケースを省略しないでください。すべての仕様に少なくとも2つ必要です
• データコントラクトを省略しないでください。すべての仕様に入出力の形状が必要です
• 実装の後に仕様を書かないでください。仕様がコードを導くのであり、その逆ではありません

連携ポイント

スキル	関係
autonomous-loop	計画モードでは仕様を読み込み、実装の不足箇所を特定します
acceptance-testing	テストは仕様の受け入れ基準から直接導き出されます
reverse-engineering-specs	既存コードから仕様を生成します（ブラウンフィールド）
prd-generation	PRD で概要レベルの要件を示し、仕様で詳細を定めます
planning	計画では、タスク定義のために仕様の受け入れ基準を参照します
test-driven-development	レッドフェーズでは、仕様の受け入れ基準に合致するテストを記述します
writing-skills	この手法を使ってスキルを仕様化できます

具体例：仕様ファイルの全体像

# Image Color Extraction

## Job to Be Done
When I upload an image to the design tool, I want to automatically extract
its dominant colors, so I can use those colors in my design palette.

## Acceptance Criteria

### Dominant Color Extraction
- Given an uploaded image in PNG, JPG, or WebP format
- When the extraction process completes
- Then 5-10 dominant colors are returned as hex values
- And colors are ordered by prominence (most dominant first)

### Transparent Image Handling
- Given an uploaded image with transparent regions
- When the extraction process completes
- Then transparent regions are excluded from color analysis
- And at least 3 dominant colors are still returned

### Processing Feedback
- Given an image upload has started
- When extraction is in progress
- Then the user sees a progress indicator
- And extraction completes within 3 seconds for images up to 10MB

## Edge Cases
- Single-color image: returns 1 color (not an error)
- Very large image (>50MB): returns an error with size limit message
- Corrupted image file: returns an error with clear message, no crash
- Animated GIF: extracts colors from the first frame only

## Data Contracts
- Input: Image file (PNG, JPG, WebP), max 50MB
- Output: Array of 1-10 hex color strings, ordered by prominence
- Error output: Error object with code and human-readable message

## Non-Functional Requirements
- Performance: <3s for images up to 10MB, <10s for images up to 50MB
- Accessibility: Color values include WCAG contrast ratio against white/black

検証ゲート

仕様が完成したと宣言する前に、次の項目を確認してください。

1. カーディナルルールを確認します — どの仕様にも実装の詳細が一切含まれていないこと
2. すべての仕様が「『そして』を使わずに一文にする」テストに合格することを確認します
3. すべての受け入れ基準が Given/When/Then 形式を使用していることを確認します
4. すべての仕様にエッジケースとデータコントラクトがあることを確認します
5. ストーリーマップに、少なくとも1つの完全な SLC リリーススライスがあることを確認します
6. ユーザーが仕様一式を承認したことを確認します

スキルの種類

厳格 — 実装の詳細を含めないルール、JTBD 構成、Given/When/Then 形式、監査チェックリストには、必ず厳密に従う必要があります。要素を省略したり、変更したりすることはできません。