AI Coding Agents Need Architecture They Can Read

AI coding agents are getting better at writing code.

That is no longer the interesting question.

The more important question is whether they can work inside your architecture without slowly damaging it.

This week, a useful pattern has been getting attention among developers using Claude Code, Cursor, Codex, and similar tools: keep Architectural Decision Records inside the repository and make agents read them before they change the system.

That sounds small. It is not.

It points to a larger shift in AI-supported software development. The best teams will not be the ones that simply give agents longer prompts. They will be the ones that turn their architectural judgement into project infrastructure: decision records, repo instructions, tests, lint rules, security checks, and review habits that agents can follow.

In other words:

AI coding agents need architecture they can read.

The hidden problem with agentic development

Most serious software systems are full of decisions that are not obvious from the code.

Why does this module own customer state?

Why is direct database access forbidden in this part of the application?

Why does billing use a separate event flow?

Why is this integration retried but that one is not?

Why are permissions checked in one layer and not another?

A senior engineer may know the answers. A founder may remember the painful incident that led to the rule. A product owner may understand the operational constraint behind a strange-looking workflow.

But an AI agent sees files.

It can infer patterns, but it does not automatically know which patterns are intentional, which are legacy accidents, and which are dangerous shortcuts. If the project context is mostly stored in people’s heads, the agent will fill the gaps with plausible guesses.

That is where teams get into trouble.

The code still compiles. The feature demo may work. The diff may even look tidy. But a boundary has shifted. A security rule has been bypassed. A data model has been duplicated. A shortcut has become a precedent.

The risk is not that agents write bad code every time. The risk is that they write reasonable code against an incomplete understanding of the system.

Prompts are not enough

It is tempting to solve this with better prompting.

Tell the agent to be careful. Tell it to act like a senior engineer. Tell it to follow best practices. Tell it to think about security, maintainability, and scalability.

That helps, but only at the surface.

Generic instructions cannot replace project-specific decisions. “Write maintainable code” does not tell an agent which service owns a workflow. “Be secure” does not tell it where tenant scoping must be enforced. “Follow the architecture” is useless if the architecture is not written down in a place the agent actually reads.

This is why repository-level context matters.

Many teams already use files such as AGENTS.md, CLAUDE.md, CONTRIBUTING.md, or internal engineering guides. Those files give tools and developers a starting point. But for architecture, a single instruction file is often too broad. It becomes either vague or so long that nobody maintains it.

Architectural Decision Records solve a different problem.

They capture specific decisions:

• the context that led to the decision;
• the decision itself;
• the consequences and trade-offs;
• the code areas affected;
• the checks or review rules that protect it.

That is exactly the kind of durable context an agent needs.

ADRs become memory for the codebase

An Architectural Decision Record is usually short. It does not need to be a grand architecture document. A useful ADR might answer one question:

Should this product allow direct database calls from feature code?

Should invoices be generated synchronously or through an event queue?

Should tenant access be enforced by the database layer, the service layer, or both?

Should AI-generated suggestions be stored, audited, or discarded?

Should a module expose a public API, or should it remain internal?

These decisions may look boring. They are not. They are the shape of the system.

When ADRs live inside the repository, an AI coding agent can read them before making a change. That means the agent is not only reacting to current files. It is working with the team’s recorded reasoning.

This changes the collaboration model.

Instead of repeatedly telling the agent “never call the database directly from this package,” the team can record the rule once, link it to the relevant modules, and enforce it where possible.

Instead of relying on a senior developer to catch the same architectural drift in every review, the team can make the decision visible before the diff exists.

Instead of treating each agent session as a fresh conversation, the repository carries memory forward.

That matters because AI-assisted development creates more implementation throughput. More throughput means more decisions become embodied in code faster. If those decisions are not guided, reviewed, and recorded, the codebase can drift more quickly than before.

The best records are enforceable

Documentation helps. Enforcement helps more.

The most useful pattern is not only “write ADRs.” It is “connect ADRs to checks.”

For example:

• An ADR says all tenant-scoped queries must go through a specific access layer.
• A lint rule flags direct imports from the database client in feature modules.
• Tests cover tenant isolation behaviour.
• Pull request review checks for changes that cross the boundary.
• The agent instruction file tells coding agents to read the ADR before touching data access code.

Now the decision exists in four forms:

• human-readable reasoning;
• agent-readable context;
• automated enforcement;
• review expectation.

That is much stronger than a paragraph in a wiki.

Not every decision needs this treatment. If teams try to enforce everything, the system becomes heavy and people route around it. The trick is to protect decisions that would be expensive, risky, or embarrassing to get wrong.

Good candidates include:

• authentication and authorization boundaries;
• tenant isolation;
• data ownership;
• payment and billing flows;
• audit logging;
• integration contracts;
• personally identifiable information;
• deployment and rollback rules;
• module ownership;
• API compatibility guarantees.

These are the areas where “the agent probably understands it” is not a satisfying answer.

This is especially relevant for founders and Mittelstand teams

For many founders, the promise of AI coding tools is speed. Build the MVP faster. Add features faster. Reduce dependency on scarce engineering capacity.

That promise is real, but incomplete.

If a product is still experimental, a fast prototype can be valuable. But once customers depend on the software, speed needs a control system. The product needs stable architecture, sensible operations, and clear ownership.

For Mittelstand and established teams, the issue is even sharper. Existing systems often contain years of implicit business knowledge. Pricing exceptions, customer-specific workflows, regulatory constraints, manual operations, and integration quirks are scattered across code, spreadsheets, tickets, and people’s memories.

AI agents can help modernise those systems, but only if the system becomes legible.

That does not mean writing a 100-page architecture manual. It means creating enough structured context that both humans and agents can understand what must not break.

At McDougall Digital, this is where architecture-first delivery becomes practical rather than theoretical. Before using AI to accelerate implementation, we want to know which decisions matter, where the risky boundaries are, and which rules should be automated. Otherwise AI simply helps a team create more code around unresolved ambiguity.

What agent-readable architecture looks like

An agent-readable architecture layer does not need to be complicated.

A healthy starting point could look like this:

1. A short repo-level instruction file

This tells agents how to behave in the project. It can include the tech stack, commands, review expectations, forbidden shortcuts, and where to find architecture notes.

For example:

“Before changing authentication, billing, tenant data, or integrations, read the relevant ADRs in docs/adr/.”

2. A small ADR folder

Start with the decisions that repeatedly come up in development or reviews. Do not document everything. Document what changes behaviour.

Each ADR can be simple:

• title;
• date;
• status;
• context;
• decision;
• consequences;
• affected files or modules;
• enforcement or review notes.

3. A test and check map

For each critical decision, identify the check that protects it.

Some decisions are protected by unit tests. Some by integration tests. Some by lint rules. Some by code review. Some by monitoring.

The point is not that every rule must be automated immediately. The point is that the team knows which decisions are currently protected by machines and which still depend on human review.

4. Clear module boundaries

Agents perform better when boundaries are visible. Folder names, public APIs, import rules, and ownership notes all help.

If a module is internal, say so. If a service is the only allowed way to mutate customer data, make that visible. If two domains must not depend on each other, encode that through import rules or architecture tests.

5. A habit of updating decisions

Architecture changes. Good teams do not freeze decisions forever. They update the record when reality changes.

This is important with AI agents because the agent can help maintain the documentation. At the end of a feature, the team can ask:

“Did this change introduce a new architectural decision or modify an existing one?”

If yes, update the ADR as part of the work.

What not to do

There are a few traps.

The first is turning ADRs into bureaucracy. If every small implementation detail becomes a decision record, nobody will read them. The records should cover meaningful choices, not personal preferences.

The second is writing documents that are not connected to the code. If an ADR says “use the central permissions layer” but nothing in the repository reinforces that rule, it will eventually be ignored. At minimum, link the ADR to the relevant files and review checklist. For critical rules, add automated checks.

The third is assuming agents will always read everything. They will not unless the workflow makes it easy and explicit. Repo instructions, prompt templates, and tool configuration should point agents to the right records before work begins.

The fourth is using ADRs to justify decisions nobody believes in anymore. A stale record can be worse than no record because it gives agents false confidence. Keep status labels clear: proposed, accepted, superseded, deprecated.

The fifth is treating architecture as a one-time setup task. Agent-readable architecture is an operating habit. It improves as the team learns where agents make mistakes, where reviews slow down, and which rules deserve stronger enforcement.

A practical first week

If your team is already using AI coding tools, you do not need a large programme to begin.

In the first week, do this:

1. Create a repo-level instruction file for agents.

Keep it short. Include commands, coding standards, forbidden shortcuts, and links to architecture notes.

2. Write five ADRs.

Choose decisions that matter today. For many SaaS and internal-tool teams, that might be authentication, tenant scoping, data ownership, billing changes, and deployment rollback.

3. Add one enforceable rule.

Pick a decision that is easy to check automatically. Maybe direct database imports are forbidden outside a data-access package. Maybe UI components cannot call an external API directly. Maybe production secrets cannot appear in local config files.

4. Ask the agent to use the records.

Run a real task and explicitly tell the agent to read the relevant ADR before proposing an implementation. Watch where it still misunderstands the system. That tells you what context is missing.

5. Review the review.

After the pull request, ask what the human reviewer had to explain that should have been in the repository. Turn the best of that into an ADR, test, lint rule, or instruction.

This is not glamorous work. It is exactly the kind of work that makes AI adoption serious.

The business case

The business value is not “we have ADRs.”

The value is that architecture becomes easier to preserve while the team moves faster.

That can reduce review load. It can make onboarding easier. It can make agent output more reliable. It can protect security decisions. It can help a founder or CTO sleep better when more code is being generated by tools that do not share the company’s memory.

It also creates a better foundation for future automation.

Once decisions and checks live in the repository, agents can do more than produce implementation. They can inspect whether a proposed change violates existing architecture. They can update documentation when a decision changes. They can generate tests for a rule that is only manually reviewed today. They can help refactor old code toward explicit boundaries.

That is a much stronger use of AI than asking it to write isolated features faster.

The point is not to slow down AI

Good architecture does not exist to make development slower. It exists to make change safer.

AI coding agents increase the amount of change a team can attempt. That makes architecture more important, not less.

The teams that benefit most from AI-assisted development will not be the ones that let agents roam through a vague codebase and hope for the best. They will be the ones that make the important parts of the system legible, testable, and enforceable.

For McDougall Digital clients, this is often the difference between a useful AI adoption strategy and a pile of impressive demos. We help teams define the architecture, product constraints, and operating rules that make faster implementation worth having.

If you are evaluating AI coding tools, do not only ask which agent writes the best code.

Ask a harder question:

Can your architecture explain itself well enough for an agent to work inside it?

If the answer is no, that is the place to start.