Architecture on Shane's Personal Blog

Litestar DTOs: The 'Advanced Feature' I Didn't Need (And When You Might)

Sun, 02 Nov 2025 00:00:00 GMT

The Moment of Self-Doubt

I was knee-deep in my FastAPI to Litestar migration, feeling pretty good about myself. I’d just wrapped my head around msgspec and was happily writing explicit schema conversions. Everything was working beautifully.

Then I made the mistake of looking at Litestar’s full-stack example repository.

class UserDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash", "sessions", "oauth_accounts"},
        rename_strategy="camel",
        max_nested_depth=2,
    )

@get("/users/{user_id}", return_dto=UserDTO)
async def get_user(self, user_id: UUID) -> User:
    return await user_service.get(user_id)

Wait. What?

The controller just returns the raw SQLAlchemy model? No manual conversion? No explicit schema class? Just… return the model and some magic DTO thing handles everything?

And everyone in the examples was using it. Every. Single. Endpoint.

That familiar developer anxiety crept in: Am I doing this wrong?

My “Primitive” Approach

Here’s what I’d been doing, blissfully unaware I might be committing some architectural sin:

# Define explicit response schemas
class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str | None = None
    is_admin: bool = False

# Manual conversion in controllers
@get("/profile")
async def profile(self, current_user: AppUser) -> UserResponse:
    return UserResponse(
        id=current_user.id,
        email=current_user.email,
        full_name=current_user.full_name,
        is_admin=current_user.is_admin,
    )

It worked. It was clear. I could see exactly what data was being exposed.

But now I was looking at this DTO thing thinking: “Should I be using that instead? Is my code… amateur hour?”

The Investigation Begins

I did what any self-respecting developer does when feeling inadequate: I asked ChatGPT.

“Should I be using Litestar’s DTO system instead of explicit msgspec schemas?”

The conversation that followed was enlightening. It wasn’t a simple “yes” or “no”—it was a “depends on what you’re building.”

That’s when I realized I needed to actually understand what DTOs are and what problem they solve. Because apparently, not every “advanced feature” is automatically better.

What Even IS a DTO?

DTO stands for Data Transfer Object. In Litestar’s context, it’s a transformation layer between your internal data models (SQLAlchemy, Pydantic, msgspec) and what you send/receive over the wire.

Think of it as a smart template system. You define transformation rules once, and Litestar applies them automatically:

“Exclude these sensitive fields”
“Rename snake_case to camelCase”
“Only include these specific fields”
“Serialize nested relationships up to depth 2”

Instead of writing manual conversion code in every endpoint, you configure the DTO once and attach it to your routes.

The key insight: DTOs are platform-agnostic. They work with Pydantic models, msgspec structs, dataclasses, and SQLAlchemy models through different backends (PydanticDTO, MsgspecDTO, SQLAlchemyDTO). The concept remains the same regardless of which you use.

But here’s what I was really wondering: Do I actually need this?

The Side-by-Side Reality Check

Let me show you what I was comparing. Here’s a real endpoint from my auth system:

My Current Approach (Explicit Schemas)

# schemas.py - Define exactly what to expose
class LoginRequest(CamelizedBaseStruct):
    email: str
    password: str

class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str | None = None
    is_admin: bool = False

class LoginResponse(CamelizedBaseStruct):
    access_token: str
    token_type: str = "Bearer"
    expires_in: int
    user: UserResponse

# controller.py
@post("/login")
async def login(
    self,
    data: LoginRequest,
    user_service: UserService,
) -> LoginResponse:
    user = await user_service.authenticate(data.email, data.password)
    token = create_access_token(user.id)

    return LoginResponse(
        access_token=token,
        expires_in=3600,
        user=UserResponse(
            id=user.id,
            email=user.email,
            full_name=user.full_name,
            is_admin=user.is_admin,
        ),
    )

Line count: Clear, explicit, about 35 lines total.

The DTO Approach

# schemas.py - Configure transformation rules
class UserResponseDTO(SQLAlchemyDTO[AppUser]):
    config = DTOConfig(
        exclude={"password_hash", "sessions", "oauth_accounts", "credit_balance"},
        rename_strategy="camel",
    )

class LoginRequestDTO(MsgspecDTO[LoginRequest]):
    config = DTOConfig(rename_strategy="camel")

# controller.py
@post("/login", data=LoginRequestDTO, return_dto=UserResponseDTO)
async def login(
    self,
    data: DTOData[LoginRequest],
    user_service: UserService,
) -> AppUser:
    request = data.create_instance()
    user = await user_service.authenticate(request.email, request.password)
    # ... token creation
    return user  # DTO handles conversion

Looking at these side-by-side, the DTO version seemed… more complex? Not simpler?

For my use case:

4 fields in the request
4 fields in the user response
Different fields in each response type (login vs profile vs admin)

The DTO configuration wasn’t saving me any code. If anything, it was adding abstraction for no clear benefit.

The Lightbulb Moment

Then ChatGPT gave me an example that made everything click.

“Imagine you have a User model with 30 fields, and you have 10 different endpoints that return users with only slight variations.”

Oh.

Without DTOs:

class UserListResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields
    created_at: datetime
    updated_at: datetime

class UserDetailResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields (SAME AS ABOVE)
    created_at: datetime
    updated_at: datetime
    last_login_at: datetime  # ONE extra field
    login_count: int          # ONE extra field

class UserAdminResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    username: str
    full_name: str
    # ... 26 more fields (SAME AS ABOVE AGAIN)
    created_at: datetime
    updated_at: datetime
    last_login_at: datetime
    login_count: int
    password_hash: str  # Admin can see this

You’d be copying and pasting 28 fields across three schemas. If you need to add a new field or rename one, you’d have to update it in three places. Error-prone. Painful during refactoring.

With DTOs:

# Define base fields once via the model
# Then configure variations

class UserListDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash", "last_login_at", "login_count"},
        rename_strategy="camel",
    )

class UserDetailDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash"},
        rename_strategy="camel",
    )

class UserAdminDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        rename_strategy="camel",  # Include everything
    )

Ah. Now I see it.

DTOs shine when you have large schemas with small variations. Instead of copying 30 fields and playing “spot the difference” during code reviews, you define transformations: “include everything except X” or “exclude only Y.”

But my auth endpoints? 4-8 fields, completely different shapes. No duplication to eliminate. No variations to configure.

When DTOs Actually Make Sense

Once I understood the problem DTOs solve, I could see exactly when they’d be valuable:

1. Large Schemas with Minor Variations

Perfect for:

User models with 20+ fields
Product catalogs with extensive metadata
Admin panels with many similar CRUD endpoints

# One model, many views
class ProductListDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig(
        exclude={"internal_cost", "supplier_details", "inventory_history"},
    )

class ProductDetailDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig(
        exclude={"internal_cost", "supplier_details"},  # Show more
    )

class ProductAdminDTO(SQLAlchemyDTO[Product]):
    config = DTOConfig()  # Show everything

Instead of defining 30 fields three times, you configure what to exclude.

2. Complex Nested Relationships

When you have models that reference other models:

# Model structure
class Case(Base):
    id: UUID
    name: str
    user: Mapped[User]  # Relationship
    documents: Mapped[list[Document]]  # Relationship
    workflow_task: Mapped[WorkflowTask]  # Relationship

# Without DTO - manual nesting
class DocumentResponse(CamelizedBaseStruct):
    id: UUID
    filename: str

class WorkflowTaskResponse(CamelizedBaseStruct):
    id: UUID
    stage: str

class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str

class CaseResponse(CamelizedBaseStruct):
    id: UUID
    name: str
    user: UserResponse
    documents: list[DocumentResponse]
    workflow_task: WorkflowTaskResponse

# Manual conversion - tedious and error-prone
@get("/cases/{case_id}")
async def get_case(self, case_id: UUID) -> CaseResponse:
    case = await case_service.get(case_id)
    return CaseResponse(
        id=case.id,
        name=case.name,
        user=UserResponse(id=case.user.id, email=case.user.email),
        documents=[
            DocumentResponse(id=doc.id, filename=doc.filename)
            for doc in case.documents
        ],
        workflow_task=WorkflowTaskResponse(
            id=case.workflow_task.id,
            stage=case.workflow_task.stage,
        ),
    )

That’s a lot of manual mapping!

With DTOs:

class CaseDTO(SQLAlchemyDTO[Case]):
    config = DTOConfig(
        max_nested_depth=2,  # Auto-serialize relationships
        rename_strategy="camel",
    )

@get("/cases/{case_id}", return_dto=CaseDTO)
async def get_case(self, case_id: UUID) -> Case:
    return await case_service.get(case_id)  # DTO handles nesting

The DTO automatically serializes nested relationships. The resulting JSON preserves the structure:

{
  "id": "123...",
  "name": "Smith v. Jones",
  "user": {
    "id": "456...",
    "email": "lawyer@example.com",
    "fullName": "John Lawyer"
  },
  "documents": [{ "id": "789...", "filename": "contract.pdf" }],
  "workflowTask": {
    "id": "012...",
    "stage": "completed"
  }
}

For deeply nested structures, DTOs eliminate a LOT of boilerplate.

3. Consistent Transformations Across Many Endpoints

If you have 20 endpoints that all return the same data with the same transformations:

# Without DTO - repeat rename logic everywhere
class UserResponse(CamelizedBaseStruct):
    id: UUID
    email: str
    full_name: str  # Manually renamed from fullName
    is_admin: bool  # Manually renamed from isAdmin

# With DTO - configure once
class UserDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        rename_strategy="camel",  # Applies to all fields automatically
    )

If you later decide to use PascalCase instead of camelCase, you change one config line instead of 20 schema classes.

4. Bidirectional Use (Request + Response)

DTOs can handle both input validation and output serialization:

class UserCreateDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        include={"email", "password", "full_name"},  # Only these for creation
        rename_strategy="camel",
    )

class UserResponseDTO(SQLAlchemyDTO[User]):
    config = DTOConfig(
        exclude={"password_hash"},  # Don't expose sensitive fields
        rename_strategy="camel",
    )

@post("/users", data=UserCreateDTO, return_dto=UserResponseDTO)
async def create_user(self, data: DTOData[User]) -> User:
    user_data = data.as_builtins()  # Validated dict
    user = await user_service.create(user_data)
    return user  # Auto-converted to response

Same model, different “views” for input vs output.

The Feature Buffet: What DTOs Can Do

Now that I understood when to use DTOs, I explored what they could actually do. Here are the key capabilities (without getting into syntax details):

Field Control:

Exclude fields: Hide sensitive data like password_hash, internal_notes
Include only specific fields: Whitelist approach instead of blacklist
Partial models: Make all fields optional (useful for PATCH endpoints)

Transformations:

Rename strategy: Convert between snake_case, camelCase, PascalCase
Rename individual fields: Custom mappings for specific fields
Computed fields: Add calculated values not in the model

Relationship Handling:

Max nested depth: Control how deep relationship serialization goes
Circular reference handling: Prevent infinite loops in self-referential models

Validation:

Type safety: DTOData provides validated conversion helpers
Integration with model validators: Works with Pydantic/msgspec validation

The point isn’t to memorize all these options—it’s to recognize that DTOs are a configuration system for data transformation. When you have complex transformation needs across many endpoints, that configuration approach starts to pay off.

The Honest Trade-offs

After all this investigation, I could finally see both sides clearly.

When DTOs Win

Scenario: E-commerce admin panel with 50+ endpoints, User/Product/Order models with 25+ fields each

✅ Less code duplication (define fields once)
✅ Consistent transformations (one rename_strategy for all)
✅ Safer refactoring (change model, DTOs adapt)
✅ Automatic nested serialization (complex object graphs)
✅ Centralized field exclusion (security by default)

Pain points: More abstraction, harder debugging when things go wrong, learning curve for DTOConfig

When Explicit Schemas Win

Scenario: Auth system with 8 endpoints, small distinct request/response shapes

✅ Crystal clear what data is exposed (security-critical)
✅ Simple debugging (no transformation layer)
✅ Easy to understand (explicit is better than implicit)
✅ Perfect for small, distinct schemas
✅ Full control over every field

Pain points: Manual conversion code, potential field drift if you’re not careful, more code for large schemas

My Decision: Explicit Schemas (For Now)

For my auth system, the choice became obvious:

My schemas are:

Small (4-8 fields)
Distinct (login, register, profile all have different shapes)
Security-critical (I want to be VERY explicit about what’s exposed)

My team values:

Explicitness over magic
Simple debugging
Clear code over clever code

DTOs would add complexity without solving any problem I actually have.

But here’s the key realization: This isn’t a forever decision.

If I later build:

An admin dashboard with 30 similar CRUD endpoints
A reporting system with complex nested data
A public API with many variations of User/Product responses

Then DTOs would make perfect sense. I’ll know when I need them—when I find myself copy-pasting large schemas and playing “spot the difference” during code reviews.

The Real Lesson: Question the “Best Practices”

This whole journey taught me something more valuable than just when to use DTOs.

I started feeling inadequate because I wasn’t using an “advanced feature” everyone else seemed to be using. The example code used it, so clearly I was doing something wrong, right?

Wrong.

“Advanced features” aren’t better—they’re just tools for specific problems.

The Litestar examples use DTOs because they’re showing off the framework’s capabilities. They’re demonstrating what’s possible, not what’s mandatory. A full-stack example repository naturally has complex nested data and many similar endpoints—the perfect use case for DTOs.

But your codebase might be different. And that’s okay.

The best code isn’t the one that uses the most advanced features. It’s the one that:

Solves your actual problems
Your team can understand and maintain
Fits your specific context

Sometimes that means reaching for powerful abstraction layers like DTOs. Sometimes it means writing simple, explicit conversion code.

The skill isn’t in knowing all the tools—it’s in knowing which tool fits which problem.

How to Choose for Your Project

Here’s the decision framework I landed on:

Use Explicit Schemas When

Schemas are small (< 15 fields)
Each endpoint has distinct response shapes
Security is critical (auth, payments, PII)
Team is small or values explicitness
You’re building a simple CRUD API

Use DTOs When

Schemas are large (> 20 fields)
Many endpoints return similar data with slight variations
Complex nested relationships need serialization
You have 20+ endpoints with consistent transformations
You’re building an admin panel or complex dashboard
Field exclusion/security is error-prone without automation

Don’t Decide Yet If

You’re just starting the project. Build a few endpoints with explicit schemas first. If you find yourself copy-pasting large schemas and thinking “there has to be a better way,” that’s when you look into DTOs.

Don’t add abstraction until you feel the pain it’s meant to solve.

Where I Am Now

I’m still using explicit msgspec schemas for my auth system. No DTOs. No automatic transformations. Just clear, simple conversion code.

And I’m completely confident in that decision.

Not because DTOs are bad—they’re actually quite elegant for the right use case. But because I understand why they exist and when they help.

That moment of self-doubt when I saw the example code using DTOs? It turned into a learning opportunity. I don’t feel inadequate anymore. I feel informed.

When I eventually build that admin dashboard with 50 endpoints and complex nested data, I’ll reach for DTOs with confidence. I’ll know exactly why I’m using them and how to configure them effectively.

But for now? Explicit is exactly right.

The Takeaway

Next time you see an “advanced feature” in example code and wonder if you’re doing it wrong by not using it, remember:

Understand the problem it solves - What pain point does this feature address?
Evaluate if you have that problem - Do you actually need this solution?
Consider the trade-offs - What are you gaining vs. what complexity are you adding?
Choose what fits your context - There’s no one-size-fits-all “best practice”

Sometimes the simple approach is the right approach. And that’s not a failure—it’s good engineering judgment.

DTOs are a powerful tool for data transformation at scale. But power you don’t need is just complexity you have to maintain.

Know your tools. Understand their trade-offs. Choose wisely.

(Written by Human, improved using AI where applicable.)

Stop Letting AI Rewrite Your Entire Codebase (And Start Coding Again)

Mon, 20 Oct 2025 00:00:00 GMT

The $400 Wake-Up Call

I used to have Cursor’s highest tier subscription—$200 a month with $400 in monthly credits. Sounds like plenty, right?

Two weeks. That’s how long it took me to burn through the entire quota.

I found myself rationing my coding time based on API credits. Think about that for a moment—I love coding. I want to work all day. But here I was, checking my usage dashboard like someone monitoring a dwindling bank account, wondering if I could afford one more refactoring session before the month reset.

Something was deeply wrong.

But the cost wasn’t even the worst part. The worst part was watching my carefully planned code dissolve into something I couldn’t recognize anymore.

When Good Plans Meet Eager AI

Picture this: You’ve architected something beautiful. You know exactly what you want. You’ve thought through the design patterns, planned the separation of concerns, mapped out the type system. You’re not just playing around—you’re building something real, something that needs to scale, something that actual users will depend on.

So you explain your plan to your LLM assistant. The plan is solid. You’re feeling good.

And then it generates 500 lines of code.

At first glance, it looks… fine? It runs. But as you read through it:

The Python typing is sloppy—bare dict and list types everywhere when you need strict typing
Data is being passed around as raw JSON objects, making everything impossible to trace
There’s zero separation of concerns—just one massive function doing everything
It’s like the LLM threw the entire architecture into a blender and hit “frappe”

“No problem,” you think. “I’ll just ask it to fix these issues.”

So it rewrites the entire thing.

Now the typing is overly specific. It’s created seventeen helper functions where you needed three. The original logic that actually worked is gone, replaced with something that breaks in subtle ways you won’t discover until production. And you can’t even remember what the original code looked like because it’s been through four complete rewrites in twenty minutes.

You’re sitting there, staring at your screen, thinking: “I had a plan. What happened to my plan?”

If you’ve experienced this sinking feeling, you’re not alone. And if you’ve sworn off AI coding assistants because of it, I don’t blame you. I nearly did too.

The Real Problem (And It’s Not the AI)

Here’s what I eventually realized: The LLM isn’t bad at coding. It’s actually pretty good—when it understands what you want and operates within clear boundaries.

The problem was me letting it jump straight to implementation.

Think of it like this: Imagine hiring a new developer who, the moment you mention a problem, immediately opens their editor and starts frantically rewriting your entire authentication system before you’ve even finished explaining what’s wrong. You’d stop them, right? You’d say, “Hold on, let’s talk through this first. What are the trade-offs? How does this fit with our existing architecture?”

But with LLMs, we often skip that conversation. We describe a problem and—because the tools make it so easy—let them immediately start generating code. No discussion. No design review. No “have we thought through the implications of this?”

The result? Cascading failures:

File A has a subtle architectural inconsistency
File B depends on File A, amplifying the problem
File C builds on File B, creating something that looks functional but is fundamentally fragile
You’ve burned through thousands of tokens generating code you’ll have to throw away

The Three-Prompt Rule That Changed Everything

After months of frustration (and drained API credits), I stumbled into a pattern that actually works. It’s almost embarrassingly simple:

Discuss, decide, then deploy.

Or more specifically: Make the LLM talk through the solution before it touches a single line of code.

This breaks down into three distinct prompts—three phases of conversation that keep you in control while letting the AI handle the heavy lifting.

Phase One: “Here’s How Things Work Around Here”

The first prompt isn’t about solving a problem. It’s about orientation—making sure the LLM understands your project’s architecture, design patterns, and philosophies before it offers any solutions.

Here’s what I actually send:

Need your help with optimizing the code with proper typing and more elegant solutions.
We'll do things iteratively—meaning we'll discuss and pin down a solution for a problem,
then I'll say "let's apply this to the code," and only then can you edit anything.
No code editing during discussion—you need explicit permission.

Now here's the overall project architecture: @project_big_picture.md

Your task right now: understand the project as a whole. We'll discuss specific
problems later.

The magic ingredient here is project_big_picture.md—a document I maintain that’s part architecture diagram, part philosophy statement, part annotated table of contents.

What goes in this document?

Think of it as the thing you’d give to a new team member on their first day. Not a line-by-line code walkthrough, but the high-level understanding they need:

Architecture overview: How the pieces fit together (I literally draw ASCII diagrams)
Design patterns we use: “All database access goes through repositories,” “We favor immutability,” etc.
File directory map: What each file/module does and how they relate
Design philosophies: The why behind our decisions
Non-negotiables: “We require strict typing,” “Error handling must be explicit,” that sort of thing

Here’s a real example from one of my projects (a cat photo rating API, because why not):

## Core Architecture

CatRater follows a layered architecture:

- API Layer (FastAPI) → handles HTTP, validation, serialization
- Service Layer → business logic, rating algorithms
- Repository Layer → all database access
- Models Layer → Pydantic models with strict typing (no bare dicts!)

## Design Principles

1. Explicit over implicit: We don't pass around JSON blobs. Every data structure
   has a defined Pydantic model.
2. Separation of concerns: Rating logic stays in services. Database access stays
   in repositories. No mixing.
3. Type safety: Python 3.11+ with full type hints. mypy must pass strict mode.

## File Map

- `api/routes/cats.py` - Cat photo submission and retrieval endpoints
- `services/rating_service.py` - Core rating algorithm (cuteness factors, whisker symmetry, etc.)
- `repositories/cat_repository.py` - Database operations for cat photos
- `models/cat_models.py` - CatPhoto, RatingScore, etc.

Is it extra work to maintain this document? Yes. Does it save me from re-explaining my architecture every single time I start a new chat? Absolutely.

Why this works:

When the LLM has this context up front, it can explore your codebase intelligently. It reads the relevant files. It understands how pieces connect. Most importantly, it learns what you care about—and it won’t suggest solutions that violate your principles.

Plus, you write this prompt once. Then you reuse it across coding sessions until your architecture meaningfully changes. The time investment pays for itself immediately.

Phase Two: “I’ve Got a Problem. How Would You Solve It?”

Now that the LLM understands your project, you can actually discuss the problem at hand.

The key here: Ask for proposals, not implementations.

Good second prompt:

I've noticed our cat rating logic is tightly coupled to the database repository,
making it impossible to test without spinning up a full database. How would you
propose refactoring this to align with our dependency injection patterns?

Bad second prompt:

Make the cat rating code testable.

See the difference? The first invites discussion. The second invites the LLM to immediately start rewriting code based on assumptions.

What happens next is what I call the “discussion chain”—a back-and-forth conversation where the LLM proposes solutions and you poke holes in them:

LLM: “I’d suggest extracting an interface for the repository and injecting it into the rating service…”

You: “That makes sense, but what about the rating cache? It’s currently stored in the repository layer.”

LLM: “Good point. We could move caching to the service layer, or introduce a dedicated caching layer…”

This might go on for 3-10 messages. You’re refining the approach together. You’re asking “what if” questions. You’re making sure the solution actually fits your architecture.

And crucially: No code changes happen during this phase.

The LLM is your thinking partner, not your typing monkey. It’s suggesting, explaining trade-offs, showing you where problems might arise. You’re maintaining full control over the design decisions.

I can’t overstate how much stress this eliminates. There’s no frantic “wait, stop, that’s not what I meant!” scrambling. There’s no throwing away thousands of lines of generated code. You’re designing the solution together, in plain English, before a single file gets touched.

Phase Three: “Okay, Let’s Do It”

Only after you’ve fully discussed the approach, considered the trade-offs, and pinned down exactly what you want—only then do you give permission:

This approach looks good. Let's apply these changes to the code.

Now the LLM implements.

And because you’ve thoroughly discussed the solution, the changes will:

Actually align with your architecture
Follow your established patterns
Include the right level of typing
Solve the problem without creating three new ones

But here’s the beautiful part: You’re not micromanaging the implementation. You’re not specifying every variable name or worrying about which files need imports. The LLM handles those details.

You designed it. The LLM built it.

The Complete Development Loop

Here’s what this looks like in practice:

Session 1:
├─ Prompt 1: "Understand my architecture" (@project_big_picture.md)
├─ Prompt 2: "Cat rating is coupled to database. Proposals?"
├─ Discussion: (4-5 messages refining the solution)
├─ Prompt 3: "Let's apply it"
└─ Implementation: (LLM makes the changes)

Session 2: (Same architecture, different problem)
├─ Prompt 1: "Understand my architecture" (same @project_big_picture.md—reused!)
├─ Prompt 2: "Image upload validation is inconsistent. Proposals?"
├─ Discussion: (6 messages)
├─ Prompt 3: "Apply it"
└─ Implementation

Session 3: (Major architectural change)
├─ Implementation revealed we needed a caching layer
├─ Update @project_big_picture.md with new architecture
└─ Next session: Start fresh with updated Prompt 1

When do you update project_big_picture.md?

Update when you’ve made a change that meaningfully alters your architecture:

Added a new layer (like that caching layer)
Changed a fundamental pattern (REST to GraphQL)
Refactored a core abstraction

Don’t update for:

Bug fixes
New features that follow existing patterns
Refactoring that doesn’t change public interfaces

When you do update, I typically ask the LLM to do it:

Based on our conversation and changes, update project_big_picture.md.
Keep the style consistent—generic enough to serve as guidance, specific
enough to capture our design decisions. Focus on how the architecture
evolved, not implementation details.

What Actually Changed (Besides My Sanity)

After adopting this approach, here’s what shifted:

Cost: I haven’t hit my $400 limit in months. Seriously. By scoping conversations to one problem at a time and discussing before implementing, I’ve cut my token usage by something like 70%. Sometimes I even copy a proposed solution from one chat and paste it into a new conversation to get a fresh perspective—sounds paranoid, but it saves a ton of tokens.

Code Quality: My code actually follows my architecture now. There’s no drift where the LLM subtly introduces patterns I don’t want. Type safety is consistent. Error handling is explicit. Everything feels intentional.

Debugging: When something breaks in production, I know exactly where to look—because I made the design decisions. The LLM just implemented them. The code structure makes sense to me because I architected it.

Mental Load: This is the surprising one. I thought adding all this structure would make coding feel more bureaucratic. Instead, it’s the opposite. I’m not constantly context-switching between “what do I want” and “what did the LLM just do?” I think at the design level. The LLM handles the implementation details. It feels like pair programming with someone who types really fast and never gets tired.

Speed: Yes, I’m actually faster overall. The time I spend in discussion is dwarfed by the time I save not debugging cascading failures or rewriting entire modules.

For the Skeptics (I Was One of You)

Look, if you’ve tried AI coding assistants and decided they write garbage code, you’re not wrong about what you experienced. I’ve been there. I’ve seen the sloppy typing, the tangled messes, the solutions that technically work but are architectural nightmares.

But here’s the thing: The LLM isn’t the architect. You are.

When you let it jump straight to code, you’re handing over design authority to something that doesn’t understand your project’s constraints, your team’s conventions, or your future maintenance burden. Of course it produces code you’d never ship.

But when you keep it in the discussion phase—when you use it as a thinking partner before giving it implementation authority—it becomes remarkably useful.

Think of it this way: You wouldn’t hire a developer and immediately give them commit access to main before they understand your codebase, right? You’d have them read the architecture docs, discuss approaches, get code reviewed.

Do the same with your LLM. Orientation, discussion, then implementation. In that order. Every time.

The Golden Rule

Discuss, decide, then deploy. Never let the LLM skip straight to implementation.

The moment you see it generating code during what should be a design discussion, you’ve lost control. Pull it back. “Let’s talk through the approach first.”

Your job: Architecture, design decisions, quality standards.

The LLM’s job: Remembering where everything is, handling boilerplate, implementing the approach you designed.

When you maintain that boundary, AI-assisted coding stops being chaos and starts being productive. You get to code faster without sacrificing quality. You get to work all day without burning through API credits. You get to ship code you actually understand and can debug when things go wrong.

And honestly? It makes coding fun again. I’m not fighting with an overager assistant that keeps rewriting my work. I’m designing systems and having them built to spec. That’s what I wanted all along.

(Written by Human, improved using AI where applicable.)