What's a brain file?
A brain file is a markdown file called CLAUDE.md that lives in the root of your project. Claude Code reads it automatically at the start of every session.
Without one, you re-explain yourself every time you open a new session. With one, the AI already knows your codebase, your conventions, your team, and your preferences before you type a single word.
Video walkthrough coming soon
A dedicated video covering the brain file, the layer architecture, and the mistakes that kill performance. In the meantime, this earlier video touches on elements of the workflow.
Future videos in this series will follow the guide format — one level per episode.
The onboarding prompt
Don't write CLAUDE.md by hand. Paste this into Claude Code the first time you open a project. It interviews you, learns how you work, and generates the brain file from your answers.
I'm setting up this project for the first time. I need you to create
a CLAUDE.md brain file so you understand how I work.
Ask me these questions ONE AT A TIME. Wait for my answer before moving on:
1. What's your name and role?
2. What does this project do? (1-2 sentences)
3. What's your main goal with this AI assistant?
(writing code, reviewing PRs, drafting docs, debugging, learning
the codebase, or a mix)
4. What's the tech stack?
5. Are there coding conventions I should follow?
(naming, file structure, testing patterns, commit format)
6. Who are your key collaborators?
7. What words, patterns, or practices do you want me to AVOID?
8. What does "done" look like for your typical task?
After all questions, create a CLAUDE.md in the project root:
## Project Overview
## My Role
## Tech Stack
## Coding Conventions
## Key People
## What I Use This Agent For
## Rules
- Always read this file at the start of every session
- Show me a plan before changing more than 3 files
- Never commit without my approval
- [add rules from my answers]
## Session Workflow
Start: Read CLAUDE.md, check recent git history
Close: Summarize what was done + list open items
Show me what you built and ask if I want to change anything.
Start with question 1.
What happens: Claude Code asks each question, waits for your answer, builds the file, shows you the result. Takes about 5 minutes. Every session after that reads this file automatically.
What a brain file looks like
Yours will be tailored to your project. Here's a stripped-down example.
## Project Overview E-commerce checkout service. Handles cart, payment, confirmation. Monorepo: api, web, shared. ## My Role Senior engineer. Own the payment integration layer. Collaborators: Sarah (frontend), Mike (DevOps), Priya (PM). ## Tech Stack TypeScript, Next.js 14, PostgreSQL, Stripe SDK, GitHub Actions. ## Coding Conventions - camelCase for variables, PascalCase for components - Tests colocated: foo.test.ts next to foo.ts - Commits: feat|fix|chore: short description - Named exports only (no default exports) ## Rules - Read this file at the start of every session - Plan before changing more than 3 files - Never commit without my approval - Run pnpm test before suggesting a PR is ready - Don't add comments to obvious code ## Session Workflow Start: Read CLAUDE.md, run git log --oneline -5 Close: Summarize changes + list open items
The brain file isn't documentation for humans. It's instructions for the AI. Write it like you're onboarding a contractor who follows directions exactly.
The prompting formula
Once your brain file exists, every request follows one shape:
Writing code
Debugging
Learning the codebase
Quick reference
| You want to… | Say something like… |
|---|---|
| Fix a bug | "This test fails: [error]. Bug is probably in [file]. Fix it, keep existing tests passing." |
| Add a feature | "Add email notifications when an order ships. Use the mailer in lib/email.ts. Plan first." |
| Write tests | "Unit tests for api/services/payment.ts. Cover happy path, expired card, network timeout." |
| Review code | "Review this diff. Focus on security, error handling, convention violations." |
| Refactor | "This file is 400 lines. Split into modules. Same public API. Don't change behavior." |
| Understand code | "Explain the middleware chain in api/index.ts. I'm new and lost on the auth flow." |
| Write docs | "README for this project. Setup, architecture, testing. Under 200 lines." |
Six rules
Took months of daily use to arrive at these. Save yourself the loop.
Mistakes you'll make once
What comes next
The brain file is level 1. Here's what the other levels cover.
Level 2 — Making It Stick
Coming Soon- Skills — reusable instruction sets for specific tasks
- Hooks — automated actions before/after tool calls
- Slash commands — shortcuts for common workflows
- Memory — capturing corrections across sessions
Level 3 — Multi-Model Research
Coming Soon- Cross-model chaining — Claude + Gemini + NotebookLM
- Research pipelines — discover, ingest, query with citations
- Dual verification — two models checking each other's work
- Knowledge notebooks — persistent research context
Level 4 — Agent Orchestration
Coming Soon- Custom skill authoring — encode your team's expertise
- Agent teams — parallel agents with coordinated tasks
- Session orchestration — auto-route to the right tool
- Self-improving loops — the system writes its own rules
Start with the brain file.
Level 1 gets you 80% of the value. Copy the prompt, answer the questions, and watch what happens to your next session.