# Contract Driven Development

> API 契約、I/O 契約、モジュール境界を先に固定してから安全に実装を進める実行手法スキル。入出力、境界条件、互換性、契約テスト観点を整理し、主に API 開発や境界のある実装系スキルの補助として使う。「契約から先に固めたい」「API 契約を決めてから実装して」「I/O を固定して進めたい」「境界条件を先に整理したい」などで発動する。

- Skill: `ynitto/contract-driven-development` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ynitto/contract-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/contract-driven-development/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/contract-driven-development

---


# contract-driven-development

API 契約、I/O 契約、モジュール境界を先に固定し、その契約を破らない形で実装を進める。

このスキルは **プライマリスキルではなく補助スキル** として使うのが基本である。実装そのものは既存の実装系スキルに委譲し、本スキルは「何を契約として固定するか」「互換性をどう守るか」「何で契約充足を確認するか」を管理する。

---

## 駆動源の定義

このスキルの駆動源は **契約** である。ここでいう契約は、少なくとも次のいずれかを含む。

- API の request / response 仕様
- モジュール境界の入力・出力・例外
- イベント payload やメッセージ形式
- データ構造の必須項目・型・制約
- 境界条件、エラー条件、互換性ルール

判断は「何を作るか」より先に、**何を守れば統合が壊れないか** で行う。

---

## パス解決

このSKILL.mdが置かれているディレクトリを `SKILL_DIR`、その親ディレクトリを `SKILLS_DIR` とする。他スキルは `${SKILLS_DIR}/[skill-name]/SKILL.md` を優先して探す。

---

## Step 0: スコーピング

最初に、このスキルを本当に適用すべきかを判定する。

### 適用する

- API、ライブラリ、モジュール、外部連携など **境界がある**
- 実装前に I/O を固定した方が後戻りが減る
- 複数実装者、複数クライアント、複数コンポーネントの調整が必要
- 互換性や deprecation を意識する必要がある
- 契約テストや schema validation に落とし込める

### 適用しない

- 純粋な内部実装で明確な境界がない
- 仕様が探索段階で、契約を先に固定するとかえって邪魔になる
- 変更順序や停止条件の管理が主眼で、`risk-driven-development` の方が適切
- 異常系・回復戦略の設計が主眼で、`failure-driven-development` 相当の方が適切
- 文書更新のみで契約対象が存在しない

### Step 0 の出力

```
適用判定: APPLY / SKIP
契約対象: [API / モジュール / イベント / その他]
代替: [なし / 代替スキル名]
```

**ゲート条件:** `APPLY` の場合のみ Phase 1 へ進む。`SKIP` の場合は理由と代替を返して終了する。

---

## Phase 1: 契約対象の特定

最初に、どの境界を契約として扱うかを決める。

最低でも次を列挙する。

| 観点 | 確認内容 |
|---|---|
| 提供者 | 契約を満たす側は誰か |
| 利用者 | 契約に依存する側は誰か |
| 入力 | 必須項目、型、制約、順序 |
| 出力 | 正常系、異常系、型、意味 |
| 境界条件 | 空、最大値、欠損、重複、順序違い |
| 互換性 | 何が breaking で何が non-breaking か |

出力形式:

```
契約名: [名称]
提供者: [コンポーネント名]
利用者: [クライアント / モジュール]
対象境界: [何と何の境界か]
```

**ゲート条件:** 契約対象が 1 つ以上具体化されていること。誰が使うかわからない契約は固定してはならない。

---

## Phase 2: 契約本体の固定

契約を実装前の基準として書き下す。形式は対象に合わせてよいが、最低限次の要素を持たせる。

### 必須項目

1. **入力契約**
   - フィールド名
   - 型
   - 必須 / 任意
   - 制約
2. **出力契約**
   - 正常系の応答
   - 異常系の応答
   - 意味上の保証
3. **境界条件**
   - 最小値 / 最大値 / 空入力 / 不正入力
4. **互換性ルール**
   - breaking
   - non-breaking
   - deprecation の扱い

### 出力形式

以下のどれか、または複数を選ぶ。

- OpenAPI / GraphQL schema
- JSON schema
- テーブル形式の I/O 契約
- 関数シグネチャ + 入出力仕様
- イベント仕様書

### Step 2 の出力テンプレート

```
契約サマリー:
- 入力: [要約]
- 出力: [要約]
- 境界条件: [要約]
- breaking 条件: [要約]
- non-breaking 条件: [要約]
```

**ゲート条件:** 入力・出力・境界条件・互換性ルールの 4 つがすべて揃っていること。1つでも欠けていれば Phase 2 をやり直す。

---

## Phase 3: 契約テスト観点の定義

実装の前に、契約が満たされたかを何で確認するかを決める。

契約テストは実コードでなくてもよいが、最低でも以下の観点を持つ。

- 正常入力が契約どおり通る
- 必須項目欠落時に期待どおり失敗する
- 型不一致・制約違反時に期待どおり失敗する
- 境界値で意味が壊れない
- 既存利用者に対して breaking change が混入していない

出力形式:

```
契約テスト観点:
- CT1: [正常系]
- CT2: [必須欠落]
- CT3: [型・制約違反]
- CT4: [境界値]
- CT5: [互換性確認]
```

**ゲート条件:** 最低 3 観点、可能なら 5 観点を列挙すること。互換性のある境界なら `CT5` を省略しない。

---

## Phase 4: 実装への受け渡し

ここから先の実装はプライマリスキルに委譲するが、以下を実装開始前に固定する。

### 実装開始前チェック

- 契約の最新版が 1 つに定まっているか
- 変更対象がその契約に従うと明言できるか
- 契約未確定事項が残っていないか
- 実装中に契約変更が必要になった場合の戻り先が明確か

### 実装中のルール

- 実装都合で契約を黙って変えない
- 契約変更が必要なら Phase 2 に戻る
- breaking change は「必要性」「影響」「移行手段」を伴わない限り許可しない

実装に渡すべき要約:

```
実装前提:
- 守る契約: [名称]
- 重要な境界条件: [要約]
- 禁止事項: [黙った breaking change など]
- 検証方法: [契約テスト観点 or schema validation]
```

**ゲート条件:** 実装を始める前に「守る契約」が 1 つに定まっていること。複数版が併存する状態で進めてはならない。

---

## Phase 5: 完了レポート

最後に、固定した契約と実装への影響を短くまとめる。

```
## Contract-Driven 完了レポート
契約対象: [内容]
固定した契約: [形式と要約]
契約テスト観点数: [N]
breaking change の有無: [なし / あり]
残留未確定事項: [なし / 内容]
推奨次アクション: [1〜3件]
```

### verdict-json

```json
<!-- verdict-json -->
{
  "skill": "contract-driven-development",
  "verdict": "PASS | HOLD | FAIL",
  "contract_target": "[summary]",
  "contract_format": "[schema/table/signature]",
  "blocking": false,
  "open_questions": []
}
<!-- /verdict-json -->
```

---

## 既存スキルとの組み合わせ

### 相性が良い

- `api-designer` — API 契約の固定と OpenAPI / GraphQL 生成
- `requirements-definer` — 契約に落とす前の要求整理
- `react-frontend-coder` — API 契約確定後のクライアント実装
- `test-driven-development` — 契約テストを先頭に置く場合のサイクル管理

### 使い分け

- 変更順序や停止条件の設計が主眼なら `risk-driven-development` を優先する
- 可用性や回復戦略が主眼なら `failure-driven-development` 系を優先する
- 仕様自体が曖昧なら、まず `requirements-definer` や `brainstorming` で整理する

---

## エラーリカバリー

| 状況 | 対応 |
|---|---|
| 利用者が不明で契約対象が定まらない | 契約を固定せず、対象の利用者と境界を追加確認する |
| 実装中に契約変更が必要になった | 実装を止めて Phase 2 に戻る |
| breaking / non-breaking の線引きが曖昧 | 既存利用者影響を優先し、曖昧な間は breaking 扱いにする |
| 契約テスト観点が定義できない | 契約が抽象的すぎるため、入力・出力を具体化し直す |
| 2 回以上契約が揺れる | 契約前提が未熟と判断し、ユーザーに再確認する |

---

## アンチパターン

- 「実装してから API を整える」
- 「利用者不明のまま契約を固定する」
- 「境界条件を書かずに happy path だけで進める」
- 「黙って breaking change を入れる」
- 「契約変更を実装都合で吸収し、利用者影響を見ない」

このスキルの目的は、**実装前に境界を固定して統合コストを下げること** である。