machenjie contract-testing
Registry Trigger
Use when
- prove provider-consumer compatibility for an API, event, schema, generated client, or captured external behavior
Do not use when
- the change has no independent consumer expectation, compatibility transition, or retained-message/replay risk
Skill Role
Prove executable compatibility on named provider-consumer surfaces. Exclude broad consumer discovery, contract design, and release verdicts.
High-Value Rules
- Name the provider, known and unknown consumer classes, authoritative or observed contract source, versions that may coexist, and compatibility direction. A provider self-test does not establish consumer admissibility.
- Contract the semantics consumers branch on: absent versus null, defaults, error and authorization shapes, unknown fields or enum values, ordering, pagination, and duplicate or replay behavior. Avoid copying provider internals into expectations.
- Prove both sides of the boundary: provider verification shows named expectations can be served; consumer or generated-client evidence shows named consumers can accept them. Unrepresented consumer classes remain explicit proof limits.
- Classify compatibility with the actual protocol, reader/writer rules, retention window, and rollout order. Neither an additive change nor a schema-tool pass is universally safe.
- Treat registries, brokers, generated clients, diffs, and vendor fixtures as scoped evidence. Record the selected subject/version/environment or capture provenance, plus behavior and consumers they do not prove.
- Exercise old/new producer-consumer combinations and retained or replayed payloads when versions coexist. Preserve field identifiers, unknown-value behavior, and migration semantics required by the selected protocol.
- Re-run affected checks after contract, fixture, generator, compatibility-policy, or consumer-selection changes. Redact captured credentials and tenant data, and disclose unavailable consumers or environments.
Anti-Patterns
- Declaring compatibility from schema shape alone while semantic meaning, error behavior, or consumer tolerance changed.
- Inventing a vendor or consumer mock from memory, or treating one captured response as the provider's complete behavior.
- Applying one broker, registry mode, versioning style, or consumer-driven workflow to every boundary.
- Replacing integration, journey, consumer discovery, or rollout proof with contract tests.
Stop Conditions
- Escalate when unknown or independently deployed consumers, retained messages, undocumented provider behavior, or an unavailable compatibility environment prevent a bounded claim and no owner accepts the residual risk.
Output Contract
- provider-consumer compatibility decision with covered versions, semantic expectations, executable proof, freshness, and explicit non-proof boundaries
Targeted References
| Path | Type | Load when | Do not load when | Required by | Required output |
|---|---|---|---|---|---|
| benchmarks and patterns | benchmark-pattern | Compatibility direction protocol mixed versions retained payloads generated clients or external behavior leave proof choices open | One named provider consumer surface and its compatibility rule resolve the decision | analysis-agent, task-agent, review-agent | option-comparison, selected-approach |
| checklist | decision-checklist | Several semantic version consumer fixture replay or rollout decisions must close together | No provider consumer expectation or compatibility behavior changes | analysis-agent, task-agent, review-agent | checklist-result, residual-risk |
| evidence patterns | evidence-pattern | Provider consumer mixed-version fixture broker registry or generated-client claims need fresh scoped proof | Fresh named-provider and named-consumer results close the bounded compatibility claim | analysis-agent, task-agent, review-agent | evidence-record, proof-limit, residual-risk |