Sign in Subscribe

Day 3: CLAUDE.md — Give Claude Code a Permanent Briefing

If you only do one thing after reading this series, create a CLAUDE.md file. It's the single highest-impact change you can make.

Day 3: CLAUDE.md — Give Claude Code a Permanent Briefing

Hey, it's G.

Day 3 of the Claude Code series.

Today I learned about the single file that will save you more time than anything else in your Claude Code setup.

CLAUDE.md — the permanent briefing that Claude reads automatically every session.

Let me show you why this matters and how to set it up in 5 minutes.

The Problem (Claude Has Zero Memory)

Here's what happens without CLAUDE.md:

You start a Claude Code session on Monday:

> You are working on a Next.js 14 app using Supabase for auth. 
> We use named exports only, no default exports. 
> Styling is Tailwind, no inline styles. 
> Now add a login page.

Claude does it perfectly.

Tuesday, you start a new session:

> Add a signup page

Claude creates it with default exports and inline styles.

Why? No memory. Every session starts fresh. Zero context.

You have to re-explain your project every single time.

CLAUDE.md fixes this permanently.

What Is CLAUDE.md? (The Concept)

CLAUDE.md is a plain markdown file that lives at the root of your project.

What makes it special:

Claude Code reads it automatically at the start of every session. You don't ask. You don't prompt. It just reads it.

What you put in it:

  • What the project is
  • Tech stack
  • Folder structure (key folders)
  • Coding conventions
  • Things to never do
  • Useful commands

The result:

Every time you start Claude Code, it already knows your project like a developer who just read the onboarding docs.

The analogy:

Without CLAUDE.md: Hiring a new contractor every day and briefing them from scratch.

With CLAUDE.md: Working with the same contractor who already knows your house, your preferences, and your rules.

How To Set It Up (5 Minutes)

Step 1: Create the File at Your Project Root

touch CLAUDE.md

That's it. One file at the root of your project.

Step 2: Open It in VS Code

code CLAUDE.md

Or just open it manually in your editor.

Step 3: Write Your Briefing

Here's what to include:

Section 1: What This Project Is

# My Project

## What This Is
A thumbnail generation SaaS. Users paste a YouTube URL and get 
a styled thumbnail in under 1 minute.

Keep it to 1-2 sentences. Just the high-level concept.

Section 2: Tech Stack

## Tech Stack
- Next.js 14 (App Router)
- TypeScript
- Supabase (auth + database)
- Tailwind CSS
- Vercel (deployment)

List everything Claude needs to know to make smart decisions.

Section 3: Key Folders

## Key Folders
- /app → all routes and pages
- /components/ui → reusable UI components
- /lib/supabase.ts → Supabase client config
- /utils → helper functions

You don't need every folder. Just the ones Claude will work in most.

Section 4: Coding Conventions

## Coding Conventions
- Functional components only, no class components
- Named exports only, never default exports
- Use Tailwind for all styling, no inline styles
- TypeScript strict mode — no `any` types

This is where you prevent the most common mistakes.

Examples from my projects:

  • "Always use the existing Button component, never create new button styles"
  • "API routes must include error handling with our standard error response format"
  • "All dates should use our formatDate util from /utils/dates.ts"

Section 5: Never Do This

## Never Do This
- Don't install new dependencies without asking me first
- Don't modify /lib/supabase.ts
- Don't change existing component APIs without flagging it

This section is critical.

It's the difference between Claude making helpful changes and Claude breaking your entire auth system because it "improved" your Supabase config.

Section 6: Useful Commands

## Useful Commands
- `npm run dev` → start local dev server
- `npm run build` → production build
- `npm run lint` → run ESLint

Not strictly necessary, but helpful when you ask Claude to test changes.

Step 4: Verify It Worked

Start Claude Code and ask:

claude

> What do you know about this project?

If it summarizes your CLAUDE.md back to you, you're set.

It should mention your tech stack, conventions, and folder structure without you having to explain.

Real Example (My Actual CLAUDE.md)

Here's what I use for Resiboko (my expense tracker):

# Resiboko

## What This Is
AI-assisted expense tracker for average Filipinos. 
Users scan receipts or chat with AI to log expenses in seconds.

## Tech Stack
- Next.js 14 (App Router)
- TypeScript (strict mode)
- Supabase (auth, database, storage)
- Tailwind CSS (no custom CSS allowed)
- shadcn/ui components
- Vercel (deployment)

## Key Folders
- /app → App Router pages and layouts
- /components/ui → shadcn/ui components (don't modify)
- /components/custom → our custom components
- /lib/supabase.ts → Supabase client (don't touch)
- /utils → helper functions
- /types → TypeScript types

## Coding Conventions
- Functional components only
- Named exports only (no default exports)
- Tailwind utility classes only (no inline styles, no custom CSS)
- TypeScript strict mode (no `any` types)
- All API routes must include try/catch with standard error format
- Use existing UI components from /components/ui before creating new ones

## Never Do This
- Don't install new dependencies without explicit permission
- Don't modify /lib/supabase.ts or auth configuration
- Don't change component APIs without discussing first
- Don't add custom CSS files
- Don't use default exports

## Useful Commands
- `npm run dev` → local dev server (port 3000)
- `npm run build` → production build
- `npm run lint` → ESLint check
- `npx supabase status` → check Supabase connection

## Common Tasks
- Logging expenses: Use the ExpenseForm component
- Receipt scanning: OCR handled by /api/scan-receipt route
- Date formatting: Use formatDate() from /utils/dates.ts
- Currency: Always display in PHP (₱)

Why This Actually Matters

CLAUDE.md is the highest ROI thing you can do when setting up Claude Code on a project.

Time investment: 5 minutes to write

Time saved: Every single session for the life of the project

What changes:

Before CLAUDE.md:

  • Every session: "You're working on a Next.js app using Supabase..."
  • Repeated explanations of conventions
  • Claude makes the same mistakes repeatedly
  • You spend time correcting instead of building

After CLAUDE.md:

  • Every session: Claude already knows everything
  • Zero repeated explanations
  • Mistakes drop dramatically
  • You focus on features, not corrections

The math:

If you save 2 minutes per session explaining context, and you use Claude Code 5 times a week:

  • 10 minutes saved per week
  • 40 minutes saved per month
  • 8 hours saved per year

Per project.

Best Practices (What Actually Works)

1. Keep It Honest

Don't write aspirational conventions that don't match your actual code.

❌ Bad:

## Coding Conventions
- We write comprehensive tests for everything

Reality: You have zero tests.

What happens: Claude writes tests you don't use and can't maintain.

✅ Good:

## Coding Conventions
- No tests yet (we'll add them later)
- Focus on working features first

Why: Claude adapts to your actual workflow, not your ideal one.

2. Start Simple, Add As You Go

Don't try to write the perfect CLAUDE.md on day one.

Start with:

  • Project description
  • Tech stack
  • Key conventions

Add later when you notice Claude making the same mistake:

  • "Claude keeps adding default exports" → Add "Named exports only" to CLAUDE.md
  • "Claude modifies my Supabase config" → Add "Don't touch /lib/supabase.ts" to Never section

Let the file grow organically from real usage.

3. Be Specific About "Never Do This"

Vague warnings don't work.

❌ Vague:

- Don't break things
- Don't make bad changes

✅ Specific:

- Don't install new dependencies without asking first
- Don't modify /lib/supabase.ts
- Don't change existing component APIs without flagging it

4. Update It When Your Stack Changes

CLAUDE.md should reflect your current project, not your project 3 months ago.

When to update:

  • Switch from Pages Router to App Router
  • Add a new major dependency (Prisma, tRPC, etc.)
  • Change styling approach (Tailwind → CSS Modules)
  • Adopt new conventions (default exports → named exports)

Set a reminder: Monthly quick review of CLAUDE.md to verify it's still accurate.

Common Mistakes (What Not to Do)

Mistake 1: Making It Too Long

Problem: 500-line CLAUDE.md with every possible detail.

Reality: Claude reads it, but longer = more noise for less signal.

Solution: Keep it under 100 lines unless you have a truly massive project.

Mistake 2: Treating It Like Documentation for Humans

Problem: Writing it like a README with installation instructions, contributing guidelines, etc.

Reality: CLAUDE.md is for AI, not humans. Focus on what Claude needs to write code correctly.

Solution: Separate file for human documentation. CLAUDE.md is AI-only.

Mistake 3: Never Updating It

Problem: Created once, never touched again, becomes outdated.

Reality: Your project evolves. Your CLAUDE.md should too.

Solution: Monthly review. Add notes when Claude makes repeated mistakes.

My Raw Notes (Unfiltered)

No memory between sessions = painful without this. Write it once, benefit forever.

Keep it honest — if you write things that aren't true about your project it confuses Claude.

Treat it like your actual project README but written for an AI dev not a human.

Don't overthink it. Start simple and add to it as you notice Claude making the same mistakes.

Best ROI file in my entire Claude Code setup. 5 minutes to create, saves hours over project lifetime.

Tomorrow (Day 4 Preview)

Topic: Understanding Claude Code's file system access — what it can see, what it can't, and how to work with it.

What I'm testing: Nested directories, hidden files, node_modules, and whether Claude can read everything or if there are blind spots.

Following This Series

Daily updates for 30 days. Each day builds on the last.

So far:

  • Day 1: Setup and installation
  • Day 2: Prompting that actually works
  • Day 3: CLAUDE.md permanent briefing (today)
  • Day 4: File system access (tomorrow)

G

P.S. - If you only do one thing after reading this series, create a CLAUDE.md file. It's the single highest-impact change you can make.

P.P.S. - My CLAUDE.md for Resiboko is 87 lines. That's it. You don't need a novel. You need clarity.

P.P.P.S. - If you're already using CLAUDE.md, drop what sections you include in the comments. I'm curious what everyone's putting in theirs.