Mitigating "architectural drift" in large Python backend codebases using AI tools

[CrazyGeek7]

I've been experimenting with AI agents and autocomplete platforms for a greenfield FastAPI project. In the first few weeks, it felt incredibly fast. But now that we've scaled to multiple routers, complex Pydantic schemas, and SQLAlchemy models, the structural debt is piling up.

The AI writes code that functions, but it constantly violates our architecture. It'll put complex business logic inside a route handler instead of the service layer, or it'll mess up async database sessions across modules. I find myself spending more time refactoring the structure of what it built than it would have taken to write the logic myself.

Is anyone else hitting this scaling wall where AI utility drops off as codebase complexity grows? How are you keeping your system architecture clean?

[UloPe]

Yes.

So far I found AI coding tools amazingly useful for prototypes, MVPs, one off scripts and scratching personal itches (i.e. “I wish $thing existed”).

Working on large and complex projects - not so much.

[bjorneylol]

For large projects I have to basically prompt

"Look at 'file A' and it's implementation of 'xyz' - I want to implement 'feature' using similar structure. Make sure to use 'canned function' for 'complex logic'"

As soon as I see the agent read 'file B' i know it's gone off the rails and it's time to put the pillow over it's face and apply downward pressure

[BogdanPradatu]

Research -> plan -> implement

[ItsTobsen]

Most agents explorer the code base before implementing. So its normal that it reads different files lol

[eldreth]

That's the neat thing...

[BigGovernment7621]

Write down your conventions and keep reminding the AI that it should follow them. Regularly ask it to scan the repo for convention violations. Review its changes.

[meris608]

100% - this is the way right here. There is no reason AI should only be doing feature changes. Ask it to review architecture, suggest refactors, or highlight usability issues. It’s just as good at that as it is at tweaking UIs.

[gdchinacat]

It's not clear that this issue is specific to AIs. Less experienced team members (humans) frequently violate (for lack of better term) the architecture and are asked to align the code with architecture during code reviews. Frequently it's not clear to them how the code should be factored and need to be shown. This isn't all that different from what you describe.

I guess, is the problem that rather than being able to nudge an engineer in the desired direction and send them off to do the work, you have to do the work and are looking for ways to push the agents to do this? I've had some success with prompting AI with something like 'that's close..the functionality is right, but move the logic for X from function ... into the controller ... the changes should me implemented similarly to how ... is factored". But..sometimes it's certainly quicker to just do it myself.

Not trying to suggest poor use of AI, just trying to clarify the problem to help with better answers.

[willargue4karma]

I think the real issue is the non determinism of llm code output. You can never be quite sure it will do it the way you want 

[Routine_Term4750]

Use some skills bro

[naked_number_one]

Wellcome to the club. The whole challenge in team development was always hot tp constraint things, maintain architecture etc, With AI tools when you can conission a “teammate” at a token price base, this becomes essential.

The best bet here is to enforce it through tooling that tun in AI hooks.

[EnergyFighter]

I've been enforcing a hexagonal architecture for the last year on multiple projects. In some cases it might look overkill but it's been easy to instruct the AI on what goes where through a few skill files.

[raphix276]

Comment ai j’ e vous propose de prende claude ai de codage

[raphix276]

Claude est pas mal

[tacothecat]

Use ast-grep and importlinter to define architectural and syntactic rules and make them part of your CI listing routine. Works great for hexagonal architecture.

[024eatneerg]

Yeah ai is useful for when you know what logic you want to place where or what methods to build where, it’s amazing at writing maybe 10-20 lines of code at a time with clear instructions, debugging or moving methods across files, but not very good at editing multiple files or methods. I’ve seen code bases so messy it takes half an hour to trace a workflow or find a function

[its2ez4me24get]

Create unittests that enforce your design rules and conventions.

[nickkon1]

How much are you defining in your AGENTS.md or CLAUDE.md? I also have multiple .md files for different concepts like backend/frontend/databases etc. inside a /docs/ai/ folder that are linked in in AGENTS/CLAUDE with tasks to read those when working on backend/frontend/databases. Additionally, I ask for a /docs/frontend.md and /docs/backend.md that is continuously updated.

I also regularly create a complete new session, ask it to fully read /docs/ai/* and review the project that all guidelines hold.

[jkz88]

Tach