Every established product has a core that the in-house team knows well and a backlog that keeps growing around it. A new capability often has to touch that core: read its data, call its services, react to its events. The usual concern is not whether the feature can be written but whether it can be added without disturbing what already works. Written contracts are one of the most practical answers, and they are worth settling before implementation begins.
The boundary is the real design decision
When a new feature runs next to an existing system, the interesting part is the seam between the two. On one side is the established code, with its own release rhythm and its own owners. On the other is the new work. Whatever crosses the seam, whether an API call, a message or a database view, is a promise made by one side and relied upon by the other. If the promise is only implied, each side fills the gaps with its own assumptions, and the gaps surface later as defects that no team owns.
Writing the promise down turns an assumption into something that can be checked. A contract names the fields, the formats and the error cases, and it states what the consumer is allowed to depend on. It should also state what is deliberately left open, because that tells the core team where it remains at liberty to change things.
Consumer-driven contracts
Consumer-driven contracts reverse the usual direction. Instead of the provider publishing a specification and every consumer adapting to it, each consumer states what it actually uses, and the provider verifies that those expectations hold. Ian Robinson’s article on the pattern, hosted on Martin Fowler’s site, frames the provider’s obligations as the set of its consumers’ expectations, which means a provider can change anything that no consumer relies on. The Pact documentation presents the same idea as executable tests: the consumer records the interactions it expects, and the provider replays them against the real implementation.
For a new feature, the new code is simply another consumer of the core, and its contract is small by nature: the handful of calls and fields it needs. That keeps the conversation with the core team concrete. Instead of asking for broad access, the feature team brings a short list of expectations, and the core team checks the list against what the core really does.
What a useful contract contains
A contract does not need to be long. The items below cover most of what a seam needs:
- Inputs and outputs. The fields, their types and which of them are required.
- Failure behavior. What the core returns when data is missing, a record is locked or a downstream call times out.
- Ownership. Who may change the contract and who must agree before a change.
- A versioning rule. How a change is announced before it lands, so that the other side can react.
- Evidence. A test or script that either side can run and that fails loudly when the promise is broken.
Where the product owner fits
A contract is technical, but its starting point is a product statement. The product owner knows which behavior of the feature matters and which can be traded. A sentence such as “an order must appear in the new view within the same session, even when the legacy status update is delayed” is a product decision, and it becomes a clause about the read path. When the product owner takes part in writing such clauses, mismatches between intent and implementation can be discussed as a conversation instead of being found as a defect.
This is also the practical meaning of work on a live product: the feature has its own code and release path, the core keeps its own, and the contract is the written agreement between them. The in-house engineers remain the authority on the core, and the feature team behaves as a careful consumer of it. How this arrangement works for product owners, from acceptance criteria to handover, is described under feature development for existing products.
Tests as the shared language
A contract that lives only in a document ages quickly. Running it as a test in both pipelines gives the two teams the same signal. When the feature’s build fails because a field disappeared, the cause is visible before anything reaches users. When the core’s build fails because a change would break a documented expectation, the core team learns which consumer is affected and can talk to its owner before merging.
The same tests help with the less visible part of the work: knowing what each side may safely remove. Unused fields can be retired with confidence only when someone can show that no contract mentions them.
Common pitfalls
- Contracts that mirror the whole schema. A contract that lists every field the core has becomes a brake on the core team. Keep it to what the feature uses.
- Contracts without an owner. If nobody is responsible for updating the clauses, the document and the behavior drift apart.
- Stubs that nobody verifies. A fake of the core used in the feature’s tests is only as good as its last comparison with the real thing. Verification against the provider is the point of the exercise.
- Confusing the contract with acceptance. The contract shows that the seam holds. Acceptance shows that the feature does what the product owner meant. Both are needed, and neither replaces the other.
A short checklist
Before the first line of the feature is written, the team can ask whether the expectations toward the core fit on one page, whether the core team has read and agreed to them, whether there is a runnable check on both sides, and whether the product owner can read the clauses that describe user-visible behavior. A “no” to any of these is a useful finding while the work is still cheap to adjust.
Contracts do not remove the need for judgment about what the core can bear, but they make the judgment visible and shared. This article is published by JetRuby Team as a general engineering note for product teams that add new capabilities next to systems they already run.