Picture by Writer
# Introduction
AI coding instruments are getting impressively good at writing Python code that works. They will construct whole purposes and implement complicated algorithms in minutes. Nonetheless, the code AI generates is commonly a ache to take care of.
In case you are utilizing instruments like Claude Code, GitHub Copilot, or Cursor’s agentic mode, you might have in all probability skilled this. The AI helps you ship working code quick, however the associated fee reveals up later. You have got possible refactored a bloated operate simply to know the way it works weeks after it was generated.
The issue is not that AI writes dangerous code — although it typically does — it’s that AI optimizes for “working now” and finishing the necessities in your immediate, when you want code that’s readable and maintainable in the long run. This text reveals you how one can bridge this hole with a concentrate on Python-specific methods.
# Avoiding the Clean Canvas Lure
The largest mistake builders make is asking AI to start out from scratch. AI brokers work finest with constraints and tips.
Earlier than you write your first immediate, arrange the fundamentals of the venture your self. This implies selecting your venture construction — putting in your core libraries and implementing just a few working examples — to set the tone. This might sound counterproductive, however it helps with getting AI to write down code that aligns higher with what you want in your software.
Begin by constructing a few options manually. In case you are constructing an API, implement one full endpoint your self with all of the patterns you need: dependency injection, correct error dealing with, database entry, and validation. This turns into the reference implementation.
Say you write this primary endpoint manually:
from fastapi import APIRouter, Relies upon, HTTPException
from sqlalchemy.orm import Session
router = APIRouter()
# Assume get_db and Person mannequin are outlined elsewhere
async def get_user(user_id: int, db: Session = Relies upon(get_db)):
consumer = db.question(Person).filter(Person.id == user_id).first()
if not consumer:
elevate HTTPException(status_code=404, element="Person not discovered")
return consumer
When AI sees this sample, it understands how we deal with dependencies, how we question databases, and the way we deal with lacking data.
The identical applies to your venture construction. Create your directories, arrange your imports, and configure your testing framework. AI shouldn’t be making these architectural choices.
# Making Python’s Sort System Do the Heavy Lifting
Python’s dynamic typing is versatile, however that flexibility turns into a legal responsibility when AI is writing your code. Make sort hints important guardrails as an alternative of a nice-to-have in your software code.
Strict typing catches AI errors earlier than they attain manufacturing. Once you require sort hints on each operate signature and run mypy in strict mode, the AI can not take shortcuts. It can not return ambiguous sorts or settle for parameters that may be strings or may be lists.
Extra importantly, strict sorts pressure higher design. For instance, an AI agent attempting to write down a operate that accepts knowledge: dict could make many assumptions about what’s in that dictionary. Nonetheless, an AI agent writing a operate that accepts knowledge: UserCreateRequest the place UserCreateRequest is a Pydantic mannequin has precisely one interpretation.
# This constrains AI to write down right code
from pydantic import BaseModel, EmailStr
class UserCreateRequest(BaseModel):
title: str
e-mail: EmailStr
age: int
class UserResponse(BaseModel):
id: int
title: str
e-mail: EmailStr
def process_user(knowledge: UserCreateRequest) -> UserResponse:
go
# Reasonably than this
def process_user(knowledge: dict) -> dict:
go
Use libraries that implement contracts: SQLAlchemy 2.0 with type-checked fashions and FastAPI with response fashions are glorious selections. These will not be simply good practices; they’re constraints that preserve AI on monitor.
Set mypy to strict mode and make passing sort checks non-negotiable. When AI generates code that fails sort checking, it would iterate till it passes. This computerized suggestions loop produces higher code than any quantity of immediate engineering.
# Creating Documentation to Information AI
Most initiatives have documentation that builders ignore. For AI brokers, you want documentation they really use — like a README.md file with tips. This implies a single file with clear, particular guidelines.
Create a CLAUDE.md or AGENTS.md file at your venture root. Don’t make it too lengthy. Deal with what is exclusive about your venture reasonably than common Python finest practices.
Your AI tips ought to specify:
- Undertaking construction and the place several types of code belong
- Which libraries to make use of for frequent duties
- Particular patterns to observe (level to instance recordsdata)
- Specific forbidden patterns
- Testing necessities
Right here is an instance AGENTS.md file:
# Undertaking Tips
## Construction
/src/api - FastAPI routers
/src/companies - enterprise logic
/src/fashions - SQLAlchemy fashions
/src/schemas - Pydantic fashions
## Patterns
- All companies inherit from BaseService (see src/companies/base.py)
- All database entry goes by way of repository sample (see src/repositories/)
- Use dependency injection for all exterior dependencies
## Requirements
- Sort hints on all features
- Docstrings utilizing Google fashion
- Features underneath 50 strains
- Run `mypy --strict` and `ruff test` earlier than committing
## By no means
- No naked besides clauses
- No sort: ignore feedback
- No mutable default arguments
- No world state
The hot button is being particular. Don’t merely say “observe finest practices.” Level to the precise file that demonstrates the sample. Don’t solely say “deal with errors correctly;” present the error dealing with sample you need.
# Writing Prompts That Level to Examples
Generic prompts produce generic code. Particular prompts that reference your current codebase produce extra maintainable code.
As an alternative of asking AI to “add authentication,” stroll it by way of the implementation with references to your patterns. Right here is an instance of such a immediate that factors to examples:
Implement JWT authentication in src/companies/auth_service.py. Observe the identical construction as UserService in src/companies/user_service.py. Use bcrypt for password hashing (already in necessities.txt).
Add authentication dependency in src/api/dependencies.py following the sample of get_db.
Create Pydantic schemas in src/schemas/auth.py just like consumer.py.
Add pytest exams in exams/test_auth_service.py utilizing fixtures from conftest.py.
Discover how each instruction factors to an current file or sample. You aren’t asking AI to construct out an structure; you might be asking it to use what it is advisable to a brand new function.
When the AI generates code, evaluation it in opposition to your patterns. Does it use the identical dependency injection strategy? Does it observe the identical error dealing with? Does it arrange imports the identical manner? If not, level out the discrepancy and ask it to align with the prevailing sample.
# Planning Earlier than Implementing
AI brokers can transfer quick, which may often make them much less helpful if velocity comes on the expense of construction. Use plan mode or ask for an implementation plan earlier than any code will get written.
A planning step forces the AI to assume by way of dependencies and construction. It additionally offers you an opportunity to catch architectural issues — equivalent to round dependencies or redundant companies — earlier than they’re applied.
Ask for a plan that specifies:
- Which recordsdata will probably be created or modified
- What dependencies exist between elements
- Which current patterns will probably be adopted
- What exams are wanted
Assessment this plan such as you would evaluation a design doc. Verify that the AI understands your venture construction. Confirm it’s utilizing the proper libraries and make sure it’s not reinventing one thing that already exists.
If the plan seems good, let the AI execute it. If not, right the plan earlier than any code will get written. It’s simpler to repair a foul plan than to repair dangerous code.
# Asking AI to Write Exams That Truly Check
AI is nice and tremendous quick at writing exams. Nonetheless, AI is just not environment friendly at writing helpful exams except you might be particular about what “helpful” means.
Default AI check habits is to check the comfortable path and nothing else. You get exams that confirm the code works when every thing goes proper, which is strictly when you don’t want exams.
Specify your testing necessities explicitly. For each function, require:
- Pleased path check
- Validation error exams to test what occurs with invalid enter
- Edge case exams for empty values, None, boundary circumstances, and extra
- Error dealing with exams for database failures, exterior service failures, and the like
Level AI to your current check recordsdata as examples. In case you have good check patterns already, AI will write helpful exams, too. For those who should not have good exams but, write just a few your self first.
# Validating Output Systematically
After AI generates code, don’t simply test if it runs. Run it by way of a guidelines.
Your validation guidelines ought to embrace questions like the next:
- Does it go mypy strict mode
- Does it observe patterns from current code
- Are all features underneath 50 strains
- Do exams cowl edge instances and errors
- Are there sort hints on all features
- Does it use the required libraries appropriately
Automate what you possibly can. Arrange pre-commit hooks that run mypy, Ruff, and pytest. If AI-generated code fails these checks, it doesn’t get dedicated.
For what you can’t automate, you’ll spot frequent anti-patterns after reviewing sufficient AI code — equivalent to features that do an excessive amount of, error dealing with that swallows exceptions, or validation logic combined with enterprise logic.
# Implementing a Sensible Workflow
Allow us to now put collectively every thing we’ve mentioned so far.
You begin a brand new venture. You spend time organising the construction, selecting and putting in libraries, and writing a few instance options. You create CLAUDE.md along with your tips and write particular Pydantic fashions.
Now you ask AI to implement a brand new function. You write an in depth immediate pointing to your examples. AI generates a plan. You evaluation and approve it. AI writes the code. You run sort checking and exams. Every thing passes. You evaluation the code in opposition to your patterns. It matches. You commit.
Whole time from immediate to commit might solely be round quarter-hour for a function that may have taken you an hour to write down manually. However extra importantly, the code you get is simpler to take care of — it follows the patterns you established.
The subsequent function goes sooner as a result of AI has extra examples to be taught from. The code turns into extra constant over time as a result of each new function reinforces the prevailing patterns.
# Wrapping Up
With AI coding instruments proving tremendous helpful, your job as a developer or a knowledge skilled is altering. You are actually spending much less time writing code and extra time on:
- Designing techniques and selecting architectures
- Creating reference implementations of patterns
- Writing constraints and tips
- Reviewing AI output and sustaining the standard bar
The ability that issues most is just not writing code sooner. Reasonably, it’s designing techniques that constrain AI to write down maintainable code. It’s understanding which practices scale and which create technical debt. I hope you discovered this text useful even when you don’t use Python as your programming language of selection. Tell us what else you assume we will do to maintain AI-generated Python code maintainable. Preserve exploring!
Bala Priya C is a developer and technical author from India. She likes working on the intersection of math, programming, knowledge science, and content material creation. Her areas of curiosity and experience embrace DevOps, knowledge science, and pure language processing. She enjoys studying, writing, coding, and low! At present, she’s engaged on studying and sharing her data with the developer neighborhood by authoring tutorials, how-to guides, opinion items, and extra. Bala additionally creates participating useful resource overviews and coding tutorials.
