AI Technical Debt: A Pre-Code Architecture Check for Solo Builders

The most expensive AI-generated mistake is rarely an untidy function. It is an unstated product assumption that becomes a data model, an API contract, and several dependent features before anyone notices it was wrong.

For a solo builder, that is the dangerous form of AI technical debt. Without a second engineer reviewing the model, a locally reasonable choice can harden into structural debt at generation speed.

The most affordable time to catch that debt is before coding begins, while the architecture is still expressed as entities, states, relationships, and boundaries. A short pre-code check exposes decisions that become expensive after the agent builds on them.

This check complements the agent-ready PRD: the PRD records approved behavior, while the pre-code architecture check challenges the entities, states, boundaries, and failure paths most expensive to reverse.

What is AI technical debt?

AI technical debt is the future cost created when AI-generated implementation choices make a codebase harder to change, understand, or align with the product.

Some debt is local: duplicated logic, oversized functions, or inconsistent naming that review and refactoring can correct. Structural debt affects the shape of the system and spreads into everything built on it.

AI coding agents do not invent structural debt. They accelerate it. An agent can implement a reasonable interpretation, then use that code as context for the next task. Once several features depend on the assumption, revisiting it is no longer a small edit.

The control point is therefore not only code review. It is the requirement that authorizes the architecture.

The three product decisions behind structural debt

Most preventable architecture flaws begin with one of three decisions that remained implicit: what exists, how it can change, and where responsibility belongs.

Under-modeled entities

Suppose a requirement says, "Customers can place and manage orders." An agent may create one order record with a total and status. That fails when the product needs split shipments, partial refunds, item-level returns, or separate payment attempts.

The requirement never established whether orders, payments, shipments, and returns were separate concepts or properties of one object.

Before implementation, name each product-significant entity and answer four questions:

• What does it represent?

• Which information does it own?

• What is it related to?

• Can it exist, change, or be deleted independently?

Define enough of the product model to stop the agent from collapsing distinct concepts into one record; you do not need every database column.

Missing states and transitions

A requirement often describes the happy path and leaves the model to infer the rest. A subscription is active or cancelled. An invitation is pending or accepted. An order is open or complete.

Real products also need awkward states: expired, partially fulfilled, recoverable, disputed, suspended, or cancelled in progress. Missing states later become special flags and exceptions.

For every important entity, list:

• its valid states

• the event that enters each state

• which transitions are allowed or forbidden

• what the user can do in each state

• what happens when a transition fails halfway through

A state diagram is optional. An explicit transition list is not.

Wrong boundaries

Requirements create architecture by deciding what belongs together. If a ticket describes payment and fulfillment as one operation, an agent may couple responsibilities that need different failure handling and change cycles.

A boundary is useful when two responsibilities have different rules, failure modes, data ownership, or reasons to change. Ask:

• Can these parts fail independently?

• Will they change for different product reasons?

• Does one own data the other should only reference?

• Would separating them make an important rule easier to verify?

Separate responsibilities when the product requires independence, not because every noun deserves its own service.

A worked example: account deletion

Consider the requirement: "Users can delete their account."

It leaves architectural decisions unresolved. An agent could hard-delete the user and related data while violating recovery, billing, or retention rules that were never supplied.

A pre-code check exposes the missing decisions:

The resulting requirement can now say what the architecture must support without dictating its implementation:

When a customer requests deletion, the account enters a recoverable deleted state for 30 days. Product access ends immediately, billing records required for retention remain available, restoration is permitted during the recovery window, and permanent cleanup begins only after the window expires.

The agent may still choose an imperfect design, but immediate hard deletion is no longer an equally valid interpretation.

The solo builder pre-code architecture check

Run this check before a product-significant requirement becomes a ticket. A small feature may take ten minutes; payments, identity, permissions, deletion, and shared data deserve more scrutiny.

1. Define the task boundary

State what changes, what must remain true, and what is out of scope. Non-goals stop the agent from adding related behavior simply because it appears useful.

2. Map entities and relationships

List the objects the feature creates, reads, changes, or deletes. Record ownership and lifecycle dependencies where they affect behavior.

3. Enumerate states and transitions

Include normal, empty, loading, failed, expired, cancelled, recoverable, and partially completed states where relevant. Define who or what can trigger each transition.

4. Test the boundaries

Separate responsibilities with different rules, failure modes, security needs, or reasons to change. Keep them together when separation protects no real product decision.

5. Walk through failure and recovery

Define the product outcome if a service fails, a task runs twice, or a process stops halfway through—not only the error message.

6. Make acceptance observable

Write acceptance criteria for the states and constraints that matter. "Works correctly" cannot reveal structural drift. "A declined payment preserves the cart and creates no confirmed order" can.

7. Record unresolved decisions

Do not hide uncertainty inside a prompt. Mark an open decision, choose an owner, and prevent implementation from treating it as settled.

Use a one-page architecture decision brief

The output does not need to be a large architecture document. A compact brief is enough for most solo-builder features.

Supply this brief with the task. Existing code describes what exists; the brief describes what the new behavior is authorized to become. For task-level context selection, see context management for AI coding agents.

Review architecture without a second engineer

A second engineer often catches a weak boundary by asking why the system is shaped that way. Solo builders must preserve that question in the workflow.

Use a traceability chain:

Product decision -> requirement -> acceptance criteria -> implementation task -> code and tests

Before approving an AI-generated change, walk backward:

• Which requirement authorizes this entity, state, or permission?

• Which decision explains why the requirement exists?

• Which acceptance criterion proves the behavior is correct?

• Did the implementation add a structural choice that the requirement never approved?

If the answer is missing, pause. A sensible option is still a product decision: approve it explicitly or change the implementation.

When a requirement changes, this chain identifies the tickets, tests, and components that inherited it. That ongoing alignment is covered in managing context drift in AI-generated code.