Every time I start a new AI coding session, I waste the first 15 minutes re-explaining my project. The stack, the conventions, the weird edge cases. Again and again.
So I built a 10-minute onboarding flow that eliminates that ramp-up entirely. Here's exactly how it works.
The Problem: Context Amnesia
AI assistants don't remember your project between sessions. Even if you had a brilliant conversation yesterday, today's session starts from zero.
Most developers handle this by:
- Pasting random files into the chat and hoping for the best
- Writing a novel-length prompt every morning
- Just accepting bad first answers
All three waste time. There's a better way.
The 10-Minute Onboarding Document
I keep a single file called PROJECT.md at the root of every repository. It's written specifically for an AI assistant to read — not for humans.
Here's the template:
# Project: [Name]
## What This Is
[2-3 sentences. What does this project do? Who uses it?]
## Stack
- Language: [e.g., TypeScript 5.4]
- Framework: [e.g., Next.js 14 with App Router]
- Database: [e.g., PostgreSQL via Prisma]
- Testing: [e.g., Vitest + Playwright]
## Architecture (3 sentences max)
[How is the code organized? What are the key directories?]
## Conventions
- [Naming: camelCase for files, PascalCase for components]
- [Error handling: always use Result<T, E> pattern]
- [Tests: co-located in __tests__ folders]
## Current State
- Last major change: [what and when]
- Known issues: [list active bugs or tech debt]
- Next milestone: [what you're working toward]
## Things That Will Trip You Up
- [The auth middleware runs BEFORE route matching]
- [Don't use default exports — the bundler breaks]
- [The \`user\` table has a soft-delete column]
Why This Works
Three reasons:
1. It's read-optimized for LLMs. Short sentences, bullet points, no ambiguity. An AI can parse this in a single pass and build an accurate mental model.
2. It captures the "gotchas." The "Things That Will Trip You Up" section is the most valuable part. These are the things that take a human developer days to discover — and they'll cost an AI assistant dozens of wrong answers if it doesn't know them upfront.
3. It's cheap to maintain. I spend 2 minutes updating it after any significant change. That's it. The document stays small because it's not documentation — it's a briefing.
How I Use It in Practice
At the start of every AI session, my first message is:
Read PROJECT.md and confirm you understand the project,
the stack, and the gotchas. Then I'll give you today's task.
The assistant reads the file, gives a brief summary, and we're off. No 15-minute ramp-up. No wrong assumptions about the database schema. No suggestions to use a library we explicitly avoid.
The 10-Minute Setup
If you don't have a PROJECT.md yet, here's how to create one in 10 minutes:
- Minutes 1-2: Write the "What This Is" and "Stack" sections from memory
- Minutes 3-4: Open your project root — list the key directories in "Architecture"
- Minutes 5-6: Write your "Conventions" from the last code review you did
- Minutes 7-8: Fill in "Current State" — what changed recently, what's broken
- Minutes 9-10: Write the "Gotchas" — the things that surprised you or your teammates
Done. You now have a document that saves 15 minutes per session, every session.
Beyond the Basics
Once the onboarding doc is working, I layer on two extras:
Session goals. I add a ## Today section at the bottom with 1-3 specific tasks. This focuses the assistant from the first message.
Evolving context. After each significant session, I update the "Current State" section. The document becomes a living project journal that any assistant (or new team member) can pick up.
Try It Today
Pick one project. Spend 10 minutes writing the PROJECT.md. Start your next AI session with "Read PROJECT.md first."
You'll feel the difference immediately.
The cost is trivial. The payoff compounds every single day.
Top comments (0)