Journal

Stop Repeating Yourself to Claude Code. Use a CLAUDE.md File.

Why Does Claude Code Forget Everything Between Sessions?

Claude Code has no memory between sessions. Every time you start a new session, it does not know your stack, your conventions, or your preferences. A CLAUDE.md file fixes this. Drop it in your project root and Claude reads it automatically at the start of every session. No plugin, no config. It just works.

Every time you open Claude Code, you are starting from zero. Claude does not know you use Supabase for everything. Does not know you hate CSS-in-JS. Does not know you spent yesterday building a dashboard and today you need to wire up the API.

So you spend the first 10 minutes re-explaining context that has not changed since last Tuesday.

That is a waste of your time.

A CLAUDE.md file fixes this. Drop it in your project root, and Claude Code reads it automatically at the start of every session. No setup. No plugin. No configuration. It just works.

I have been using one across every project I build. Client apps, side projects, automation tools. The difference in output quality is night and day. Here is the template I use and why each section exists.

What Should Go in the Project Section?

The project section tells Claude what you are building and where you left off. It includes the project name, a one-liner description, the current phase, and what you worked on last session. This is the only section you customize per project. Everything else stays the same across repos.

## PROJECT
**Name:** [Project Name]
**One-liner:** [What it does in one sentence]
**Current phase:** [MVP / Testing / Production / Redesign]
**Last session:** [What you were working on]

Claude Code has no memory between sessions. Without this, it starts every session guessing what you are building. The “last session” line is the most underrated part. It lets you pick up exactly where you left off instead of re-explaining what you were doing yesterday.

Why Should You Declare Your Tech Stack in CLAUDE.md?

Without a stack declaration, Claude picks whatever it feels like. You say “add auth” and it reaches for NextAuth when you wanted Supabase Auth. You say “style this” and it writes inline CSS when you wanted Tailwind. Declaring your stack once means every suggestion aligns with what you are actually using.

### Stack
- **Framework:** Next.js 14+ (App Router) + TypeScript
- **Styling:** Tailwind CSS + shadcn/ui
- **Backend:** Supabase (PostgreSQL, Auth, Storage, RLS, Realtime)
- **AI:** Claude API / Gemini API (abstracted - swap via env vars)
- **Hosting:** Vercel
- **Version Control:** Git → GitHub → Vercel auto-deploy

Every suggestion, every code snippet, every architectural decision aligns with your actual tools. You write this once and never argue about framework choices again.

How Does a Key Files Map Help Claude Navigate Your Code?

A key files map tells Claude which files matter most in your project. Claude can read your file tree, but a 200-file project has maybe 5 to 10 files that are architecturally important. Listing them upfront tells Claude where to look first instead of wandering through node_modules looking for context.

### Key Files
/app/                    # Pages and routes
/components/             # Reusable UI components
/lib/supabase.ts         # Supabase client
/lib/types.ts            # TypeScript types
.env.local               # Secrets (NEVER commit)

Think of it as a map of your codebase’s critical paths. When Claude knows where the important files live, it makes better decisions about where to put new code and what existing patterns to follow.

What Engineering Preferences Should You Set?

Engineering preferences shape how Claude thinks about your code. This is where you declare your philosophy: systems before tools, MVP first, production quality always, explicit over clever. Without preferences, Claude defaults to “technically correct but not how I would do it.” With them, it writes code that actually matches your style.

## ENGINEERING PREFERENCES

### Philosophy
- Systems before tools - document the workflow, then implement it
- MVP first - ship the simplest version that validates the idea
- Production quality - even MVPs should be well-structured
- Explicit over clever - readable code wins over smart one-liners

If you hate over-engineering, say so. If you want aggressive error handling, say so. Claude follows instructions, but only if you give them. This section is the difference between fighting Claude’s defaults and having it work the way you think.

How Do Code Style Rules Prevent Wasted Rounds With Claude?

Code style rules eliminate the back-and-forth where you ask for a component and Claude writes a class component with .then() chains. Then you ask it to rewrite. Then it uses any everywhere. Then you fix the types. Three rounds of corrections for something that should have been right the first time. Write your style rules once, never argue again.

### Code Style
- TypeScript strict mode - no `any` unless absolutely necessary
- Functional components with hooks - no class components
- Named exports for components, types, and utilities
- One component per file
- Use async/await - no raw .then() chains
- Error handling on every async operation

Style arguments with AI are the biggest time sink in development. Every minute spent re-explaining preferences is a minute you could spend building. This section pays for itself on the first session.

Why Are Architecture Patterns the Most Important Section?

Architecture patterns prevent Claude from making structural decisions you will have to undo later. The most expensive bugs are structural ones: wrong auth pattern, exposed API keys, missing RLS policies. Declaring your patterns upfront means Claude builds on the right foundation from the start instead of guessing and getting it wrong.

### Architecture Patterns
- App Router conventions - server components by default, "use client" only when needed
- Supabase RLS on every table - never rely on frontend-only security
- Environment variables - NEXT_PUBLIC_ prefix only for client-safe values
- API routes for sensitive ops - keep service role keys server-side only
- Component structure: /components/{feature}/{ComponentName}.tsx

A wrong architectural choice in session one becomes technical debt by session three. This section saves you from that. It is the most impactful part of the entire file because structural mistakes are the hardest to fix after the fact.

How Do UI Preferences Change What Claude Builds?

UI preferences tell Claude about your taste, which is impossible to infer from code alone. Claude does not know you prefer dark mode until you tell it. Does not know you hate placeholder text until “Lorem ipsum” shows up in your deployed app. This section bridges the gap between “technically works” and “actually looks like something I built.”

### What I Like
- Dark mode UIs
- Mobile-first responsive design
- Clean minimal interfaces
- shadcn/ui components as the base
- Loading states and error states on everything

### What I Don't Like
- Over-engineering for scale I don't have yet
- CSS-in-JS libraries - Tailwind only
- Default placeholder content left in production
- Console errors or warnings left unhandled

Design taste is personal. Claude is good at following instructions but bad at guessing what you find visually acceptable. Tell it once and every component it generates will match your standards.

What Workflow Rules Keep Claude Code From Breaking Things?

Workflow rules are guardrails that prevent Claude from being too helpful. Without them, Claude will “helpfully” upgrade your dependencies, refactor files you did not ask about, or modify your environment variables. The “Don’t Touch” list is the most important part. It is a fence around the things that will ruin your afternoon if changed.

## WORKFLOW RULES

### Before Making Changes
- Read this file and any /docs folder content for context
- Understand the current state before modifying anything
- If unsure about a decision, ask - don't assume

### While Working
- Test locally with npm run dev before committing
- Run npm run build to catch type errors
- Make small, focused changes - don't refactor outside current scope
- Commit often with clear messages

### Don't Touch
- .env.local - never modify credentials without asking
- Supabase migrations already applied to production
- Existing API routes - unless the task specifically says to
- Package versions - don't upgrade dependencies unless asked

Claude Code is powerful, which means it can break things powerfully. These rules channel that power in the right direction. Think of it as setting boundaries for a very capable but overeager assistant.

How Should You Tell Claude Code to Communicate?

Communication style rules tune how Claude talks to you. Claude defaults to being verbose and diplomatic. If you want blunt answers, you need to say so. If you want it to stop assuming you understand Kubernetes, you need to say so. This section makes the conversation efficient instead of padded with unnecessary preamble.

## COMMUNICATION STYLE
- Be direct - skip the preamble
- Don't assume I know things - explain step by step when needed
- If something is broken, tell me what went wrong and what you did
- When presenting options, give your recommendation and why
- End task summaries with: what changed, what works, what's left

The difference between a frustrating Claude session and a productive one often comes down to communication fit. Some people want detailed explanations. Some want bullet points. Tell Claude which one you are and it adapts.

Do You Need a Docs Folder Structure in Your Project?

A docs folder gives Claude Code deeper project context beyond the CLAUDE.md file. If you use automated task loops where a script feeds Claude tasks sequentially, this structure is what makes it work. Even without automation, having a DECISIONS.md file prevents you from re-debating the same architectural choices every session.

## DOCS FOLDER STRUCTURE
docs/
├── SCOPE.md              # Project scope, goals, constraints
├── DECISIONS.md           # Why we chose X over Y (append-only)
├── ROADMAP.md             # What's next, prioritized
└── tasks/                 # Task files for batch work
    ├── 01-task-name.md
    ├── 02-task-name.md
    └── ...

The DECISIONS.md file is gold. When you choose Supabase over Firebase in week one, write it down with the reasoning. When Claude suggests Firebase in week four, it checks DECISIONS.md first and stays consistent.

How Should You Write Task Files for Claude Code?

Task files force specificity. “Build the dashboard” gives you garbage output. “Create a dashboard page at /dashboard that shows total P&L, win rate, and trade count from the trades table, using shadcn Card components, with a loading skeleton while data fetches” gives you something usable. The template keeps every task clear and testable.

### Task File Template
# [Task Name]

## Goal
[One sentence: what this task accomplishes]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]

## Done When
- [Testable acceptance criteria 1]
- [Testable acceptance criteria 2]
- npm run build passes
- No console errors

Vague tasks produce vague output. This template forces you to define what “done” looks like before Claude starts working. The “Done When” section is especially important because it gives Claude a clear finish line instead of letting it keep tweaking indefinitely.

Why Should You Include a Quick Reference Table?

A quick reference table lists the exact commands for your project so Claude does not have to guess. Claude Code runs commands. If it does not know the right command for your project, it makes assumptions. This table eliminates guessing. It also helps you when you forget the exact Supabase types generation command for the third time this week.

## QUICK REFERENCE
| Action          | Command                                    |
|-----------------|---------------------------------------------|
| Dev server      | npm run dev                                |
| Build check     | npm run build                              |
| Deploy          | git push (Vercel auto-deploys)             |
| Supabase local  | supabase start                             |
| Supabase types  | supabase gen types typescript --local > lib/database.types.ts |

Small detail, big impact. When every command is spelled out, Claude runs the right one on the first try. No more “did you mean npm run dev or yarn dev?” moments.

What Does the Full CLAUDE.md Template Look Like?

Here is the complete template. Copy it, drop it in your project root, fill in the PROJECT section, and adjust the preferences to match how you work. The engineering preferences, code style, and architecture sections reflect my defaults. Change them to match yours.

# CLAUDE.md - Project Configuration

## PROJECT

**Name:** [Project Name]
**One-liner:** [What it does in one sentence]
**Current phase:** [MVP / Testing / Production / Redesign]
**Last session:** [What you were working on]

### Stack
- **Framework:** [Your framework]
- **Styling:** [Your CSS approach]
- **Backend:** [Your backend]
- **Hosting:** [Your hosting]
- **Version Control:** Git → GitHub

### Key Files
/app/                    # Pages and routes
/components/             # UI components
/lib/                    # Utilities, clients, types
.env.local               # Secrets (NEVER commit)

---

## ENGINEERING PREFERENCES

### Philosophy
- Systems before tools - document the workflow, then implement it
- MVP first - ship the simplest version that validates the idea
- Production quality - even MVPs should be well-structured
- Explicit over clever - readable code wins over smart one-liners

### Code Style
- TypeScript strict mode - no `any` unless absolutely necessary
- Functional components with hooks - no class components
- Named exports for components, types, and utilities
- One component per file - colocate styles and types when small
- Use async/await - no raw .then() chains
- Error handling on every async operation

### Architecture Patterns
- Server components by default, "use client" only when needed
- RLS / auth on every data endpoint - never rely on frontend-only security
- Environment variables - public prefix only for client-safe values
- API routes for sensitive operations - keep secret keys server-side
- Component structure: /components/{feature}/{ComponentName}.tsx
- Types in /lib/types.ts or colocated if feature-specific

### What I Like
- Dark mode UIs
- Mobile-first responsive design
- Clean minimal interfaces
- Loading states and error states on everything

### What I Don't Like
- Over-engineering for scale I don't have yet
- Default placeholder content left in production
- Console errors or warnings left unhandled

---

## WORKFLOW RULES

### Before Making Changes
- Read this file and any /docs folder content for context
- Understand the current state before modifying anything
- If unsure about a decision, ask - don't assume

### While Working
- Test locally before committing
- Run build to catch type errors and build issues
- Make small, focused changes - don't refactor outside current scope
- Commit often with clear messages

### Don't Touch
- .env.local - never modify credentials without asking
- Database migrations already applied to production
- Existing API routes - unless the task specifically says to
- Package versions - don't upgrade dependencies unless asked

### Git Conventions
- feat: [description] - new feature
- fix: [description] - bug fix
- refactor: [description] - code improvement
- docs: [description] - documentation
- chore: [description] - tooling, config, deps

---

## COMMUNICATION STYLE

- Be direct - skip the preamble, get to the point
- Don't assume I know things - explain step by step when needed
- If something is broken, tell me what went wrong and what you did
- When presenting options, give your recommendation and why
- End task summaries with: what changed, what works, what's left

---

## DOCS FOLDER STRUCTURE

docs/
├── SCOPE.md              # Project scope, goals, constraints
├── DECISIONS.md           # Why we chose X over Y (append-only log)
├── ROADMAP.md             # What's next, prioritized
└── tasks/                 # Task files for batch work
    ├── 01-task-name.md
    ├── 02-task-name.md
    └── ...

### Task File Template

# [Task Name]

## Goal
[One sentence: what this task accomplishes]

## Requirements
- [Specific requirement 1]
- [Specific requirement 2]

## Done When
- [Testable acceptance criteria 1]
- [Testable acceptance criteria 2]
- Build passes with no errors
- No console errors

---

## SESSION START PROMPT

Read CLAUDE.md and tell me where we left off in one line.

---

## QUICK REFERENCE

| Action          | Command                          |
|-----------------|----------------------------------|
| Dev server      | [your dev command]               |
| Build check     | [your build command]             |
| Deploy          | [your deploy method]             |
| Run tests       | [your test command]              |

How Do You Start Using CLAUDE.md Today?

Getting started takes five minutes. Copy the template above into a file called CLAUDE.md in your project root. Fill in the PROJECT section with your actual details. Adjust the preferences to match your stack and how you write code. Start a Claude Code session. It reads the file automatically. No install, no dependency.

Here is the full process:

  1. Copy the template above into a file called CLAUDE.md in your project root.
  2. Fill in the PROJECT section with your actual project details.
  3. Adjust the preferences to match your stack and how you write code.
  4. Start a Claude Code session. It reads the file automatically.
  5. Update the “Last session” line when you wrap up for the day.

That is it. No install, no config, no dependency. Just a markdown file that makes every Claude Code session start with full context instead of cold.

The 10 minutes you spend writing this file saves you hours of re-explaining yourself. And the code quality difference between “Claude guessing your preferences” and “Claude knowing your preferences” is massive.

Build the system once. Use it everywhere.

Shahab Papoon is an AI & Automation Integrator who builds systems for businesses. He is the co-founder of ConnectMyTech and founder of Keyweemotion. Learn more at shahabpapoon.com.