Monowai

writing - ai & organisation

Is the organisation the next codebase?

An organisation is a codebase with people in it - boundaries, interfaces, and a great deal of undocumented behaviour everyone has learned to work with or around. This is an argument for writing the seams down and putting a name against each one, and for enterprise architecture describing those capabilities and advocating the automation of them, rather than approving builds. The two questions that survive delegating the code survive here too: which business capability is being fulfilled, and how that function operates at runtime.

Mike Holdsworth · Singapore

AI amplifies the architecture it finds: point an agent at a codebase with strong boundaries and delivery moves predictably, point it at a tangle and you get more tangle, faster. That argument stops at the repository boundary only if you assume the organisation around it is not also structure. It is. And the reader changed here too: what an organisation wrote down, it wrote for people who could ask.

What you are left with when the decisions are not written down is not technical debt, which at best is deliberately prudent and at its worst inadvertently reckless. It is a set of decisions no one can quite explain - an audit headache. Debt is an engineering problem; unexplainable decisions are a governance one, and governance belongs to the organisation rather than the codebase. Sean Grove makes the move in reverse, reading the US Constitution as a national spec: versioned, amendable, with judicial review as its eval suite. That is the layer this argument is about.

An organisation has no compiler and no test suite; its seams are negotiated by people who can push back, reinterpret or ignore them. Impact of change is left to teams to stumble across. A written, governed seam is read the same way by everyone who meets it. An unwritten one is guessed at - and people guess once, then reuse the workaround, so the box gets ticked and everyone is at least imagining the same seam. An agent guesses afresh on every invocation, and it never learned which box to tick - so it reaches for the median. Undocumented agreements used to decay slowly. Now they diverge at the speed you deploy.

On my last project I built a harness that could tell a good OpenAPI spec from a bad one. 15 days of effort, a marginal personal trade and a durable shared asset. It only worked because it had a contract repo to check against: version-controlled contracts owned by the team who reviewed the pull requests. Remove that and there is nothing to hang a gate on - only an agent with an opinion about specs, and a different one each time you ask.

That raises a harder question than which framework to use: what is your organisation's structure, and who owns it?

Start from the job descriptions

If we categorised agents in an organisation around the structure that already exists - HR, Payroll, Finance, Sales, IT - what might that look like? Imagine all of those job descriptions. Assuming everyone's job consists of a great deal of context switching, how many functional MicroContexts - one bounded slice of the job each - might that produce? Who builds them, and who orchestrates them? The tooling will look familiar - Arazzo workflows looking for a capable agent, GitHub Actions assessing security compliance. The ownership will not.

So version control them - or at least consider what it would mean to. A job description is the one artefact an organisation already writes down for every role. Most are stale and written for recruitment, which is an argument for versioning them, not against. It is the closest thing most organisations have to a map of who holds which context. If you were going to anchor AI adoption somewhere structural, that beats starting from whichever team shouted loudest.

Break down the job of a senior systems engineer at the broadest level and you get something like Problem framing, Solution design, Programming, Test design, Integration, Security, Release management and Team coordination. Eight headings, and tracing one feature through them splinters them into a dozen contexts before lunch. Programming is one of the eight, and it is the one that fell first. Agents reach into several of the others - they will write your tests and wire your integrations - but reaching a heading is not holding it. Holding one means being accountable for what good looks like under it, and that is written down for some of the eight far more than others. Which go next has less to do with difficulty than with which ones anyone ever wrote the answer for. Software development is not a typing problem.

I am not claiming this is the answer. I am asking whether it is a better starting point than a tooling rollout - which runs the risk of becoming a golden hammer. It decomposes into exactly the units this post has been circling - a context, a capability, a constraint, an owner. Test it against your own role: how many of your headings could be handed over tomorrow, and how many are waiting on someone writing the answer down?

Spec-driven development scales down better than it scales out. A team can adopt it on Monday; an organisation adopting it needs someone whose job that is. In most shops the question is not answered badly, it is never asked - delivery is the goal, engineering is the overhead. Organisations have the same blind spot as the agent, and no prompt to correct it.

The enterprise architecture we were promised

If the job descriptions decompose into a model of the organisation, then somebody has been claiming to own that model for a long time. Enterprise architecture has held this ground since Zachman put a framework to it in 1987 - TOGAF's business layer, ArchiMate's actors and roles, the capability map on the wall. All of them are attempts to write down what the organisation does and who does it.

That is coming up on forty years of the same promise. It survived unkept because the cost of not keeping it was drift slow enough for people to absorb - someone always knew who to ask, and a wall chart being wrong was an inconvenience rather than an outage. Agents remove that slack. The amplification problem repeats at every layer that has no owner, and this is the top of the stack: there is no further layer to escalate it to. This is the moment for enterprise architects to step up and demonstrate that value, because this model should be the thing that tells you where an agent belongs and who it answers to.

Stepping up is the same review, run at organisational scale. Not approving the build - asking which capability this team or agent fulfils, how that function has to operate, and where both are written down well enough that a gate could fail on them. That is a reviewable position rather than a decision taken away from the people doing the work, and it is the one contribution an agent cannot infer from a repository.

Review is only half of it, and the smaller half. Describing the capabilities is the work. Advocating the automation of them is the job with no other home. A delivery team optimises its own loop; a product owner optimises their product. Neither has the sightline or the mandate for a capability that spans HR, Finance and IT, and neither gets thanked for building a gate that mostly pays off for another team. The opportunity is only visible from the layer that holds the model, which makes enterprise architecture the natural advocate for AI and automated workflow rather than its reviewer of last resort.

What teams wanted from enterprise architecture was coherence and reuse, not another control point. That critique is not mine and it is not new: Ryan Pehrson, who led enterprise architecture at Takeda, calls an EA function that primarily controls technology decisions through centralised review boards cosplay Enterprise Architecture. The difference between a board and a review is what it is held against.

Boards decide on behalf of a team, from a document their build never consulted, while a review asks the team the two questions and leaves the decision with the people who have to run the thing. A capability map that no build consults is a wall chart - capabilities without constraints, and the constraints are what a gate could have failed on. Point agents at it and you get the wall chart's opinion, drift and all. An asset with no owner does not merely decay. It gets rebuilt by whoever arrives next and cannot read it, and at this level that is a reorganisation.

Pick a seam and measure it

Catalogue the agreements you have between teams. Every one of them is a seam, and most of them are assumed rather than agreed, which is what makes the exercise worth doing.

You will not find nothing. You will find an SDLC document written once to clear a stage gate and never versioned against the running system, a release runbook describing a process the deploy stopped following two years ago, ClickOps calling itself continuous delivery with the deployment decision held as muscle memory in a console, and at best a Confluence page with an author and no test. A decision that outlasts the people who made it is owned, versioned and testable - that is what statute, building codes and IETF RFCs have in common. Every artefact on that list fails at least one of the three, and most fail all three. It is not that the organisation has no specs. It is specs with the load-bearing parts taken out.

I would start with a low-risk IT governance process: how those processes operate, and how they support the deployment process. That is where the evidence and the decision points already are, and it is the part of the organisation with the most ceremony per unit of delivered change. Regulated shops are the interesting case, because they do have a forcing function and still mostly produce evidence rather than executable constraints. Ceremony is not the constraint.

Take the change review board. A delivery team arrives with a release and the compliance evidence the organisation demands. Which evidence, exactly? The requirement is real, and it is rarely written down anywhere a gate could check it, so the team infers it from whichever board went badly last. The reviewers have minimal context about the solution - that is what makes it a board rather than a review - so what they can evidence is that the paperwork exists and the process was followed, not that the change is safe. Both sides are behaving rationally. The definition of good was never written down at a layer above either of them, and holding it was never in anyone's job description.

Then ask who owns the cadence. The board sits when the board sits and the change waits, which makes the release schedule an artefact of the reviewers' calendar rather than of the risk in the change. That held while releases were monthly and human.

It does not scale, and the question answers itself. A serialised human review sized for a release train cannot absorb what an estate of agents produces. You can convene more boards and multiply the inconsistency, or you can write down once what the evidence is actually for and let the pipeline produce it every time. That is a gate with an owner, at the altitude the constraint binds. It is the spec harness argument again, run where it belongs.

So what does that gate actually check? Not whether the change is safe - that is a judgment, and a gate that needs one is a board with better tooling. It checks what is decidable: that the change declares a risk class, that the class has a written evidence requirement, that the evidence came from the pipeline which built the artefact rather than a form filled in afterwards, that it is newer than the change it covers, that the capability being touched exists in the model with an owner's name against it, and - where an agent made the change - that it fell inside the scope that agent was declared to hold. What it cannot decide it routes to the named owner with the context attached. That is a smaller and rarer question than the one a board answers monthly about everything.

The plumbing is unremarkable and most of it is already in your estate: policy as code, signed provenance from the build, a registry the declarations resolve against. The failure mode is not technical either. It is a gate that checks the document exists rather than that the claim is true - the change review board reproduced in YAML, running at higher throughput, with the accountability diffused into a pipeline that has no owner. Automating the ceremony is easier than writing down the constraint, and on a slide the two look identical.

Then borrow Giles Edwards-Alexander's method rather than his number. He ran the same feature change either side of 15 structural steps and measured what the structure was worth; the unit was input tokens because the subject was a codebase. At this scale the decision is an organisational one - a handoff added, an approval removed, a seam written down rather than assumed - and the unit is elapsed time and rework. Ceremony per unit of delivered change is a number, and a number takes a baseline. Do that and your organisational structure stops being the opinion of whoever is most senior in the room. It becomes a line item too.

None of this is an argument for waiting. It is an argument for order, and for ownership. Write down what the organisation does and who holds it - which capability each team or agent fulfils, and how that function has to operate - make it something a gate can check, give it an owner, delegate against it and measure the feedback. Start where the names already are: the job descriptions. Reverse the order and you are generating a ball of mud at the scale of the organisation, faster than anyone can review it. Good structure gets faster. Bad structure gets faster too, because AI amplifies the architecture it finds.

Write the seams down before the agents start guessing at them.

References & further reading

← All writing