Stop Wasting Tokens on Context You Already Know
Every new AI session starts with zero memory. Without a structured brief, you spend the first 20 messages re-explaining your project — and your AI still hallucinates the wrong stack. Here's the fix.
Why Context Management Matters
Memory Resets
Cursor, Lovable, Windsurf — none of them remember your project between sessions. Every new tab is a blank slate.
Hallucinations
Without context, your AI assumes generic patterns. It'll suggest Pages Router when you're on App Router.
Wasted Tokens
Re-explaining your project wastes your first 2,000 tokens. Worse — the AI breaks code you told it not to touch.
The CONTEXT.md Template
Drop this into your project root for instant alignment.
# CONTEXT.md — Project Brief
## Project Name
[Your App Name] — [One-line description, e.g. "SaaS for indie hackers to track MRR"]
## Tech Stack
- **Frontend:** Next.js 14 (App Router), TypeScript, Tailwind CSS
- **Backend:** Supabase (Postgres + Auth + Storage)
- **Payments:** Stripe
- **Deployment:** Vercel
- **Package Manager:** npm / pnpm / bun
## Current Task
> What you're working on RIGHT NOW in this session.
- [ ] Building the user dashboard page
- [ ] Fixing auth redirect bug after Google sign-in
- [ ] Adding Stripe webhook for subscription events
## What NOT To Touch
- `/app/api/stripe/` — working perfectly, do not modify
- `middleware.ts` — auth logic is correct, leave it alone
- `lib/supabase/client.ts` — stable config, no changes needed
- Production environment variables — never hardcode or expose
## Known Issues
- [ ] Dark mode flicker on first load (not a priority this sprint)
- [ ] Mobile nav doesn't close on route change (tracked in Notion)
- [ ] Stripe webhook occasionally fires twice — idempotency key added, monitor
## File Structure Overview
```
/app
/dashboard ← protected routes
/api
/stripe ← webhook handlers
/auth ← Supabase auth helpers
/components
/ui ← shadcn/ui primitives
/shared ← reusable app components
/lib
/supabase ← client + server helpers
/stripe ← stripe helpers
/types ← shared TypeScript types
```
## Key Conventions
- All server actions live in `/app/actions/`
- Use `createServerClient` for server components, `createBrowserClient` for client
- Tailwind only — no custom CSS unless absolutely necessary
- Zod for all form validation
- Error handling: toast for user-facing, console.error + Sentry for logging
## Recent Decisions
- Chose Supabase over Firebase for row-level security
- Using App Router (not Pages) — don't suggest pages/ patterns
- Stripe Checkout (hosted) over Elements for speed
## Session Goal
By the end of this session I want to: [specific, measurable outcome]
Execution Strategy
Sync After Decisions
Update it whenever you make an architectural decision, add a new dependency, or complete a major feature. Treat it like a changelog for your AI.
Modular Context
For larger projects, create feature-specific files like CONTEXT.auth.md. Paste only what's needed to prevent token bloat and keep logic sharp.
Cursor Rules Hybrid
Combine with .cursorrules. Use rules for style and CONTEXT.md for project state. This 1-2 punch virtually eliminates hallucinations.
Define No-Go Zones
Explicitly list stable files in 'What NOT To Touch'. Think of it as fencing off landmines before handing the shovel to your AI.
Post-Session Debrief
Spend 2 minutes updating 'Current Task' before closing. Your future self will start with full context instead of catching up.
Full Compatibility
Standardized for every major AI coding engine.
Master Your Context
Ready to Build at 10x Speed?
CONTEXT.md is just the start. Join the structured build challenge to go from idea to deployed product without losing your mind.
Take the Challenge