If you use Cursor, Claude, or any AI coding assistant, you've probably experienced this: the AI writes code that works, but it doesn't fit. Wrong naming conventions, unfamiliar error patterns, random library choices.
After a few months, your codebase looks like it has 12 different authors.
I stumbled onto a fix so obvious I'm embarrassed it took me this long.
The Problem
Every AI session starts fresh. The AI doesn't know:
- Your naming conventions
- Which libraries you prefer
- How you handle errors
- What patterns you've already established
- Project-specific context (locales, domain concepts, etc.)
So it guesses. And it guesses differently every time.
The Fix: Project DNA
Create a CONTEXT.md file in your project root. I call it "Project DNA" because it's the core identity of your codebase that AI needs to understand.
Here's mine for Doc2Pay (a SaaS I'm building for Ukrainian accountants):
## PROJECT: Doc2Pay — Invoice Recognition SaaS
## STACK: Next.js 14, Prisma, PostgreSQL, tRPC, Zod
## PATTERNS: Repository pattern, always validate at boundary, Zod schemas for all external data
## ERRORS: Custom AppError class. Always log then rethrow. Never silent catches.
## NAMING: camelCase for vars/functions, PascalCase for components/classes, SCREAMING_SNAKE for constants
## NEVER: Raw SQL queries, magic strings, `any` types, console.log in production
## ALWAYS: Ukrainian locale for dates (uk-UA), UAH for currency display, i18n keys for user text
## DOMAIN: invoices, agencies, accountants, PrivatBank API, tax declarations
10 lines. Changes everything.
How to Use It
With Cursor: Just create the file. Cursor reads it automatically as part of its project context system. No extra setup needed.
With Claude/ChatGPT: Paste it at the start of each session before your actual request.
With GitHub Copilot: Add it as a .github/copilot-instructions.md file — same concept, different path.
Real Results
Before CONTEXT.md:
- AI PR review comments: 20+ per session
- Time fixing AI style issues: 15-20 min per feature
- Codebase consistency: non-existent
After:
- AI PR review comments: 2-3 max
- Time fixing AI style issues: less than 5 min
- Codebase consistency: actually exists
What to Put In Yours
The most impactful sections:
| Section | What to include |
|---|---|
| STACK | Exact libs and versions you use |
| NAMING | Your specific conventions |
| ERRORS | How you handle them |
| NEVER | Rules the AI breaks constantly |
| ALWAYS | Things you always want to see |
| DOMAIN | Business concepts AI wouldn't know |
The Deeper Insight
AI doesn't need to be smarter. It needs context.
You wouldn't hire a senior developer, give them zero onboarding, and expect them to write code that fits your team's patterns. Same logic applies to AI.
Project DNA is the onboarding doc for your AI assistant.
I'm building SnakeFlow, a free open-source VS Code extension for managing your entire dev environment (Docker, servers, Git, quality checks, GitHub PRs) from one sidebar panel. Check it out: github.com/vaulttec-dev
Top comments (0)