Intent architecture: from company purpose to one line of code

Most architecture damage is not done by a bad architect. It is done by a reasonable change, made by someone who could not see the rule it broke. A developer closes a ticket by calling a service directly because it is quicker. A new field is logged because it helps with debugging. A retry is added because a call sometimes times out. Each change is sensible locally. Together, over a year, they weaken a product rule, a domain boundary or a security control that nobody on the ticket knew existed.

Coding agents make this sharper. An agent is extremely good at optimising the task in front of it, and it has no way of knowing about a rule it was never shown. It will not hesitate at a boundary it cannot see. So the question for any team using agents at scale is not only “is the spec good?” but “does the person or agent doing this piece of work receive the parts of the organisation’s intent that apply to it?”

That is what this part calls intent architecture: organising purpose, principles, rules, decisions and contracts so they flow down to local work. It is an emerging umbrella term rather than a governed standard or a product you buy. Think of it as a way of arranging context, not a new tool.

We are following one fictional organisation through this series. Kestrel Mutual is fictional, and all figures are illustrative. Kestrel is a mid-sized South African insurer building assisted account recovery (SPEC-017): a way for customers who have lost access to their registered mobile number to get back into the portal without making SIM-swap account takeover easier. Part 3 took that specification apart section by section.

A chain from purpose to runtime evidence

Intent does not start in a feature spec. It starts with why the organisation exists and what it has promised customers, and it ends with evidence from production that the promise is being kept. In between sit several layers, each more specific than the last:

1. Business intent and outcomes. What the organisation is trying to achieve.
2. Product principles and domain rules. How the product behaves and what the business means by its words.
3. Architecture boundaries and decisions. How the system must hold together.
4. The feature specification. What behaviour changes now.
5. Contracts and acceptance tests. The precise, checkable shape of that behaviour.
6. Code and configuration. The implementation.
7. Runtime evidence. What actually happens in production, which feeds back into the business intent at the top.

That last step matters. Without it the chain is a one-way broadcast, and the organisation never learns that a rule written three years ago no longer matches reality.

Intent layers change at different speeds

The most useful thing to notice about these layers is that they change at very different rates. Kestrel’s layers for assisted recovery look like this:

“Controlled” deserves a word. A contract is the agreed shape of what one part of the system sends to another: field names, types, allowed values, error codes. It does not change slowly or quickly; it changes by agreement, with a version number, because other teams depend on it. Kestrel’s portal team cannot simply rename a field in RecoveryDecision on a Tuesday afternoon, however convenient that would be.

Change rate tells you where to put effort. Slow layers deserve careful wording and named owners, because they are inherited by everything beneath them for years. Fast layers should be cheap to write and cheap to throw away. A team that spends a week polishing a task description and ten minutes on its architecture principles has the effort upside down.

An agent needs the slice, not the strategy

An agent working on TASK-017-04, the adapter that creates a fraud case when a high-risk recovery attempt is blocked, does not need Kestrel’s five-year strategy. It does not need the claims domain glossary, the brand guidelines or the rules for premium collections. Loading all of that wastes the agent’s attention and invites it to “improve” things it was never asked to touch.

What it does need is a precise, inherited slice:

• from global policy: personal information must not be written to logs, and secrets never live in source code;
• from the domain: what Kestrel means by a recovery attempt, an assurance level and a case, and the rule that high-risk attempts never reset automatically;
• from the repository: where adapters live, the boundary set by ADR-024, and the command that runs the tests;
• from the feature: the high-risk scenario in SPEC-017 and the requirement that every attempt records a correlation ID, outcome and policy version;
• from the task itself: the exact change, which is to map a blocked RecoveryDecision onto the case management system’s case format.

This is the balance every team has to find. Too little context causes drift: the agent does not know that personal information cannot be logged, so it logs the customer’s ID number to help debugging. Too much context causes noise: the agent reads everything, loses the three sentences that matter among three hundred that do not, and starts making unrelated changes.

Context inheritance in practice

Nothing about this requires special tooling. It requires putting intent where people and agents will find it, and linking the layers so each one points to the next.

A layered model works well:

• Global: security, quality and engineering policy that applies to every repository.
• Domain: the language, boundaries and rules of one business area, such as identity or claims.
• Repository: the architecture, conventions and commands for one codebase.
• Feature: the behaviour and acceptance criteria for one change.
• Task: the exact local change.

Each layer should inherit only the relevant constraints from the layer above, by reference rather than by copying. A feature spec that links to ADR-024 stays correct when the ADR is updated. A feature spec that pastes a paragraph from it becomes quietly wrong the day the decision changes.

Here is how Kestrel lays out the identity repository:

/docs
  /intent
    product-principles.md
    domain-glossary.md
  /architecture
    context.md
    boundaries.md
    /adr
      ADR-024-identity-decisions-stay-in-identity-domain.md
  /specs
    /assisted-recovery
      spec.md
      design.md
      tasks.md
      /acceptance
/src
/tests
/ops
  service-levels.md
  /runbooks
AGENTS.md

A few terms. An ADR, or architecture decision record, is a short document recording one significant design decision, the options considered and the consequences accepted. AGENTS.md is a plain text file of instructions for coding agents: how to build and test, where things live, what not to touch. Many coding agents read a file like this at the start of a task, and Part 5 looks at how to keep it short and useful. The /ops folder holds service levels, the reliability targets the service is run against, and runbooks, the step-by-step guides for handling incidents.

The point of the layout is not the folder names. It is that the product principles, the domain glossary, the architecture decisions, the feature spec and the operational targets all live in version control next to the code, where a reviewer, a new engineer and an agent can all reach them. That is the same idea as the constitution in our write-up of spec-driven development on a real delivery: guardrails survive a handover only when they are artefacts, not intentions.

A feature spec is not an ADR

Teams new to spec-driven development often bury durable decisions inside feature work. It is worth being strict about the difference.

A feature spec describes desired behaviour for a change. SPEC-017 says what a customer can do, which evidence counts, what happens on a high-risk attempt and how success is measured. Parts of it will be revised as the journey evolves.

An ADR preserves a significant design decision that outlives the feature. ADR-024 says identity decisions remain in the identity domain, so the portal never decides assurance for itself. That decision was taken during assisted recovery, but it will govern the next five identity features too.

If ADR-024 had lived only in tasks.md, it would have been archived with the tasks when the feature shipped. The next team, or the next agent, would never have seen it, and the portal would eventually have grown its own little assurance check “just for this one screen”. Do not bury durable architecture inside a temporary task list.

Two kinds of drift

When people say a system has “drifted”, they usually mean one of two quite different things, and the fixes are different.

Implementation drift is when the code no longer satisfies the approved spec. At Kestrel, SPEC-017 blocks banking-detail changes for 72 hours after a successful recovery. Suppose an engineer, or an agent, codes the cooling-off period as 48 hours. The spec is right; the code is wrong.

Intent drift is when the spec no longer represents business or architecture reality. Suppose Kestrel’s fraud operations team decides that any recovery attempt made within 30 days of a change to the customer’s email address must always go to human review, because that pattern is showing up in fraud cases. They brief the contact centre. Nobody updates SPEC-017. The code faithfully implements the spec, the tests pass, and the system is still wrong.

Tests help with the first kind. A test that checks the cooling-off period fails the moment someone codes 48 hours. Contract checks and review against the spec catch more of it.

Tests cannot catch the second kind, because they were written from the same out-of-date spec. Intent drift is caught by people and by production: a product owner who treats the spec as a live asset and updates it when policy changes, architecture governance that notices when a new decision contradicts an old ADR, and runtime learning, where production evidence is actually read. If Kestrel’s dashboards show a rising share of recovery attempts that pass every automated check and are later reported as fraud, that is intent drift announcing itself.

This distinction matters for anyone thinking agents will “keep the spec and code in sync”. An agent can help detect implementation drift by comparing code against the spec. Only the people who own the business can detect intent drift, because it lives outside the repository. Our article on technology homeostasis looks at the same problem from the other side: systems stay healthy through continuous small corrections, not occasional rescues.

Why this matters in a South African organisation

Many South African enterprises carry the same pattern: a core system that is decades old, rules that live in the heads of a few long-serving specialists, and regulatory obligations such as POPIA’s requirement for appropriate security safeguards over personal information. When those specialists move on or retire, the intent leaves with them. An agent pointed at that codebase inherits the code without the reasons.

Intent architecture is partly a knowledge-preservation exercise. Writing the glossary, the rules and the boundary decisions down is the work that lets a new engineer, a partner team or a coding agent change the system safely. It is also, not by accident, much of the evidence an auditor or regulator will ask for.

What to take from this part

Intent flows down in layers that change at different speeds. Put careful wording and named owners on the slow layers, and keep the fast layers cheap.

Give each task the relevant slice, not everything. Too little context causes drift; too much causes noise and unrelated changes.

Link the layers rather than copying them. A reference to an ADR stays correct; a pasted paragraph goes stale.

Keep durable decisions in ADRs, not task lists. Tasks are archived; decisions have to outlive the feature.

Tell the two kinds of drift apart. Tests catch implementation drift; product ownership, architecture governance and production evidence catch intent drift.

Next in the series: Harness engineering: the workshop around the agent.

How CloudNala can help

We help teams map the intent layers for a product area: finding the principles, rules and decisions that currently live in people’s heads, writing the few that matter as short, owned artefacts, and arranging the repository so each piece of work, human or agent, receives the slice it needs. The aim is a small, linked set of documents a team will keep current, not a new library of templates.

Work with CloudNala

CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.

Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.

Plan an SDD Pilot or write to us at consult@cloudnala.co.za