Why Fast Coding Agents Still Need Thoughtful Architecture

Coding agents just shipped a refund-approval endpoint, two migrations, and a PR in the time it took your team to schedule the design meeting. That's not hype — it's a real enable. A model can inspect files, draft an endpoint, change a schema, write tests, and open the PR while you're still arguing about naming. The first wave of teams that wires this in gets weeks of engineering time back per quarter.

Then someone reviews the PR and asks: who can approve a refund? Can the same person create and approve it? What happens when the payment provider is down? Does the audit record survive a schema migration? The PR compiles. The tests pass. The design is missing. Speed didn't make those questions smaller. It just made it easier to skip them.

This is the lesson every coding-agent workflow keeps rediscovering: speed helps only after you define the right boundaries.

The speed is real, and worth using

Coding agents aren't a toy. They do work that used to eat afternoons: scaffold an endpoint, write the boilerplate, generate the test, draft the migration. If you've ever watched Cursor or Claude Code turn a three-file change into one PR, you've seen the loop work.

Concrete plumbing to put one in your editor today:

# Cursor — point at any frontier model via OpenRouter, no extra account
export OPENROUTER_API_KEY=...
# In Cursor Settings → Models, pick a frontier model from the
# OpenRouter catalog (e.g. openrouter/anthropic/...)

# Claude Code — straight from Anthropic
npm i -g @anthropic-ai/claude-code
claude
# /model <frontier-model-id>

# Or any agent via a flat OpenAI-compatible endpoint
export OPENAI_BASE_URL=
export OPENAI_API_KEY=...

The point isn't which vendor wins. The point is the loop: read the repo, edit files, run tests, open the PR. That loop is genuinely fast now. Teams that don't use it are leaving time on the table, full stop.

Architecture is the slow part on purpose

The part that doesn't get faster is the one that matters most. Architecture is the set of important decisions that shape a system. Not the folder structure. Not which framework is fashionable this quarter. The decisions:

• which component owns each responsibility
• which component owns each data set
• which dependencies are allowed
• which failure modes the system must tolerate
• which security boundaries the system must enforce
• which parts can change without coordinated work
• which operational costs the team accepts

Each of these is a judgment call that depends on users, regulations, team structure, budget, existing systems, and expected change. None of that lives in the repo. None of it fits in a context window. An agent can implement any of these decisions. It cannot remove the need to make them.

The refund workflow, walked through

A request lands in your tracker: add an approval workflow for customer refunds. Looks like an afternoon. It isn't.

Seven questions hide inside it:

1. Who can approve a refund — role, team, dollar threshold?
2. Does the amount change the rule — manager for $50, director for $500, CFO for $50k?
3. Can the same person create the request and approve it?
4. What happens when the payment provider is unavailable — queue, retry, fail loud, refund anyway?
5. Must the system keep an audit record — of the request, the approval, the reversal, all three?
6. Can an approval expire — and if so, does the customer get re-prompted or silently dropped?
7. Who can read the audit log — and is it the same set who can refund?

A coding agent will guess. It will pick reasonable defaults — a single approved_by column, a boolean flag, a try/catch around the Stripe call. The PR will compile. The tests will pass. Six months later an auditor asks for the trail, and the trail is one nullable column with no actor history. The "fast" decision just cost you a quarter.

This is what the original essay means by an agent can build the wrong system faster than your team can understand it — see Coding Agents Are Fast. Architecture Is Still Slow. Speed without the boundary-setting step is a faster way to ship technical debt.

How to actually use coding agents without shipping the wrong thing

The pattern that works is boring and worth repeating: let the agent own the loop, keep the boundary-setting in human hands. Concretely, a single file in the repo that every agent reads first:

# ARCHITECTURE.md — these rules are not negotiable.

## Money-movement endpoints
- Must write to an append-only `audit_log` table before returning 2xx.
  Schema: `id`, `actor_id`, `action`, `before`, `after`, `occurred_at`.
- No component may both create and approve the same business object.
  Two distinct roles in the auth model, enforced at the endpoint.

## External calls
- Stripe, banks, shipping APIs: wrapped in a retryable, idempotent job.
  The HTTP request returns 202, not 200. The job worker owns the result.

## Schema changes
- Ship in two PRs: the additive one first, the destructive one after
  the new code is live. Never break a read in a single deploy.

Thirty lines. The part that doesn't change when the model does. Read it before the agent runs. Update it when a decision actually changes. Hand it to every new agent the same way.

Three habits that compound:

# 1. Keep the doc in the repo root, not a wiki
ls ./ARCHITECTURE.md   # every agent reads this first

# 2. Block merges on the boundary checks, not just the tests
# (CI rule: every PR touching routes/refunds/* must reference an
#  audit_log write — grep it, fail the build if missing)

# 3. Always run the agent on a feature branch, never on main
git checkout -b feature/refund-approval
claude "implement the refund approval workflow per ARCHITECTURE.md §1"

The speed is still real. The agent still ships the endpoint, the migration, the tests, the PR. The difference is the boundary was set first, so what ships is the system you meant.

The durable layer underneath the agent churn

Here's the part that doesn't change when the model does: the decisions themselves. Which component owns the refund data. Which role can approve. What the audit table looks like. How failure surfaces to the user. These are choices your team will live with for years. The agent — whichever one — will churn. The boundaries shouldn't.

This is also the part that doesn't fit in a prompt. It doesn't fit in a context window. It fits in a codebase that has already made the calls and shipped the conventions: one API surface for the same component on web, iOS, and Android; one auth model that enforces separation of duties at the endpoint; one data layer that owns the audit table by construction. When that baseline exists, every coding agent that runs against it produces code that's consistent with the last six months of decisions — not just the last six minutes of context.

The risk isn't using the agents. The trap is using them against an undefined system — where every PR reinvents the boundary, every endpoint invents its own auth check, every component invents its own data model. That's the technical-debt factory, and it now runs at agent speed.

Set the boundaries once, in a place the agents can read. Let the agents run fast inside them.

What this gets you

A team that uses coding agents well looks like this: the architectural doc lives in the repo, the conventions are baked into the shared component and data layer, and the agent loop runs on top. A refund approval ships in an afternoon, and the audit table is already there because the data layer made it impossible not to be. A new engineer clones the repo on Monday and ships a compliant endpoint on Wednesday, because the boundaries are visible in the code, not tribal knowledge.

That's the enable. Speed at the surface, durable decisions underneath. The model will keep changing. The boundaries shouldn't.