ynitto 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: 契約本体の固定
契約を実装前の基準として書き下す。形式は対象に合わせてよいが、最低限次の要素を持たせる。
必須項目
- 入力契約
- フィールド名
- 型
- 必須 / 任意
- 制約
- 出力契約
- 正常系の応答
- 異常系の応答
- 意味上の保証
- 境界条件
- 最小値 / 最大値 / 空入力 / 不正入力
- 互換性ルール
- 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
<!-- 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 を入れる」
- 「契約変更を実装都合で吸収し、利用者影響を見ない」
このスキルの目的は、実装前に境界を固定して統合コストを下げること である。