Image
MVP to Stable

Building on undocumented and esoteric third-party systems

Your product depends on a system nobody documented, and every guess about it is a hidden risk. This is how an agent maps what it actually does, keeps the observed apart from the assumed, and contains it behind one adapter in your code, while the third-party system itself is never changed.

The short answer

Short answer

You build on a third-party system with no documentation by learning what it actually does before you rely on it.

Observe it read-only, mark each behaviour observed or assumed, pin the observed ones in boundary tests, and keep the system behind one adapter in your code. Any first write to the live system waits for your named owner.

The risk

Why is a system you do not own so risky to build on?

Your product has to work with a system you did not build: an old platform, a niche vendor's interface, a file drop in a format nobody wrote down. The person who understood it has left, or never existed. Every guess your code makes about it is a risk you cannot see until something fails on their side and the failure surfaces in yours. Hyrum's Law puts the wider point plainly: with enough users of an interface, it does not matter what the contract promises, because all observable behaviours of a system will be depended on by somebody.

Who needs this?

A founder or technical lead whose product must talk to an old, niche or poorly documented external system, and who has been told it cannot be done, or cannot be done safely. You may own the product and its code. You do not own the other system, its terms or its access, and nothing here changes that.

How is each behaviour of the system recorded?

The behaviour map is the working record. Every entry in it carries one of these states, and the state decides what your code may do with it.

What you knowHow it is markedWhat your code may do with itWho decides
Behaviour seen directlyObserved, with the request, the response and where it was seenRely on it, with a boundary test that pins itYour reviewer merges the test
Behaviour taken from old docs, messages or sample filesAssumed, tagged with where it came fromNothing load-bearing until it is observedYour owner, if it must be used sooner
A question nobody can answer yetOpen unknown, kept on the listTreat as unknown, never filled in by a guessYour owner sees the full list
Behaviour that differs from last timeA failing boundary testHold the affected path until a fix lands in the adapterA person on your side
The first write to the live systemPending sign-offNothing, until approvedYour named owner

How it works, step by step

The external system is treated as something to learn, never as something to fix. What changes is your code at the boundary with it.

01

Gather what is already known

Partial docs, sample files, old messages and the code that already calls the system, each item tagged with where it came from. All of it starts as assumed.
02

Observe before relying on anything

The agent exercises the system read-only, or in a test environment you provide, and records what it accepts, returns and rejects. Martin Fowler notes that when testing an external service, it's usually best to do so against a test instance of it.
03

Keep observed and assumed apart

The behaviour map marks every behaviour as observed, with its evidence, or as assumed. Open unknowns stay listed as open, where everyone can see them.
04

Pin observed behaviour at the boundary

Boundary tests sit at the edge of your code, so a change on their side shows up as a failing check on yours. They work like Fowler's contract tests, which check that the answers your test doubles give match what a call to the external service would return.
05

Contain the unknown in one adapter

The external system sits behind a single adapter in your code, so its quirks live there and nowhere else. Fowler's gateway pattern describes the same move: rather than let an external system's awkwardness spread through the code, contain it in a single place.
06

Human gate on the first live write

Any first write to the live external system, any use of production credentials and any new dependency on it goes to your named owner for sign-off. Until then the agent only reads. A reviewer on your side merges the adapter and its tests. Both holds are kept as How It Works sets out, and the approval gates page covers where such a sign-off belongs.
07

Leave their system as it was found

Nothing in the third-party system is changed. It is used as it stands, within the access its owner grants. Eric Evans describes this in his anticorruption layer, which works with the other system through its existing interface and needs little or no change to it.

Boundaries

What stays out of bounds?

Their system

No change to it, no workaround inside it, and no access beyond what its owner grants.

Guesses presented as facts. An assumed behaviour is never relabelled as observed without evidence.

Unattended writes

Reads come first; a write to the live system needs your named owner's sign-off.

Your other code

Repairing the rest of your code is covered on a sibling page about hardening, and an undocumented dependency may first surface as a finding on the assessment checklist.

Where this fits

MVP to Stable

Undocumented systems sit at the outer edge of MVP-to-Stable product work: the product works, and part of what it depends on sits outside it. The same habit of watching before acting runs through shadow mode, where an agent works beside your team without touching a real record. If the job is a recurring process rather than a product, start with the readiness checklist or browse the full set of use cases.

Scattered calls or one adapter: what is the difference?

QuestionCalls spread through your codeOne adapter with boundary tests
Where the system's quirks liveWherever a call was writtenIn the adapter only
What a change on their side breaksWhatever happens to depend on it, found by a userA boundary test, where one covers that behaviour
Where a fix landsIn every place that made the callIn the adapter
What a reviewer readsChanges scattered across the productOne file and its tests
MVP to Stable Product
How It Works

Questions, answered

Yes. The map is then built from observation and from the code that already calls the system. Some unknowns stay unknown, and they stay on the list.
AI Opportunity Audit · Undocumented systems

Bring the system nobody can explain, and map it first

Bring the one system your product depends on that nobody can explain.