specification-first

仕様ファースト

概要

実装の前に仕様を作成します。仕様が信頼できる唯一の情報源です。コードは仕様を満たすために生成されるものであり、その逆ではありません。

基本原則： 動作仕様は、システムが何をするかを定義します。コードはその方法を実装します。仕様がなければ、推測するしかありません。

例外なし。回避策なし。近道なし。

最優先の指針

NO IMPLEMENTATION WITHOUT A SPECIFICATION FIRST

入力、出力、エッジケース、受け入れ基準を定義した仕様を作成していない場合、コードを書くことは認められません。これは任意ではありません。過剰でもありません。AI 生成コードの失敗の最大の原因である、間違ったものを作ることを防ぎます。

使用する場面

必須となる場面：

• 新しい機能やモジュールを開発する
• API エンドポイントを作成する
• データパイプラインを構築する
• 入力と出力が定義されたシステムを構築する
• ユーザーが「X を作って」または「Y を作成して」と言う

例外（人間に確認してください）：

• 設定の変更
• 動作が明確な、1 行だけの不具合修正
• ドキュメントの更新

開始プロトコル

BEFORE writing any implementation code:

1. IDENTIFY: What are the inputs?
2. DEFINE: What are the expected outputs?
3. CONSTRAIN: What are the boundaries and limitations?
4. EDGE: What happens at the edges? (empty, null, maximum, concurrent)
5. ACCEPT: What criteria demonstrate correctness?
6. WRITE: Produce the specification document
7. APPROVE: Obtain user confirmation
8. ONLY THEN: Implement

Omit any step = building the wrong thing

仕様書テンプレート

# [Feature Name] Specification

## Purpose
[Single sentence: what this does and why it exists]

## Inputs
| Input | Type | Required | Constraints | Default |
|-------|------|----------|-------------|---------|
| [name] | [type] | [yes/no] | [validation rules] | [default] |

## Outputs
| Scenario | Output | Shape |
|----------|--------|-------|
| Success | [what is returned] | [type/structure] |
| Invalid input | [error response] | [error shape] |
| Not found | [404 response] | [error shape] |

## Behavior

### Standard Path
1. [Step-by-step behavior for normal usage]
2. [Include state mutations, side effects]

### Edge Cases
| Case | Input | Expected Behavior |
|------|-------|-------------------|
| Empty input | "" | Return validation error |
| Maximum length | 10000 chars | Truncate to 5000 |
| Concurrent access | 2 simultaneous requests | Serialize second request |
| [case] | [input] | [behavior] |

## Acceptance Criteria
- [ ] [Criterion 1 - testable, specific]
- [ ] [Criterion 2 - testable, specific]
- [ ] [Criterion 3 - testable, specific]

## Explicitly Excluded (YAGNI)
- [Feature intentionally omitted]
- [Optimization intentionally deferred]

テストファースト開発との関係

digraph spec_test_flow {
    rankdir=LR;
    spec [label="Author Spec\n(this skill)", shape=box style=filled fillcolor=lightyellow];
    test [label="Write Failing Test\nfrom Spec Criteria", shape=box style=filled fillcolor="#ffcccc"];
    code [label="Write Minimal Code\nto Pass Test", shape=box style=filled fillcolor="#ccffcc"];
    verify [label="Verify Against\nSpec Criteria", shape=box style=filled fillcolor="#ccccff"];

    spec -> test [label="acceptance criteria\nbecome test cases"];
    test -> code [label="test-first cycle"];
    code -> verify [label="all criteria satisfied?"];
    verify -> spec [label="no - revise spec\nor implementation"];
}

仕様 -> テスト -> コード -> 仕様に照らした検証

仕様の受け入れ基準は、テストケースに直接対応します。各基準から、少なくとも 1 つのテストを作成します。基準からテストを導き出せない場合、その基準は曖昧すぎるため、仕様を見直してください。

仕様の詳細レベル

レベル	適切な場面	範囲
最小限	単純な機能、動作が明白	目的 + 入力 + 出力 + 受け入れ基準 3 項目
標準	ほとんどの機能	上記の完全なテンプレート
徹底的	複雑なシステム、公開 API、マルチテナント	完全なテンプレート + シーケンス図 + ステートマシン + エラー分類

複雑さに応じて仕様の詳細度を調整します。ユーティリティ関数には最小限の仕様が適切です。認証システムには徹底的な仕様が必要です。

認知上の落とし穴

合理化	実態
「仕様を書くほどのものではない」	単純な機能にも、隠れたエッジケースがあります。仕様の作成には 2 分かかります。
「コーディングしながら考えればよい」	間違ったものを作り、3 回もリファクタリングすることになります。
「ユーザーはすでに希望を説明している」	ユーザーが説明するのは目標であり、動作ではありません。仕様がその隔たりを埋めます。
「テストファーストで十分。仕様は必要ない」	テストファーストは、何を検証するかを示します。仕様は、何を作るかを示します。どちらも必要です。
「仕様を書くと遅くなる」	仕様は間違ったものを作ることを防ぎます。測定可能なあらゆる点で、その方が速くなります。
「仕様は後で書けばよい」	実装後に書かれた仕様は、本来作るべきものではなく、作ったものを正当化します。
「AI は私の意図を理解している」	AI は意図から外れている可能性のある、もっともらしいコードを生成します。仕様によって曖昧さをなくせます。

ガードレール

禁止事項：

• 仕様の承認前に実装を開始する
• 仕様の基準を参照せずにテストを書く
• 仕様を更新せずに動作を変更する
• 受け入れ基準に照らして検証せずにリリースする
• エッジケースへの対応を先送りする（「後で対応する」）
• 実装完了後に仕様を書く

必須事項：

• コードを書く前に仕様の承認を得る
• 受け入れ基準とテストケースを 1 対 1 で対応させる
• 要件の変更に応じて仕様を更新する
• 完了を宣言する前に、すべての基準に合格していることを検証する
• 明示的に対象外とする機能（作らないもの）を含める

統合

ワークフローの順序：

• godmode:intent-discovery -> 設計を作成します
• godmode:specification-first -> 設計から仕様書を作成します
• godmode:task-planning -> 仕様書から実装計画を作成します
• godmode:test-first -> 仕様書の基準に基づいてテストを作成します
• godmode:completion-gate -> 仕様書の基準に照らして検証します

必須の併用スキル： 実装時に godmode:test-first を呼び出します