Operating principles

Interfaces are built for machines first

Every interface your company builds or buys now has a second reader, and it cannot ask a colleague what a field means. Build for that reader first and the human screen becomes one client among several. Build for the human alone and every integration needs a person in the middle. The test: could an agent nobody briefed drive it today?

Decision rights

An interface a machine cannot drive has to be refusable, and in most companies the person who can refuse it does not work in engineering, because the company runs on software it bought. So the decision lands in the evaluation, before the contract. "Can a program do this without a person reading a screen" costs one question at that moment. The same question a month after signing is a feature request queued behind every other customer's.

The estate you already have is not the subject, and nobody should promise you a retrofit. The scope is the next system you buy and the next surface you build, which happens several times a year. The criterion is free at that moment and expensive at every other one.

Memory and context

A human interface keeps its meaning somewhere else. A column called Status means whatever this team means by it, and the team knows because someone explained it in their first week. A machine has no first week. Everything a colleague would have supplied has to be in the thing itself: what the field is, what values it takes, what changed last.

Errors are where the gap opens widest. A message written for a person says something went wrong and trusts the human to work out what. A program needs to know which failure it was, because it retries one kind and stops on the other. An error nothing can branch on is a dead end wearing a sentence. The contract lives where the agent hits it, not in a wiki. See Context lives in files.

Execution

Wrapping is the fallback and it works. A thin service in front of something that will never change puts the schema and the error codes where they were missing. The estate underneath stays exactly as bad as it was. Price it honestly: the wrapper is a system, it needs an owner, and it goes stale the first time the thing behind it moves.

What a wrapper cannot buy back is state. Some systems hold half of what they know in a session, or in a sequence of screens that has to be walked in order. Those stay expensive to drive from outside whatever you put in front of them. Hidden state is the property to test for during evaluation, because nothing downstream repairs it.

Governance

The rule that survives contact is narrow: no new outward-facing surface ships human-only, and any exception gets written down when it is granted. A broad rule covering the whole estate is suspended by month two and never comes back.

The exception that quietly eats this one is the internal tool nobody expects an agent to touch. Agents arrive there first, because internal is where permission is easiest to get.

Readable, discoverable and permitted are three separate questions and this page answers the first. What an agent may then do is a rung on the autonomy ladder, on credentials scoped under agent identity. Answer them as one question and a read-only integration acquires write access on the strength of being easy to extend.

Observability

Count how many systems in your critical path a program can reach with nobody in the middle. Count it, do not estimate it. It moves slowly and only when somebody owns the number.

A cheaper signal arrives sooner: how often a new integration gets built by scraping a screen or parsing a report formatted for printing. Each one is an interface that failed this test, and the engineer who wrote the scraper can already name it.

One failure shows up last and costs the most. An interface can pass every check a machine makes and still be wrong, because a machine that can read a field will read it whether or not the number in it is current. The other half of that problem is Data foundations first, and neither half covers for the other.