Project Anatomy
How to structure a vibe-coding project.
A vibe-coding project looks like a regular codebase — with one important addition: a context layer for the AI. These are plain text files that tell your AI assistant what you're building, what decisions you've made, and how it should behave. The source code structure changes by technology; this layer stays the same everywhere.
The generic structure
Works regardless of which tech stack you use.
What each file does
BRIEF.md
The most important document. Describes what you're building, for whom, main requirements, and chosen stack. Give it to the AI at every session as starting context.
CONTEXT.md
The logbook. Keep track of every decision made, problem solved, shortcut used. It helps the AI not contradict you and not forget what you've already decided.
RULES.md / .cursorrules
The rules of behavior for your AI assistant. Here you write "don't add useless comments", "always use strict TypeScript", "components go in src/components". The filename changes based on the tool you use.
docs/
Relevant snippets from the docs of libraries you use. The AI doesn't know the latest versions — pasting the parts you use reduces errors and hallucinations.
prompts/
The prompts that worked well. If you found the perfect way to ask the AI to do something, save it. You will reuse it, and need it more than you think.
src/
The actual code. The internal structure changes completely based on the technology you use — see below for specific examples.
Tech-specific variations
The AI context part is always the same. What changes is the code structure inside src/ — or equivalent.
Practical tips
Always start from BRIEF.md
Before writing a single line of code, write what you're building. Two paragraphs are enough. The AI needs it so it doesn't go in the wrong direction.
The rules file name changes based on the AI tool
On Cursor it's .cursorrules, on Claude Code it's CLAUDE.md, on Windsurf it's .windsurfrules. The concept is the same: permanent rules of behavior for your AI.
Save prompts that work
When you find the right way to ask the AI something, copy the prompt into prompts/. Reusing it is faster than rewriting, and it works better than you think.
Don't put secrets in MD files
BRIEF.md and CONTEXT.md go into git. Do not write API keys, passwords, or sensitive data in them. For those always use .env (and add it to .gitignore).
Update CONTEXT.md after each session
Take 2 minutes at the end of each work session to note down what you decided and why. The next session — or the next AI — will thank you.