The AI changed the wrong file again.
I asked it to update a documentation file. It updated the documentation file and silently modified a component in a completely different directory. I only caught it because something looked different in the browser. By the time I traced it back, I'd already accepted the changes.
This wasn't a prompting problem. I'd written a clear, specific prompt. The AI followed the instruction — it just also did something I didn't ask for. And the reason it did that was because it didn't have enough context about which files it should and shouldn't touch.
That incident is what made me build a persistent context system: three files that give the AI a complete, accurate picture of the project before I write a single prompt.
The Three Files
1. .cursorrules — Global Rules for Every Session
This file lives in the project root and loads automatically in every Cursor session. It contains constraints the AI must follow regardless of what I ask it to do.
Here's what mine actually looks like (trimmed):
## Tech Stack — LOCKED. Do not change or upgrade.
- Next.js 16.1.6 (App Router only — never Pages Router)
- React 19.2.3 with React Compiler enabled
- TypeScript strict mode — NO any types, ever
- Tailwind CSS v4 only — NO tailwind.config.js
## TypeScript Rules — CRITICAL
- Strict mode is ON — every variable, parameter, and return type must be explicitly typed
- No any types — use unknown, proper interfaces, or type narrowing instead
- catch (error) blocks must type-check error as unknown
## React Rules — CRITICAL
- React Compiler is enabled — NEVER use useMemo or useCallback
## File Structure Rules
- Four backend routes exist: generate, checkout, verify, portal
— do not add more without explicit approval
- No new files or components unless explicitly requested
## What Must Never Be Changed
- Core request execution logic (handleSendRequest)
- JWT verification logic in generate/route.ts
- localStorage keys: apibuilder_pro_token, apiBuilderSavedRequests
The key insight: these aren't preferences. They're constraints that prevent the AI from making decisions I've already made. Without this file, every session starts from scratch. The AI might decide to add useMemo because that's what it learned from training data. It might create a tailwind.config.js because that's how Tailwind v3 worked. It might add a new API route when I only asked it to modify an existing one.
The .cursorrules file turns "don't do that" conversations into rules the AI follows before I say anything.
2. CONTEXT.md — Architectural Context per Session
This is the file I paste at the start of every Cursor session. It gives the AI a snapshot of the project's current state — what's built, what the architecture looks like, and how the pieces connect.
The structure:
## What This Project Is
[One paragraph: what it does, who it's for, how it makes money]
## Tech Stack
[Specific versions, specific patterns, specific constraints]
## File Structure
app/
├── api/generate/route.ts ← AI generation endpoint
├── api/checkout/route.ts ← Stripe Checkout
├── builder/page.tsx ← Main app UI
├── page.tsx ← Landing page
└── layout.tsx
## Current State
[What's been built, what each major component does,
what state variables exist, what the data flow looks like]
## Key Constraints
[What not to do, what not to change, what's off limits]
This prevents the most expensive category of AI mistakes: wrong assumptions. Without this file, the AI guesses at your architecture. It might assume you're using the Pages Router when you're on App Router. It might assume you have a database when everything is in localStorage. It might assume page.tsx is the landing page when it's actually at /builder.
Every one of those wrong assumptions produces code that compiles, looks correct, and breaks something subtle.
3. Master Document — Full Project History
This is the longest file and the least frequently referenced. It contains the complete project history: every major decision, every week's progress, every architectural choice and why it was made. I don't paste it into Cursor — it's too long. I paste it into Claude.ai when I need strategic advice or when I'm planning a major feature.
Its purpose is continuity across sessions. AI has no memory between conversations. The master document is the memory. When I start a new Claude.ai session and say "here's where we left off," this document is what I paste.
Why This Works Better Than Better Prompts
The standard advice for AI coding is "write better prompts." Be more specific. Add more detail. Include edge cases. That advice is correct but incomplete.
The problem with relying only on prompts is that you have to remember every constraint, every architectural decision, and every "don't touch this" rule every single time you write a prompt. You will forget. The AI will do something you didn't want. You'll spend 20 minutes figuring out what changed.
Context files move those constraints out of your memory and into the environment. The AI reads them before it reads your prompt. The rules are applied before you have a chance to forget them.
Since setting up this system, the AI has not modified a file I didn't ask it to modify. The TypeScript strict mode errors that plagued my first week disappeared because "no any types" is in the rules file, not in my head. The architecture stays consistent because the AI knows the architecture before I ask it to build anything.
The breakthrough wasn't learning to write better prompts. It was learning to design a better environment for the AI to work in.
This system was developed while building APIBuilderHQ, a browser-based API client shipped in 5 weekends using AI coding tools. The .cursorrules and CONTEXT.md excerpts above are from the real project.
