
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
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.
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 know | How it is marked | What your code may do with it | Who decides |
|---|---|---|---|
| Behaviour seen directly | Observed, with the request, the response and where it was seen | Rely on it, with a boundary test that pins it | Your reviewer merges the test |
| Behaviour taken from old docs, messages or sample files | Assumed, tagged with where it came from | Nothing load-bearing until it is observed | Your owner, if it must be used sooner |
| A question nobody can answer yet | Open unknown, kept on the list | Treat as unknown, never filled in by a guess | Your owner sees the full list |
| Behaviour that differs from last time | A failing boundary test | Hold the affected path until a fix lands in the adapter | A person on your side |
| The first write to the live system | Pending sign-off | Nothing, until approved | Your 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.
Gather what is already known
Observe before relying on anything
Keep observed and assumed apart
Pin observed behaviour at the boundary
Contain the unknown in one adapter
Human gate on the first live write
Leave their system as it was found
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
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?
| Question | Calls spread through your code | One adapter with boundary tests |
|---|---|---|
| Where the system's quirks live | Wherever a call was written | In the adapter only |
| What a change on their side breaks | Whatever happens to depend on it, found by a user | A boundary test, where one covers that behaviour |
| Where a fix lands | In every place that made the call | In the adapter |
| What a reviewer reads | Changes scattered across the product | One file and its tests |
Related reading
- Exception detection and routing across your ops stack: watching the seams between systems you run.
- Shadow mode: earning trust by observing before acting.
- Approval gates: where a named sign-off belongs.
