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.
- Autor
- rpraharaj ↗
- Repozytorium
- forward-deployed-engineer ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 27.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.
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
- Why this exists
- When this applies
- When it doesn't
- Prerequisites
- Procedure
- Output
- Common traps
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
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · rpraharaj/forward-deployed-engineer | 100 | MIT |
| geekatron/jerry | 100 | Apache-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.