Out of 25+ independent sources — Reddit threads, YC founder discussions, practitioner write-ups, official docs — one practice appeared in every single one. Not testing. Not git discipline. Not TypeScript strictness.
Context files.
Every AI coding tool has one. In Claude Code it’s CLAUDE.md. In Cursor it’s .cursorrules. In most other tools it’s AGENTS.md. The name doesn’t matter. The concept is everything.
What a Context File Does
It’s the document your AI reads at the start of every session. Without it, you’re re-explaining your stack, your conventions, your folder structure, your preferences — every single time. With it, the AI walks into your project already oriented.
Think of it like onboarding a new contractor. Would you rather explain everything from scratch every morning, or hand them a one-page brief that covers the essentials?
What Goes In It
# Project Context
## What this is
[One paragraph. What the project does and who it's for.]
## Tech stack
- Framework: [your framework + version]
- Styling: [CSS approach]
- Language: TypeScript (strict mode)
- Database: [your DB]
- Deployment: [your platform]
## Key commands
- `npm run dev` — start dev server
- `npm run build` — production build
- `npm run lint` — ESLint check
## Code conventions
- Components: PascalCase
- Utilities: camelCase
- Files: kebab-case
- No `any` types — ever
- Files stay under 500 lines
## Folder structure
- `src/components/ui/` — atomic components
- `src/components/layout/` — layout components
- `src/lib/` — utilities and non-UI logic
- `src/types/` — TypeScript interfaces
## Important rules
- NEVER use `any` in TypeScript
- NEVER hardcode secrets or API keys
- ALWAYS run lint before committing
The 150-Line Rule
This is the counterintuitive part. Surely more context is better?
It isn’t.
Claude and other models have a tendency to quietly deprioritize long context files when they feel only partially relevant to the current task. A 400-line CLAUDE.md gets skimmed. A sharp 100-line one gets followed.
If you notice the AI doing things you’ve told it not to, your context file is probably too long. Prune it.
Rules that aren’t universally applicable don’t belong in the root context file. Put domain-specific rules in nested context files — a CLAUDE.md inside /src/components/ or /docs/supabase/ that only loads when the AI works in that folder.
Context Window Management
The context file solves the start-of-session problem. But sessions degrade over time too.
AI models don’t have memory between sessions. Everything they know is what you’ve put in front of them in this conversation. As conversations grow, older context gets compressed or lost. The AI starts giving inconsistent responses, forgetting decisions, contradicting itself.
The signals your context is degraded:
- AI suggests things it already tried that didn’t work
- Responses feel less precise or more generic
- You’re spending more time correcting than building
- You’ve had to explain the same thing twice
When to start fresh:
- Debugging has stretched past 15–20 messages without resolution
- You’re starting a genuinely new feature
- The AI is producing output that ignores your instructions
The Handoff Protocol
Before ending a productive session:
Before we finish, summarize:
1. What we built
2. What worked and what didn't
3. Current state of the feature
4. What needs to happen next
5. Decisions or patterns to carry forward
Write this to HANDOFF.md.
Next session: Read HANDOFF.md and continue from there.
This takes 30 seconds and saves 15 minutes of re-orientation.
Be a Student of Your Own Code
When AI generates something you don’t understand, don’t just accept it. Ask:
Explain how this file works in plain English.
What does each major section do?
Why is it structured this way?
You don’t need to rewrite the code. You need to understand the architecture — because when it breaks, you need to know enough to point the AI in the right direction.
The PB&J principle applies: if you tell someone “make a sandwich” and they hold the closed bread bag up to the closed jar, they weren’t wrong — you were imprecise. Good AI instructions are almost embarrassingly specific. The quality of your output is a direct function of the quality of your input.
The Compounding Effect
Here’s what happens when you commit your context file to git and maintain it:
- Week 1: AI follows your conventions 60% of the time
- Week 4: You’ve refined the file based on where it drifted. 85% compliance.
- Week 8: The file is tight. New sessions feel like continuing an ongoing conversation. 95%+ compliance.
The context file compounds in value. Every session where you notice a drift and tighten the rules makes every future session better. This is the single highest-leverage investment you can make in your AI coding workflow.
Commit it. Maintain it. Trust the process.