Building Without Tech Debt: An AI Development Playbook

Table of Contents

• The Debt Accumulation Model
• Principle 1: Lock the Architecture First
• Principle 2: Prompt as Contract, Not Command
• Principle 3: Review Diff Volume, Not Just Correctness
• Principle 4: Maintain a “AI-Free” Core
• Principle 5: Establish a Debt Budget
• Principle 6: The Pair-Programming Protocol
• Principle 7: Use AI for Boilerplate, Not Business Logic
• The Repeatable AI Workflow
• Measuring AI Debt
• Conclusion

The Debt Accumulation Model

Technical debt from AI follows a predictable curve.

Week 1–2: You ship 2x velocity. Code reviews are faster because diffs are smaller. You feel unstoppable.

Week 4–6: Inconsistencies emerge. The AI generates three different error-handling patterns across three services. Tests are missing or shallow. You start “fixing” AI-generated code more than writing new code.

Month 2+: The codebase has implicit dependencies on patterns the AI invented organically. New team members can’t onboard because the architecture is emergent, not designed. You’re now slower than before.

The root cause: AI optimizes for plausible output, not maintainable architecture.

Principle 1: Lock the Architecture First

AI should implement your architecture, not design it. Before you let AI write a single line of production code, define:

• Module boundaries: What calls what
• Data contracts: Input/output schemas
• Error policy: How errors propagate, log, and surface
• State ownership: Which layer owns which state

graph TD
    A[Architecture Decision] --> B[Implementation Spec]
    B --> C[AI Generates Code]
    C --> D[Human Reviews Against Spec]
    D --> E{Tests Pass?}
    E -->|Yes| F[Merge]
    E -->|No| G[Refine Spec or Prompt]
    G --> C

This is non-negotiable. If you haven’t written the architecture doc, prompt, or ADR, the AI is making architectural decisions by statistical accident.

Principle 2: Prompt as Contract, Not Command

Most prompting is wishful thinking: “build me a todo app.” This produces code that works once and breaks when requirements change.

Treat prompts as contracts with three sections:

1. Context: The system you’re working in and its constraints
2. Interface: Exact inputs, outputs, and error cases
3. Boundaries: What the code must NOT do

Example:

## Context
We're adding email verification to an existing Express API.
Database uses Prisma. Auth uses JWT with 15min expiry.

## Interface
POST /api/auth/verify-email
Input: { token: string }
Output: 200 { success: true } or 400 { error: string }

## Boundaries
- Do NOT change existing auth middleware
- Do NOT add new database tables
- Do NOT use console.log for production errors

This prompt produces code you can review in minutes, not hours. The boundaries prevent AI from “helpfully” refactoring things you didn’t ask for.

Principle 3: Review Diff Volume, Not Just Correctness

Code review after AI assistance needs a different lens. You’re not checking if it works—you’re checking if it scales mentally.

Three checks that catch 80% of AI debt:

1. Pattern scan Search the diff for:

• Multiple error-handling approaches
• Inconsistent naming conventions
• Duplicated utility functions
• Unnecessary abstractions

If you see more than two patterns for the same problem, reject the diff and refine the spec.

2. Dependency check AI loves adding dependencies. Review package.json diffs and imports with suspicion. Every new dependency is a maintenance commitment.

3. Test coverage audit AI-generated tests often test that the code does what the code does. They miss edge cases, error paths, and integration failures. Don’t merge code whose tests are obviously template-derived.

Principle 4: Maintain a “AI-Free” Core

Not every layer should have AI-generated code. Protect these boundaries:

• Security-critical paths: Auth, authz, payment flows, data validation
• State management: The core store and its mutations
• Infrastructure: CI/CD, deployment configs, database migrations

AI-generated infrastructure code is especially dangerous because it looks right, fails silently in production, and is hard to debug. The cost savings from AI-generated deploy scripts aren’t worth the blast radius when they fail at 2 AM.

Principle 5: Establish a Debt Budget

Technical debt isn’t avoidable. It’s manageable. Set explicit ceilings:

• Max AI-generated lines per PR: 200–300 lines. Larger changes should be split into smaller, reviewable chunks.
• Max new dependencies per month: 2. This forces intentional addition.
• Min test coverage for AI code: 85%. Lower standards for AI code are a false economy.
• Weekly “debt wipe”: 30 minutes to review and refactor AI-generated sections from the week.

If you hit any ceiling, stop AI-assisted development for that module until the debt is paid down.

Principle 6: The Pair-Programming Protocol

The highest-ROI AI workflow isn’t autonomous generation—it’s pair programming with review gates.

sequenceDiagram
    participant H as Human
    participant A as AI
    participant R as Reviewer

    H->>A: Prompt with architecture context + spec
    A->>H: Returns implementation
    H->>H: Smoke tests locally
    H->>R: Submits PR with AI context in description
    R->>R: Reviews for pattern consistency
    R->>H: Approves or requests refinement

The key rule: AI writes the first draft. Human writes the final version.

After review, you should be able to delete the AI-generated code and rewrite it from scratch without losing information. If you can’t, the code has become de facto documentation—and AI documentation rots faster than human docs.

Principle 7: Use AI for Boilerplate, Not Business Logic

The safe zone for AI is:

• CRUD endpoint scaffolding
• Test fixture generation
• Documentation drafts
• Refactoring within locked patterns
• Migration scripts for well-defined schemas

The danger zone is:

• Authentication flows
• Payment integration logic
• State machine transitions
• Data model design
• Performance-critical algorithms

This isn’t because AI can’t do these things. It’s because failures in these areas have asymmetric cost. A 10x velocity gain on boilerplate doesn’t offset a single auth bypass.

The Repeatable AI Workflow

Putting it together, here’s the workflow I use for every AI-assisted feature:

1. Pre-prompt: Write the architecture decision or interface contract
2. Generate: Prompt AI with context + contract + boundaries
3. Validate: Run tests and smoke tests locally
4. Pattern review: Scan the diff for inconsistency and unnecessary dependencies
5. Rewrite critical sections: Manually rewrite security, state, and integration code
6. Add edge-case tests: AI tests are happy paths; add failure scenarios yourself
7. Merge with debt note: Add a comment noting AI-assisted sections for future refactoring

This workflow adds about 15–20 minutes per feature but prevents the compounding debt that kills velocity at month 2.

Measuring AI Debt

You can’t manage what you don’t measure. Track these metrics:

• AI code percentage: What fraction of your codebase is AI-generated? Flag modules above 40%.
• Review turnaround time: If AI PRs take longer to review than handwritten ones, the debt is already accumulating.
• Production incident rate by module: AI-heavy modules should be audited weekly in the first 90 days.
• Refactoring frequency: How often do you rewrite AI-generated code? Once is learning. Twice is process failure.

Conclusion

AI is a multiplier, not a replacement. It multiplies your architecture if you have one. It multiplies your velocity if you have review processes. It multiplies your debt if you have neither.

The teams that win with AI won’t be the ones with the best tools. They’ll be the ones with the best processes—the ones who learned to treat AI output as raw material, not finished product.

Start with the architecture. Use AI to implement, not design. Review the diff, not just the tests. And maintain a strict debt budget.

The future belongs to engineers who can ship fast without shipping junk. That’s not a skill AI gives you. That’s a skill AI depends on.