Architecture boundaries for prompt-driven teams that last

Why fast prompt-built code gets messy

Teams often ask an AI coding tool for a feature before they decide where that feature should live. The model does exactly what it was asked to do: it makes the feature work. If nobody has drawn a clear line between data, business rules, and screens, the code spills across all three.

That feels efficient on day one. A prompt like "add account status to the customer page" can change the database, the API response, the page logic, and even billing rules in one pass. The demo works, so nobody stops to ask whether those parts should know about each other.

That is when boundaries start to matter. AI is fast, but it does not protect a line that nobody defined. It will repeat the same assumption in five places if that is the easiest way to finish the task.

The problem gets worse because quick fixes stick. One developer patches an edge case in the screen. Another prompt repeats the rule in an endpoint. A week later, someone updates a report and bakes the same logic in again. Nobody writes down the contract between those parts, so the shortcut becomes the system.

Later, small edits start breaking things that look unrelated. Renaming one field breaks a report, a mobile view, and a background job. Changing a discount rule affects invoices that seemed untouched. Teams often call this random instability. It usually comes from tight coupling created during fast delivery.

A small SaaS team can hit this surprisingly early. They ask AI to add "trial expired" handling. The model updates the user table, login flow, admin page, email copy, and access checks all at once. It ships fast. Then support asks for a two-day grace period, and now the team has to search through half the app to change one idea.

Speed is not the problem. Unmarked boundaries are. When every prompt can edit every layer, the codebase stops acting like a set of parts and starts acting like one large script.

Where boundaries should go first

The first boundary should sit around the part of the product that changes most. Teams often split code into folders like frontend, backend, or utils because it looks tidy. That split usually fails fast. Change does not follow folders. It follows user actions: sign up, pay, cancel, invite, export.

When a team builds through prompts, vague boundaries spread rules everywhere. A signup check ends up inside billing. Reporting recalculates numbers its own way. After a few rushed updates, two prompts can change the same rule and neither one knows the other exists.

Start with business actions, not file names. If a user can finish a real job in one flow, give that flow a clear owner, a small interface, and one place where its rules live. That is usually the most durable cut. The prompt stays focused, and the code picks up fewer surprise dependencies.

Draw the next line where two teams, or even two separate prompts, touch the same rule. If both can edit plan limits, account state, tax logic, or report totals, you already have coupling. Freeze that rule behind one interface early.

For most small products, the first useful boundaries sit around signup and identity, billing and plan changes, reporting and calculations, and notifications and messaging. These areas do different jobs, so they should not quietly borrow each other's rules. Reporting can read billing events, for example, but it should not decide how invoices work. Billing owns that.

This matters even more on a small SaaS team. One prompt ships a new onboarding step in an afternoon while another changes pricing logic the same day. If signup knows billing internals, those changes collide. If signup only calls a small billing interface, both changes can move forward and the rule stays in one place.

The first cut should follow the jobs users do and the rules that must stay consistent. Not the tech stack. Not the folder tree.

What to freeze early

Freeze the contract, not the code.

When a team moves fast with prompts, the danger is rarely the first version of a function. The real danger appears in the second and third versions, after other parts of the product start depending on behavior nobody wrote down.

Start with plain language. Write what goes in, what comes out, and what each field means. "Customer ID is a string," "trial_end may be empty," and "status can only be active, paused, or canceled" are clear enough for both people and models. Loose labels like "user info" or "account data" invite guesses, and prompt-built code fills those gaps differently every time.

Ownership needs the same clarity. Decide which side owns which data, who can change it, and who only reads it. Billing can own invoice state. The app can own feature access rules. If two teams edit the same field, coupling starts quietly and tends to stick.

Errors and missing fields need one shared rule too. Keep it boring. If a required field is missing, reject the request with a clear error code. If a field is optional, return null or an empty value the same way every time. Do not let one service guess defaults for another service's required data. That single rule prevents a lot of silent breakage.

Someone also needs final approval for contract changes. One person or one team should review changes to shared field names, types, and error behavior. Otherwise, a small prompt tweak can change an output shape and break three consumers before anyone notices.

Do not freeze internal details too early. The prompt, helper functions, database queries, and even service layout can change often. That freedom is where speed comes from. Keep the outside stable and let the inside move. Teams that do this well can rewrite internals in a day without forcing the rest of the product to relearn the boundary.

How to lock an interface early

Start with one workflow that matters right now. Do not try to freeze the whole product. Pick the path your team touches every week, like "trial signup creates account" or "support ticket moves from open to closed." One boundary done well beats five half-finished ones.

Then write a short contract for that workflow. Keep it specific. You are not writing a big spec. You are deciding what can cross the boundary, what state changes are allowed, and where the limits are.

A good contract often fits on one page. It names the fields and their types, the states an item can move through, the limits around size, timeout, retries, and error format, and the parts that stay stable even if the code behind them changes.

This is where teams either hold the line or lose it. If the contract is vague, AI tools fill the gaps with guesses. Those guesses turn into code, and that code spreads fast.

Put the contract inside the prompt you give your coding tools. Say what they can do and what they cannot change. A plain instruction works well: generate code inside this interface, do not rename fields, do not add states, do not change response shape. That one rule cuts a lot of accidental coupling.

You also need one test that fails when the contract changes. Keep it simple. If your API returns status, plan, and expires_at, the test should fail when someone swaps expires_at for expiryDate because a prompt decided it looked cleaner. Speed is fine. Silent drift is not.

A small SaaS team can do this in an afternoon. They freeze the billing webhook payload, pin the allowed event states, and add one contract test in CI. After that, prompts can still generate handlers, logs, retries, and admin screens. They just cannot rewrite the boundary on a whim.

Treat boundary edits as a special kind of change. Review them before you merge, even if the diff looks tiny. Most messy systems do not break from one huge mistake. They drift because small interface changes slip through while everyone is moving fast.

How to keep speed without breaking the contract

Fast teams rarely get stuck because they write too much code. They get stuck when one prompt quietly changes what another part of the app expects. If an API shape, event payload, or function signature drifts every few days, each quick win creates more cleanup later.

One habit helps more than most teams expect: keep interface notes next to the code, not in a separate doc nobody opens. A short contract file with field names, status codes, and one or two sample payloads saves time because the model, the developer, and the reviewer all work from the same source.

Example requests and responses should also show up in prompts and code reviews. Models do better when they can copy a clear pattern. Reviewers do better too, because they can compare output to a concrete sample instead of guessing what the prompt meant.

Treat the inside of a module as flexible. Regenerate handlers, tests, helpers, and queries whenever you want. Treat boundary edits as planned work. If you need to rename a field, change an error format, or drop a parameter, assign it, record it, and ship it like any other product change.

Sometimes one side needs to change first. That is normal. Do not force both sides to move on the same day if that creates risk. Add a small adapter instead. It can translate old input into the new shape, or map new output back to the old one, until the second side catches up.

The shared record can stay simple. One changelog, schema file, or contract note in the repo is enough if the team updates it every time. The line stays clear when nobody has to ask where the latest version lives.

A short checklist usually works:

• Keep contract notes and samples in the repo, close to the code that uses them.
• Paste example requests and responses into prompts, tests, and reviews.
• Rewrite internals freely, but schedule changes at the boundary.
• Use adapters when clients and services cannot change together.
• Record every contract change in one shared place.

This sounds strict, but it protects speed. Prompt-driven software moves fastest when teams can change the inside freely and trust the edges to stay stable.

A simple example from a small SaaS team

A four-person SaaS team had one week to ship a new onboarding flow. Trial users signed up, got lost in setup, and never reached billing. The team used AI to move fast: one prompt wrote most of the form checks, another drafted the welcome emails, and a third generated the admin action that created a customer record for support.

They made one smart decision before they started. On day one, they froze the handoff between signup and billing. Signup could collect data, validate it, and send one clean payload to billing. Billing would accept only that payload and return only a few clear states, such as "trial started" or "payment needed."

The contract stayed small: user identity, selected plan, country for tax rules, and trial start date. Everything else stayed outside billing. The email step did not call payment code. The admin panel did not reach into checkout. If the team wanted extra profile fields later, signup could store them on its side without changing how billing worked.

That decision paid off two days later. The AI-generated email step looked fine in testing, but real users ignored the first message. The team rewrote the email logic, changed the timing, and added a reminder for incomplete setup. They did all of that without touching payments, because email listened for a signup event instead of sitting inside the billing path.

The same boundary helped with testing. The team did not need to retest every screen after each change. They only checked two things: did signup still send the agreed fields, and did billing still respond with the same states? That cut the test surface down to something a small team could handle in a busy week.

Prompt-built code often grows by accident. One generated function calls another, then a third reaches across the app "just for now." A frozen interface stops that drift early. The code behind each step can stay messy for a while, but the seam between steps stays stable.

That is why this kind of boundary pays off fast. A team can keep shipping at AI speed, replace weak parts as they learn, and avoid turning a one-week shortcut into a six-month cleanup job.

Mistakes that create permanent coupling

Teams rarely plan tight coupling. They usually create it through fast fixes, and prompt-built code makes that easier.

One common mistake is giving prompt tools permission to read and change any file in the repo. When a model can touch everything, it often crosses lines a human would stop and question. A small billing change ends up editing auth, shared types, email templates, and background jobs because that is the shortest path to a passing result.

Another mistake is passing raw database tables across module or service boundaries. It feels fast because nobody writes mapping code. Then storage details leak into the rest of the product. If one team splits a table, renames a column, or changes a nullable field, everyone else inherits that change whether they want it or not.

Field renames create a slower version of the same problem. Someone changes customer_name to full_name in one area and hopes the rest still works. Prompt tools often catch the obvious references, but they can miss exports, filters, reports, older endpoints, and scripts that nobody remembers until they fail.

Temporary scripts cause trouble too. A one-off importer or migration helper lands inside product code, then starts calling internal modules because it is convenient. A few weeks later, someone runs it in production because it already exists. Now a throwaway script is part of the system.

Ownership matters just as much as code shape. When two teams share one interface and nobody owns it, both sides keep making small edits. Each change looks harmless on its own. Together, they turn the boundary into a moving target.

The warning signs are usually obvious once you know where to look. Prompts start asking to "update every file that uses this." Teams pass full ORM models instead of small contract objects. Old scripts show up in CI or scheduled jobs. Two teams change one schema without a named reviewer.

Boundaries hold up better when access stays narrow, contracts stay explicit, and one owner protects each interface. That may feel slower for a day. It saves weeks of cleanup later.

Quick checks before you ship

Fast code feels good right up to the moment a small change leaks across three parts of the product. A two-minute review at the boundary catches a lot of that.

Before shipping, ask a few direct questions. Can one side change on its own? If the UI tweaks a label or the backend gets an internal refactor, the other side should stay untouched unless the contract itself changed. Is there one owner for the contract? One person or team should approve schema changes, state changes, and version rules. If ownership is fuzzy, the boundary will drift.

Your tests should also fail on contract breakage. Renamed fields, removed fields, new enum values, and missing states such as empty, loading, denied, or archived should trigger a clear failure. And ask a new teammate to explain the boundary in plain words. If they need ten minutes to trace files, prompts, and side effects, the line is too blurry.

One more check is easy to miss: compare the prompt scope with the diff. If you asked for a change in one module and the model edited shared helpers, auth code, or common types, stop and review it by hand.

A small SaaS team can feel this immediately. Suppose support adds a new ticket state called "waiting_on_customer." If that change forces edits in reporting, billing, and mobile notifications on day one, the team did not just add a state. They exposed hidden coupling.

That does not mean every contract needs heavy process. A short schema file, a few contract tests, and a named owner are often enough. This is also the kind of practical discipline Oleg Sotnikov talks about in his AI-first advisory work, because it keeps speed useful instead of expensive.

If one of these checks fails, do not patch around it and ship anyway. Freeze the contract, narrow the prompt, and rerun the change inside the boundary you meant to touch.

Next steps for teams that need more structure

If your team keeps fixing the same mess, do not start with a full process rewrite. Start with one workflow that already hurts. Pick something concrete, like customer onboarding, billing updates, or support-driven bug fixes, and map the handoffs that happen today.

Write down who creates the prompt, who checks the result, which service receives the output, and where people still patch things by hand. Most teams find the real problem fast. The code is rarely the first issue. The handoff is.

Before the next sprint starts, freeze one interface in that workflow. Keep it small. Define the input, the output, who owns it, and what happens when data is missing or wrong. Put that contract in one place the team can see, then back it with tests so nobody changes it by accident.

A simple cadence works well. Map one messy workflow end to end. Freeze the next interface the team will touch. Assign one owner for that boundary. Review boundary changes at sprint start instead of letting them slip in midweek.

If the same boundary keeps moving, stop treating it as a coding problem. The split is usually wrong, ownership is fuzzy, or one team still reaches across layers when work gets rushed. A short architecture review can settle that before the next round of rework starts.

Sometimes outside help is the fastest option. Oleg Sotnikov works with startups as a Fractional CTO and helps teams set practical prompt rules, clear ownership, and software boundaries that hold while code moves fast. If you want a closer look at that approach, oleg.is is a straightforward place to start.

Teams that build mainly through prompts move fast by default. Structure should do one job: keep that speed from turning into coupling you have to live with for years. Pick one boundary this week and make it boring, clear, and hard to break.