1. What AI is good at

AI is a master of abstraction. Give it a description and it can turn that description into types, functions, interfaces and layers. Ask for another capability and it can extend the model, introduce another component and connect the pieces. We can now delegate much of the work of expressing an idea in code.

That changes an important constraint. When humans wrote the implementation, constructing each abstraction took their attention and effort. With AI, we can ask for a design and receive the implementation without making every construction decision ourselves. Those decisions still exist. They are being made while the agent works.

The ability to produce an abstraction does not settle whether the system needs it. This is where the strength becomes an engineering problem.

2. Where it gets out of hand

A request leaves room for choices. The agent might extend an existing operation, introduce a new service, generalise a concrete type or add a configuration layer. Several choices may satisfy the immediate request. Without an explicit construction model, the request also becomes an invitation to decide how the codebase should be organised.

Consider a small, hypothetical sequence: one change adds a helper, another wraps it in a service, and a third introduces a factory to select between implementations. Each step can be explained by the request in front of the agent. Together, they establish an architecture that the human never deliberately selected. Subsequent changes inherit those choices.

Locally plausible decisions accumulate. The code may work while the human loses a clear account of where a change belongs, what it will affect and why the surrounding machinery exists. Asking AI to simplify it can open another round of architectural choices unless simplification has a defined target.

This problem has a concrete counterpart in Anthropic's prompting guidance: it identifies unnecessary abstractions and unrequested flexibility as overengineering tendencies in Claude Opus 4.5 and 4.6. The issue here is how to constrain such construction across successive changes.

3. What humans are doing now

Software engineering developed ways for people to work within human limits. Abstractions let a person reason about a smaller part. Team boundaries divided responsibility. Plans and reviews helped people coordinate decisions and inspect one another's work.

We can carry that organisation into AI work: assign architect, developer and reviewer roles, pass a plan between them, then ask the human to inspect the result. But assigning those roles leaves open the constructions each agent may introduce. A more elaborate workflow can still produce a codebase whose organisation is being decided afresh with each task.

In her trials of specification-driven tools, Birgitta Böckeler describes verbose, repetitive documents and an agent regenerating classes already described as existing. She questions whether the tools reproduce existing workflows too literally. Her account gives a specific instance of the process problem: more material to review can coexist with unresolved control over construction.

The question becomes what the codebase itself must make explicit, so that keeping it coherent does not depend on a human rediscovering every structural decision in every review.

We need to give the agent a stable answer to a question that survives the current task: what forms may it use to build this system?

4. Define the domain before construction

A construction model tells the agent where a type belongs. The domain model tells it what that type means. Without that meaning, the agent can put every declaration in the right file and still build the wrong system. The definitions need a durable home beside the code, so each change starts from the same model.

This is domain-driven design. Scott Wlaschin's Domain Modeling Made Functional starts with a shared model developed with domain experts: the language they use, the events and workflows they describe, and the boundaries within which those meanings apply. Types express that model, and small functions compose into workflows. The implementation follows the domain's distinctions and decisions.

His Designing with Types practices make that concrete: give meaningful values distinct types, represent alternatives and states explicitly, and make invalid combinations impossible to construct where the type system permits it. A customer identifier and an email address may both be stored as strings, but they play different roles. A verified address carries a fact that an arbitrary string does not.

I use four documents to carry those decisions into agent construction:

DocumentWhat it establishesWhy the agent needs it
PROFILE.mdDomain vocabulary, objects, relationships, operations, domain laws and boundariesA shared meaning for the types and transformations it constructs
INVARIANTS.mdConstruction shapes, type ownership, permitted dependencies and verification obligationsRules for realising that model, with recognisable violations and corresponding checks
specifications/INTENT.mdDomain requirements: this system's purpose, scope, decision rules and required behaviour, including examplesA basis for deciding whether a structurally valid implementation does the required job
AGENTS.mdThe entry point that directs the agent to load the profile and invariants, then follow the working procedureDomain context and construction rules established before it plans or changes code

AGENTS.md is the entry point when an agent starts working in the repository. I link PROFILE.md and INVARIANTS.md from it and instruct the agent to read them at the beginning. This establishes the context within which it should think and operate: what the domain means, which constructions are permitted and what must hold as it changes the system.

INTENT.md describes the system we are building in domain language. For a trading engine, it sets out the strategies, decisions, risk limits and required behaviour; implementation design is developed in separate engineering specifications.

These filenames are my way of organising the definitions. The approach draws on Wlaschin's domain modelling practices: discover the meaning, express it in types and operations, and preserve it through implementation.

For example, suppose the domain permits password resets only through verified email addresses. PROFILE.md defines what verification means and the distinction between unverified and verified addresses. Intent states what a reset request must do in each case. The code expresses the states with distinct types and gives the reset operation a verified address as its input. This follows Wlaschin's example of making email-verification state explicit. Verification has to be established by the required process; renaming an unchecked string does not establish it.

The construction rules then give those types and operations their homes. AGENTS.md directs the agent to use the existing definitions and resolve a missing policy with the human. The same domain terms should appear in the documents, type names, function signatures and behavioural examples, so a changed decision has a traceable consequence in code.

That is why the documents are necessary. The codebase needs a current account of the decisions construction must preserve. Keep it small and revise it with the system: establish the meanings and behaviour the next change needs, express them in code, and check that they agree. This gives successive changes a common basis without generating a new stack of plans for every task.

5. Rethink the codebase

Shape is the observable structure of the code: what a declaration contains, what a function receives and returns, which operations its body performs, and what it depends on. A construction model gives those structures permitted forms and homes.

We choose an explicit shape because it gives automated control something concrete to inspect. Once a declaration has a permitted home and an operation has a defined boundary, a detector can identify a departure and report the rule it violates. Hooks can bring that finding into the agent's work as it happens.

A module called “service” can contain data, calculations, network calls and orchestration. The name alone settles little. Here is the shape I propose, with the definitions beside a small Python package:

A defined repository

Repository tree with root definitions, agent hooks, shared construction checks and eight implementation categories.

repository/

  • .claude/
    • hooks/
    • settings.json
  • .codex/
    • hooks/
    • hooks.json
  • specifications/
    • INTENT.md
  • src/
    • application/
      • constants.py
      • effects.py
      • enums.py
      • morphisms.py
      • objects.py
      • pipelines.py
      • primitives.py
      • runtime.py
  • tools/
    • lint/
      • enforce.py
  • .pre-commit-config.yaml
  • AGENTS.md # Read PROFILE.md and INVARIANTS.md at startup
  • INVARIANTS.md
  • PROFILE.md
repository/
├── PROFILE.md
├── INVARIANTS.md
├── AGENTS.md
├── .claude/
│   ├── settings.json       # Claude hook registrations
│   └── hooks/              # Claude event adapters
├── .codex/
│   ├── hooks.json          # Codex hook registrations
│   └── hooks/              # Codex event adapters
├── .pre-commit-config.yaml # Git commit checks
├── tools/
│   └── lint/
│       └── enforce.py      # Shared construction-check entry point
├── specifications/
│   └── INTENT.md
└── src/
    └── application/
        ├── constants.py    # Fixed, typed, immutable values
        ├── primitives.py   # Distinct scalar types: identifiers, quantities, flags
        ├── enums.py        # Closed sets of named alternatives
        ├── objects.py      # Immutable records, unions, collections and capability types
        ├── morphisms.py    # Individual pure calculations, transformations and predicates
        ├── pipelines.py    # Named compositions of existing pure operations
        ├── effects.py      # Functions that read or change the external world
        └── runtime.py      # Configuration selection, capability assembly and lifecycle
The definitions, construction rules and implementation live together in one repository.

Each home has a permitted construction. A record in objects.py contains declared data; it has no operational methods. Scalar types originate in primitives.py, enums in enums.py, and compound types in objects.py. Functions use those declared types in their signatures. A function cannot introduce its own inline dict[str, Any] representation; that structure needs an explicit declaration in its type-owning home.

The profile determines the domain names and distinctions inside those homes. A verified-address type belongs in objects.py, its pure validation and transition operations in morphisms.py, and the external act of sending a message in effects.py. In this Python binding, type annotations need static checking, and boundary validation must establish the facts the types represent. The folder layout alone cannot do that work.

morphisms.py owns individual pure operations. They receive the values they need and return their results. pipelines.py composes those operations; a new calculation gets its own morphism. effects.py owns file, network, database and environment access. runtime.py supplies the concrete capabilities and manages their lifetime. The outside world is what effects interact with; it needs no code directory.

The dependencies follow those responsibilities. Morphisms and pipelines may use the declared types, constants and pure operations, but cannot import effects or runtime. Effects can use pure operations and declarations, but cannot depend on runtime. Runtime assembles the required parts. A calculation that needs a stored value receives it as an input; the database read belongs in effects.

A small vocabulary of construction

Eight construction forms grouped from values and types through pure operations, external interaction and runtime assembly.

Values and types

  1. constants # Fixed, typed, immutable values

  2. primitives # Distinct scalar types: identifiers, quantities, flags

  3. enums # Closed sets of named alternatives

  4. objects # Immutable records, unions, collections and capability types

Pure operations

  1. morphisms # Individual pure calculations, transformations and predicates

  2. pipelines # Named compositions of existing pure operations

External interaction

  1. effects # Functions that read or change the external world

Assembly

  1. runtime # Configuration selection, capability assembly and lifecycle

A small set of forms carries a growing domain.

The same model applies as the codebase grows. morphisms.py can become morphisms/, with modules such as validation.py and calculations.py. Every module inside still contains individual pure operations. The other categories can grow in the same way. New domain operations use the existing forms. A genuinely new construction requires a deliberate change to the model, rather than arriving unnoticed inside a feature.

The categories also give existing code a target for simplification. Separate a mixed module's data, calculations and external interactions into their declared homes. Use the categories the change actually needs; a pure calculation needs no external-interaction layer. Adding a capability should extend the domain through the model, rather than require another stack of wrappers.

This is the proposed simplification: the domain can grow while the vocabulary of construction stays small. AI can express more behaviour through the same few forms, with fewer opportunities to invent another organisation for it.

6. Build the control panel

This is what the new shape makes possible: a control panel for agent construction. We define the permitted forms, build detectors for their violations, and connect those detectors to stages of the agent's work. A departure becomes feedback the agent can act on while the change is still being built.

Claude Code and Codex provide hooks at session start, before tool use, after tool use and when the agent attempts to finish. Each stage gives us a different point of intervention:

StageWhat the control can do
SessionStartEstablish the engineering standard and working context before construction begins
PreToolUseInspect a matched tool call and deny a prohibited operation before it runs
PostToolUseInspect the result of a matched edit and return violations for correction; the edit has already happened
StopCheck the accumulated changes and completion evidence, returning unresolved findings to the agent
Git pre-commitRun the configured checks on the proposed commit and fail it while blocking findings remain

I use SessionStart to set the engineering standard before the first edit. My startup hook states: “Classify declarations and behavior before mutation.” That is the starting point for functional construction: decide whether something is data, a pure operation, a composition or an external interaction, then use its permitted shape. AGENTS.md connects the agent to the full definitions; the startup hook brings the standard into the session before work begins.

I use the hooks to keep the agent within the decisions we have made. Before an action, they reject attempts to bypass checks or erase existing work. After an edit, they check declaration placement, dependency direction and the separation of pure calculations from external interactions. Before the agent finishes, they inspect the combined change and require current verification evidence for a claim that a defect is fixed. Pre-commit applies the construction and verification gates to the code being committed. The agent receives a concrete obligation: correct the named violation while preserving the intended behaviour.

The agent corrects its construction

Agent construction with startup context, action and edit checks, a correction loop, and separate completion and commit gates.

SessionStart

Set the engineering standard

PreToolUse

Check the proposed action

Rejected actions do not run. A rejection goes to Finding.

Agent work

Construct within the defined shape

PostToolUse

Check the changed construction

The edit has already happened. No findings: continue work.

↓ On a violation from either check

Finding

Name the violation

Correction

Correct the named violation

Return to PreToolUse and recheck the correction.

Stop

Check combined changes and completion evidence

When the agent attempts to finish. Unresolved findings return to the correction loop.

Git pre-commit

Check the proposed commit

Whenever a commit is attempted. Blocking findings return to the correction loop.

Set the standard. Check each change. Return violations to the agent for correction.

Suppose the agent adds this declaration to morphisms.py:

morphisms.py

class RunMode(Enum):
    TEST = "test"
    LIVE = "live"

Its declaration identifies it as an enum. Its permitted home is enums.py. The correction is precise: move RunMode there and import it into the operation that uses it. Importing an enum into morphisms is permitted; declaring one there violates the shape, even if the application and its tests still work.

A method that reads the environment inside a record in objects.py also violates the shape. A database call inside a morphism crosses the pure boundary. The same construction contract identifies each departure.

These rules give the agent a specific target for repair. Move the external read to its permitted home, pass the resulting value to the operation, then check the affected construction again. The correction follows from the model instead of depending on a fresh instruction to “use better architecture”.

A useful diagnostic names the declaration or operation, the rule it violates and the correction required. The agent can then repair a local departure while preserving the behaviour the change was meant to deliver. A new abstraction is judged against the same model as the code it replaces.

The implementation already has detectors for declaration placement, dependency direction and forbidden I/O imports in pure layers. An import check can report PURE-NO-IO with the file, line and imported module. The hook returns that finding to the agent; the agent applies the correction and reruns the affected check. The same detector remains available at completion and commit.

Some properties can be checked directly from declarations and imports. Others need analysis of the function body or of the operations it calls; a filename alone cannot establish purity. Choose rules precise enough to inspect, and make the available checks correspond to them.

The timing matters. An edit hook gives feedback close to the construction that caused it. A stop hook can inspect the combined changes before the agent declares completion. Pre-commit checks the staged version as another gate, including changes made outside the matched agent tools. In this implementation, pre-commit also runs registered type checks, lint validation and tests for the hooks and controls when their matching files change.

A rule written in an instruction file still depends on the agent following it. A detector attached to these stages makes a departure observable and brings it back as a correction obligation. The control panel works because the shape makes those obligations precise.

Shape gives structural control a repeatable basis. Behaviour still has to be evaluated against the system's purpose: a calculation can occupy the correct home and calculate the wrong thing. That evaluation has a clearer object when the calculation is explicit, its inputs are visible and its external interactions are separated.

7. A different engineering practice

The human's work shifts towards defining the system: its purpose, meanings, intended behaviour and the forms through which it may be constructed. AI can help expose gaps and explore choices, then implement within those decisions. The human can revise the model when the system genuinely needs another form.

For the next change, identify the behaviour that must change and the constructions it touches. Update the relevant domain definitions and intent when a decision changes, keeping the construction rules and agent procedure current. The agent can add or update the relevant data and operations, connect the required interactions and check the result. When it encounters a structural violation, the model supplies the correction. When the requested behaviour exposes a missing domain decision, that decision comes back to the human.

Massive simplification means reducing the decisions that must be reopened for each change. The construction model is established once and kept current; a new request develops the system within it. Hooks return structural departures to the agent during construction, and pre-commit checks them again at the commit boundary, leaving the human to judge the decisions and results that require human understanding.

AI is a master of abstraction. We want that ability working within a shape we understand and can enforce. As the system grows, the same few construction rules should still tell us where a change belongs, what it may depend on and how to correct it. That is the basis for engineering when AI writes the code.