Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

contract-design

/contract-design

Projektuje kontrakt API, zdarzeń lub schematu z naciskiem na zgodność: strategia wersjonowania, zgodność wsteczna, ścieżka migracji konsumentów i semantyka błędów, wraz z listą wpływu na konsumentów.

Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Projektuje kontrakt API, zdarzeń lub schematu z naciskiem na zgodność: strategia wersjonowania, zgodność wsteczna, ścieżka migracji konsumentów i semantyka błędów, wraz z listą wpływu na konsumentów.

Oryginalny opis (EN)

Design an API, event, or schema contract with compatibility as the primary concern - versioning strategy, backward compatibility, migration path for existing consumers, and failure semantics - plus a consumer impact list. Use when creating or changing anything that crosses a team boundary, when adding a field to a published response or event, when consumers exist outside your repository, or when someone asks how to version an API. Once consumers exist you do not control, the contract stops being a design problem and becomes a coordination problem.

Jak działa

  1. Why this exists
  2. When this applies
  3. When it doesn't
  4. Prerequisites
  5. Procedure
  6. Output
  7. Common traps
Sekcje z nagłówków SKILL.md, w oryginale · 190 linii, 1 614 słów
Podgląd SKILL.md
---
name: contract-design
description: Design an API, event, or schema contract with compatibility as the primary concern - versioning strategy, backward compatibility, migration path for existing consumers, and failure semantics - plus a consumer impact list. Use when creating or changing anything that crosses a team boundary, when adding a field to a published response or event, when consumers exist outside your repository, or when someone asks how to version an API. Once consumers exist you do not control, the contract stops being a design problem and becomes a coordination problem.
---

# Contract design

Designing something other people depend on.

## Why this exists

An internal interface can be changed by editing every caller. A published contract cannot, and the moment consumers exist outside your repository the constraints change completely: you no longer control when they upgrade, whether they upgrade, or in some cases who they are.

The characteristic mistake is designing a contract as though it were an internal interface — shaped for the current implementation, with no versioning story — and discovering the constraint when the first breaking change is needed. By then the options are all expensive.

An FDE hits this specifically because you often can't see the consumers. `blast-radius` ring 4 is the hardest ring to establish from inside one repository, and contracts are exactly where an unknown consumer hurts.

## When this applies

- Creating or changing an API, event, message, or shared schema
- Adding a field to a published response or event payload
- Consumers exist outside your repository
- "How should we version this?"
- Anything crossing a team boundary

## When it doesn't

- Internal interfaces with all callers in one repository — refactor freely
- A prototype nobody consumes yet
- The contract exists and isn't changing — that's `blast-radius`

## Prerequisites

Resolve `<workspace>` before reading or writing artifacts: use `FDE_WORKSPACE` if set (report an unavailable explicit path rather than falling back), otherwise the charter's recorded Location (look in `.fde/` and `../*-fde/`), then an existing `.fde/` or `../<repo>-fde/`. If none exists, run core `fde-orient`; do not create a second workspace. All artifact paths below use that location. Follow core workspace conventions for headers; preserve existing sections when appending.

- `<workspace>/06-blast-radius-*.md` — ring 3 and ring 4 especially. **You need the consumer list before designing.** If ring 4 was not checked, design as if consumers are uncontrollable.
- `<workspace>/03b-nfrs.md` — data classification determines what may cross the boundary
- `<workspace>/02b-ownership.md` — who must be coordinated with

## Procedure

### 1. Establish who consumes it, and how much control you have

This determines everything downstream, and the categories behave very differently:

| Consumer type | Control | Implication |
|---|---|---|
| Same team, same repo | Full | Change freely; this isn't really a contract |
| Other team, same org | Coordinated | Breaking changes possible with notice and effort |
| External partner | Contractual | Breaking changes need commercial agreement |
| Mobile or embedded client | **None** | Old versions live forever. Design for indefinite compatibility. |
| Unknown | **None, and you can't ask** | Treat as the most constrained case |

The mobile case is the one engineers under-weight. You cannot deploy a fix to an app on someone's phone; a two-year-old client version will still be calling. "Backward compatible until the next release" and "backward compatible indefinitely" are different designs.

Where consumers are **unknown** — common, and the honest state after a blast-radius ring 4 you couldn't complete — design as though they're uncontrollable. That's the cost of not knowing, and it's cheaper than the alternative.

### 2. Choose what changes are allowed to be

Decide, before designing, which categories of change you're committing to support. Broadly consistent across formats:

**Usually safe:**
- Adding an optional field
- Adding a new endpoint, message type, or enum member *(see below)*
- Relaxing a validation constraint

**Usually breaking:**
- Removing or renaming anything
- Making an optional field required
- Changing a type or its semantics
- Tightening validation
- Changing the meaning of an existing value

**Adding an enum value deserves its own thought.** It is safe only if consumers are built to tolerate unknown values, and many are not — a strict parser or an exhaustive switch will reject or crash. Whether this is safe is a property of your *consumers*, not of your schema, so it can only be answered by knowing them.

The same applies to added fields: additive is safe unless a consumer uses strict schema validation, parses positionally, or round-trips the payload. Check rather than assume — this is the most common way an "obviously safe" change breaks something.

### 3. Pick a versioning strategy and state the lifecycle

Options, each with a real cost:

| Strategy | Cost |
|---|---|
| **No versioning, additive only** | Simple; you can never remove anything |
| **URI or namespace version** (`/v2/`) | Explicit and visible; doubles surface area while both live |
| **Header or content negotiation** | Cleaner URLs; harder to see what's in use |
| **Schema evolution** (Avro, Protobuf) | Strong tooling; requires discipline about field numbering and defaults |
| **Event type versioning** | New event type alongside the old; consumers migrate independently |

Whichever you choose, define the **lifecycle** explicitly, because this is what people skip: how long does a version live, what triggers deprecation, how much notice do consumers get, and what happens to a consumer that doesn't migrate?

A version with no defined end lives forever. Most organizations have three "current" API versions because nobody ever said when v1 stops.

### 4. Design the failure semantics

Half of a contract, and routinely undocumented — leaving each consumer to guess, differently.

- What errors can this return, and what does each mean?
- Which are retryable, and which will never succeed?
- Is the operation idempotent? If a consumer retries after a timeout, what happens? **This is the single most important question in the contract**, and the least often answered.
- What's the timeout expectation on both sides?
- What happens on partial success?

An idempotency key mechanism, defined up front, prevents a whole category of duplicate-processing incidents. Retrofitting one later is far harder because consumers have already built retry logic against its absence.

### 5. Be deliberate about what you expose

A contract is a commitment. Everything in it is something you must keep supporting.

- Don't leak internal structure — an entity serialized straight from the domain model couples consumers to your internals, and every refactor becomes a breaking change
- Don't expose fields consumers don't need. Each is a future constraint.
- Don't expose sensitive data because it was convenient — every consumer inherits that data and its retention obligations. See `security-compliance-check`.
- Do include what consumers will obviously need next, if it's cheap. Adding it later is easy; the coordination isn't.

### 6. Write the migration path before you need it

For any change requiring consumers to act: what do they do, by when, what happens if they don't, and how do you know who has migrated?

That last one matters and is usually impossible retrospectively. **Build version observability in from the start** — log the version each consumer uses, so "can we retire v1?" is a query rather than a guess. Without it, retiring a version becomes a consumer-discovery project — the same problem `decommission-plan` exists for if `fde-migration` is installed.

### 7. Document it where consumers will look

A contract only documented in code isn't a contract. Machine-readable where the ecosystem supports it — OpenAPI, `.proto`, JSON Schema, Avro — because that gives consumers generated clients and gives you contract testing.

Record the decision in an ADR via `solution-design`. The versioning strategy in particular is a decision future engineers need the reasoning for.

## Output

ADR at `<workspace>/adr/NNNN-contract-<name>.md`, plus the machine-readable schema in the repo:

```markdown
# ADR-NNNN — <contract> versioning and compatibility

**Status:** proposed · **Deciders:** <who> · **Date:** <YYYY-MM-DD>
**Engagement:** <name>
**Author:** FDE
**Source revision:** <repo>@<short SHA>, or "no repository yet"
**Confidence:** <what is confirmed, inferred, or unverified>

## Decision
<One sentence.>

## Consumers
| Consumer | Type | Control | Can we coordinate? |
|---|---|---|---|
| `billing-web` | internal | coordinated | yes |
| Partner X extract | external | contractual | 90 days' notice per agreement |
| Mobile app | **uncontrollable** | none | **no — v1.x will call indefinitely** |
| Unknown | — | none | **assume uncontrollable** |

## Compatibility commitment
- Additive optional fields only, within a major version
- Unknown fields MUST be ignored by consumers — **stated in the contract docs**
- Unknown enum values MUST be tolerated — `UNKNOWN` fallback defined
- Breaking changes require a new major version + 12 months' overlap

## Versioning
**Strategy:** URI major version · **Lifecycle:** 12 months' overlap minimum, deprecation
announced at new-version launch · **Retirement gate:** < 0.1% traffic for 30 days

## Failure semantics
| Condition | Response | Retryable | Idempotent |
|---|---|---|---|
| Validation failure | 400 + field list | no | n/a |
| Downstream unavailable | 503 + `Retry-After` | yes | yes — `Idempotency-Key` required |
| Duplicate idempotency key | 200, original result | n/a | yes |

## Version observability
`consumer_id` + `api_version` logged per request → retirement is a query, not a guess.

## Migration path
<What consumers do, by when, what happens if they don't.>
```

## Common traps

**Designing it like an internal interface.** You don't control when consumers upgrade, or whether.

**Assuming additive is safe.** Strict validators, positional parsers, and round-trippers all break. A property of consumers, not of your schema.

**Adding an enum value without checking consumer tolerance.** Exhaustive switches crash.

**No defined version lifecycle.** Three "current" versions forever, because nobody said when v1 ends.

**Undocumented failure semantics.** Every consumer guesses differently, and their retry logic becomes your problem.

**No idempotency story.** Retrofitting one after consumers have built retries around its absence is far harder.

**Serializing the domain model.** Every internal refactor becomes a breaking change.

**No version observability.** "Can we retire v1?" becomes a consumer-discovery project.

**Forgetting mobile.** Old versions live forever, and you cannot deploy a fix to them.

Wersje

RepozytoriumWynikLicencja
Ta strona · rpraharaj/forward-deployed-engineer100MIT
geekatron/jerry100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 3433313f60fa (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90api-design
    Projektuje interfejsy odporne na zmiany po stronie konsumentów: model zasobów, błędy, wersjonowanie, paginacja i zgodność wsteczna.
  • 100api-design
    Podaje wzorce projektowania stabilnych API dla konsumentów: kontrakt-first, semantyka błędów RFC 9457, konwencje REST, paginacja, idempotencja i zgodność wsteczna.
  • 100api-contract-reviewer
    Recenzuje kontrakty API i zdarzeń pod kątem poprawności, spójności, zgodności wstecz, błędów i wersjonowania oraz testowalności.
  • 100api-contract-reviewer
    Ocenia kontrakty API, zdarzeń i bibliotek klienckich: spójność, zgodność wstecz, semantykę błędów i możliwość testowania.
  • 90api-contracts
    Projektuje lub zmienia kontrakt API dla nowych i istniejących klientów: endpointy, schematy, błędy, uwierzytelnianie i wersjonowanie.
  • 90api-design
    Projektuje kontrakt API przed implementacją: stabilność interfejsu, zgodność wsteczną i specyfikację kontraktu błędów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.