How I Made AI Stop Hallucinating on Our 3-Year-Old Fintech Codebase
AI coding tools fail on real production projects. They work on new code but fall apart on old codebases with history.
I learned this the hard way with our fintech project. We have two React frontends, an admin panel, and a FastAPI backend. Our database is complex. It holds sensitive financial and user data.
We tried using AI to move faster. It failed immediately.
I asked the AI to create a contacts table. It created new columns for names and emails. These columns already existed in our users table. The AI duplicated data instead of using a foreign key. It had no idea our users table existed.
I stopped asking how to make AI write better code. I started asking what the AI needs to know to make good decisions.
AI is only as good as the context you give it. We made our context explicit and authoritative. Here is the system we built:
• ADR Files: We created a docs/adrs/ folder. These files record why we make architectural decisions. One file (ADR-001) tells the AI: "Check existing tables first. Use foreign keys. Never duplicate user data."
• context.md: This file explains our specific terms. It tells the AI how different concepts relate to each other in our system.
• plot.md: This is a high-level map. It shows how the different pieces of our project connect.
• Strict Rules: We told the AI that the docs directory is the ultimate authority. It must follow these rules in order.
• Mandatory Tests: Every new API route must have test cases.
This system makes AI predictable.
Once, the AI changed a shared function that broke eight other parts of the app. Because we had tests, the AI saw the failures. It fixed its own mistake by creating a new version of the function that handled both old and new requirements. Without tests, that bug would have reached production.
Stop blaming AI for not knowing your codebase. Treat it like a new hire. You do not blame a new hire for not knowing your rules. You give them documentation and onboarding.
Our structure looks like this:
docs/
- context.md (Terms and connections)
- plot.md (High-level map)
- adr/ (Specific rules like table creation or API structure)
Three tips for your workflow:
- Be specific in your ADRs. Use clear instructions instead of vague advice.
- Make docs authoritative. Tell the AI these rules come first.
- Turn mistakes into rules. Every time the AI fails, create a new ADR to prevent it.
This does not make AI perfect. It makes it consistent.
Optional learning community: https://t.me/GyaanSetuAi