Every time I start a new project with an AI assistant, I used to spend the first 20 minutes re-explaining everything: the tech stack, the coding style, the project structure, what we tried yesterday.
Then I started keeping 5 files at the root of every project. Now my assistant is productive in under a minute.
The 5 Files
1. PROJECT.md — What This Thing Is
A one-paragraph summary plus the current state:
# Widget Dashboard
React + TypeScript frontend, Express API, PostgreSQL.
Currently: MVP is deployed. Working on user auth (OAuth2 via Google).
Last session: finished the login flow, need to add refresh tokens.
This replaces the "okay so this is a React app and we're building..." preamble. The assistant reads it and knows where we are.
2. STACK.md — Versions and Dependencies
- Node 20.11, TypeScript 5.3
- React 18.2, Vite 5.1
- Express 4.18, Prisma 5.8
- PostgreSQL 16
- Testing: Vitest + Playwright
- Formatting: Prettier (2-space indent, no semicolons)
This prevents the assistant from generating code for the wrong library version. It's the difference between openai.ChatCompletion.create() and client.chat.completions.create().
3. CONVENTIONS.md — How We Write Code Here
- Functional components only, no classes
- Use `zod` for all input validation
- Error responses: { error: string, code: number }
- File naming: kebab-case for files, PascalCase for components
- No barrel exports (index.ts re-exports)
- Tests live next to source: `widget.ts` → `widget.test.ts`
Without this, the assistant defaults to whatever patterns were most common in its training data. Which is usually a mix of everything.
4. DECISIONS.md — Why We Did It That Way
## 2024-03-15: Chose Prisma over Drizzle
- Need: quick schema iteration for MVP
- Prisma's migration tooling is more mature
- Will revisit if query performance becomes an issue
## 2024-03-20: No Redux
- App state is simple enough for React Context + useReducer
- If we need global state beyond auth, reconsider
This is the one most people skip. It's also the one that prevents the assistant from suggesting "have you considered switching to Drizzle?" every other session.
5. TODO.md — What We're Doing Right Now
## Current Sprint
- [x] Google OAuth login flow
- [ ] Refresh token rotation
- [ ] Session middleware (attach user to req)
- [ ] Protected route wrapper component
## Next Up
- Dashboard data fetching (SWR or React Query)
- Role-based access control
This is your shared task list with the assistant. When you start a session with "let's continue," it knows exactly where to pick up.
How I Use Them
At the start of every session, I paste or reference these files:
Read PROJECT.md, STACK.md, CONVENTIONS.md, DECISIONS.md, and TODO.md.
Then pick up the next unchecked item in TODO.md.
That's it. No 10-minute context dump. No "remember when we..." conversations.
Maintenance
- PROJECT.md — update when the project phase changes
- STACK.md — update when you add or upgrade a dependency
- CONVENTIONS.md — update when you make a new style decision
- DECISIONS.md — update when you make an architectural choice
- TODO.md — update every session (the assistant can do this for you)
Total maintenance: maybe 2 minutes per day. Time saved: easily 20+ minutes per session.
Why This Works
AI assistants are stateless. Every session starts from zero. These 5 files are the minimum viable context to get back to full speed.
Think of it like onboarding a new developer — except you do it every single day. The better your onboarding docs, the less ramp-up time you waste.
The best part: these files aren't just useful for AI. They're useful for you. A month from now, you'll open DECISIONS.md and thank yourself.
What files do you keep in your AI-assisted projects? I'm always looking to steal good ideas — share yours in the comments.
Top comments (0)