Sign in Subscribe

Day 8: CLAUDE.md Mastery — Structure and Sections

Learn the 6-section CLAUDE.md structure that Claude Code actually follows. Includes master template, verification methods, and before/after examples.

Day 8: CLAUDE.md Mastery — Structure and Sections

Hey, it's G.

Day 8 of the Claude Code series. Phase 2 starts now.

Phase 1 was foundations. Phase 2 is getting actually productive.

We start with CLAUDE.md — but not the basics. Today is about structure.

Day 3 taught you what CLAUDE.md is. Day 8 is about doing it properly.

There's a massive difference between a CLAUDE.md that technically exists and one Claude Code actually reads, understands, and follows consistently.

Let me show you what that difference looks like.

The Problem (Most CLAUDE.md Files Are Useless)

Here's what most people's CLAUDE.md looks like:

# My Project

This is a Next.js app with TypeScript and Tailwind.

Rules:
- Write good code
- Don't break things
- Use TypeScript

What's wrong with this?

Everything is vague. "Write good code" means nothing to an AI. "Don't break things" is not actionable. "Use TypeScript" doesn't specify strict mode, any types, or conventions.

What Claude Code does with this: Guesses. Makes assumptions. Follows patterns inconsistently.

Here's what a properly structured CLAUDE.md looks like:

# My Project

## Project Overview
Project management SaaS for Filipino freelancers. 
Track projects, log hours, generate invoices in PHP.

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.x (strict mode)
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS v3
- Deployment: Vercel

## Coding Conventions
- TypeScript strict mode — never use `any`, ever
- Named exports only — never `export default`
- Components must be under 150 lines — if longer, split it
- Tailwind only — no inline styles, no external CSS files

What's different?

Every rule is specific, testable, and actionable. Claude Code can follow this precisely.

The Concept (Structure Determines Behavior)

CLAUDE.md is just a markdown file — but how you organize it determines how well Claude Code internalizes it.

A wall of text gets skimmed. A well-structured file with clear sections gets followed.

Think of it like writing documentation:

Not for a human reading top to bottom, but for an AI that needs to quickly locate the right rule for the right situation.

Example:

When Claude is about to create a new component, it needs to know:

  • What export style to use (named vs default)
  • What styling approach (Tailwind vs CSS modules)
  • File length limit (when to split)

If those rules are buried in a paragraph, Claude might miss them.

If they're in a clear "Coding Conventions" section with bullet points, Claude follows them every time.

The Six Essential Sections

Every solid CLAUDE.md should have exactly these six sections:

1. Project Overview

What the app does in plain English.

2. Tech Stack

Exact versions matter, not just names.

3. Folder Structure

Only the folders Claude needs to know about.

4. Coding Conventions

Your non-negotiable rules.

5. Behavior Rules

What Claude can do freely vs. what needs approval.

6. Commands

Exact commands for common tasks.

Let me break down each one.

Section 1: Project Overview

What to include:

  • What does this app do?
  • Who is it for?
  • What problem does it solve?

Keep it to 2-3 sentences.

❌ Bad (too vague):

## Project Overview
A web app for managing stuff.

✅ Good (specific and clear):

## Project Overview
Expense tracking app for average Filipinos. Users scan receipts 
or chat with AI to log expenses in seconds. Displays spending 
patterns and budget alerts in Philippine Peso (₱).

Why this works: Claude knows exactly what the app does, who uses it, and what features matter.

Section 2: Tech Stack

What to include:

  • Framework (with version)
  • Language (with version and mode)
  • Database
  • Auth system
  • Styling approach
  • Deployment platform

Exact versions matter, not just names.

❌ Bad (no versions):

## Tech Stack
- Next.js
- TypeScript
- Some database
- Tailwind

✅ Good (specific versions):

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.x (strict mode)
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS v3
- UI Components: shadcn/ui
- Deployment: Vercel

Why this works:

Claude knows you're using App Router (not Pages Router), TypeScript strict mode (not permissive), and Tailwind v3 (specific utility classes).

These details change how Claude writes code.

Section 3: Folder Structure

What to include:

  • Key folders only (not every single directory)
  • What lives in each folder
  • Any special rules about folder contents

Keep it scannable.

❌ Bad (too detailed):

## Folder Structure
- /
  - /app
    - /api
      - /auth
        - /login
        - /logout
      - /users
    - /dashboard
      - /projects
      - /invoices
  - /components
    - /ui
      - /button
      - /input

This is too much. Claude doesn't need every subfolder.

✅ Good (essential only):

## Folder Structure
- /app → all routes and pages (App Router)
- /app/api → all API routes
- /components → shared components
- /components/ui → base UI components only
- /lib → third-party client configs (supabase, stripe, etc.)
- /utils → pure helper functions, no side effects
- /types → all TypeScript type definitions
- /hooks → custom React hooks

Why this works:

Claude knows where things live and what goes where. "Base UI components only" in /components/ui means it won't create custom components there.

Section 4: Coding Conventions

This is the most important section.

What to include:

  • Export style (named vs default)
  • Styling approach (specific tools and restrictions)
  • TypeScript rules (strict mode, any types, etc.)
  • Component structure (file length, one per file, etc.)
  • Async patterns (async/await vs promises)

Every rule must be specific and testable.

❌ Bad (completely useless):

## Coding Conventions
- Write clean code
- Follow best practices
- Use TypeScript properly

What does "clean code" mean? What are "best practices"? What's "proper" TypeScript?

Claude has no idea.

✅ Good (specific and actionable):

## Coding Conventions
- Functional components only, never class components
- Named exports only, never `export default`
- TypeScript strict mode — never use `any`, ever
- Tailwind for all styling — no inline styles, no CSS modules
- Keep components under 150 lines — split if larger
- One component per file
- Async/await only — never .then() chains
- Currency always displayed in PHP (₱)

Why this works:

Every single rule is testable:

  • Did Claude use a named export? ✅ or ❌
  • Did Claude use inline styles? ✅ or ❌
  • Is the component over 150 lines? ✅ or ❌

No ambiguity. No interpretation needed.

Section 5: Behavior Rules

What to include:

  • What Claude can do freely (without asking)
  • What needs approval (install packages, migrations, git operations)
  • Critical files it should never touch
  • When to ask vs. when to act

This section keeps you in control.

❌ Bad (not specific enough):

## Behavior Rules
- Ask before making big changes
- Don't break things

✅ Good (clear boundaries):

## Behavior Rules
- Always ask before installing any new dependency
- Always ask before running database migrations
- Never modify /lib files without flagging it first
- Never push to git without my instruction
- Run freely: npm run dev, npm run build, npm run lint
- If unsure about scope of a change — ask, don't assume

Why this works:

Claude knows exactly what it can do autonomously (run dev/build/lint) and what requires your approval (installs, migrations, git push).

"If unsure about scope — ask, don't assume" is the safety valve.

Section 6: Commands

What to include:

  • Dev server command
  • Build command
  • Lint command
  • Test command (if applicable)
  • Any project-specific commands

Use exact command syntax.

❌ Bad (incomplete):

## Commands
- Start the server
- Run linting

✅ Good (exact commands):

## Commands
- `npm run dev` → start local dev server (port 3000)
- `npm run build` → production build
- `npm run lint` → run ESLint
- `npm run typecheck` → run TypeScript compiler check
- `supabase start` → start local Supabase instance
- `npm run test` → run Jest tests

Why this works:

Claude knows the exact command to run when you say "check for TypeScript errors" (it runs npm run typecheck).

The Master Template (Copy This)

# [Project Name]

## Project Overview
[2-3 sentences. What does this app do? Who is it for? 
What problem does it solve?]

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.x (strict mode)
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS v3
- Deployment: Vercel

## Folder Structure
- /app → all routes and pages (App Router)
- /app/api → all API routes
- /components → shared components
- /components/ui → base UI components only
- /lib → third-party client configs (supabase, stripe, etc.)
- /utils → pure helper functions, no side effects
- /types → all TypeScript type definitions
- /hooks → custom React hooks

## Coding Conventions
- Functional components only, never class components
- Named exports only, never `export default`
- TypeScript strict mode — never use `any`
- Tailwind for all styling — no inline styles, no CSS modules
- Keep components under 150 lines — split if larger
- One component per file
- Async/await only — never .then() chains

## Behavior Rules
- Always ask before installing any new dependency
- Always ask before running database migrations
- Never modify /lib files without flagging it first
- Never push to git without my instruction
- Run freely: npm run dev, npm run build, npm run lint
- If unsure about scope of a change — ask, don't assume

## Commands
- `npm run dev` → start local dev server (port 3000)
- `npm run build` → production build
- `npm run lint` → run ESLint
- `npm run typecheck` → run TypeScript compiler check
- `supabase start` → start local Supabase instance

Customize every section for your actual project.

Don't leave placeholders. Fill in real values.

How To Verify Your CLAUDE.md Works

After updating your CLAUDE.md, run this test:

claude

> Read my CLAUDE.md and summarize the rules you'll follow 
> in this project

Claude should respond with something like:

I'll follow these rules for this project:

Project: Expense tracking app for Filipinos using AI to log expenses
Tech: Next.js 14 App Router, TypeScript 5.x strict mode, Supabase, Tailwind v3

Coding:
- Named exports only, never default
- TypeScript strict, never use any
- Tailwind only, no inline styles or CSS modules
- Components under 150 lines
- Async/await only

Behavior:
- Ask before installing dependencies
- Ask before database migrations
- Never modify /lib files without flagging
- Can freely run: dev, build, lint
- Ask if unsure about scope

Commands I know:
- npm run dev (port 3000)
- npm run build
- npm run lint
- npm run typecheck

If the summary matches what you wrote — you're set.

If something's missing or wrong — that section needs to be clearer.

The test isn't whether Claude can read your CLAUDE.md.

The test is whether Claude summarizes it back the way you intended.

Real Example (Before and After)

Before (My Old Resiboko CLAUDE.md)

# Resiboko

This is an expense tracker for Filipinos.

Tech:
- Next.js
- TypeScript
- Supabase
- Tailwind

Rules:
- Write good code
- Use TypeScript
- Don't break things

Total: 6 lines. Completely useless.

After (Properly Structured)

# Resiboko

## Project Overview
AI-assisted expense tracker for average Filipinos. 
Users scan receipts or chat with AI to log expenses in seconds. 
Displays spending patterns and budget alerts in PHP (₱).

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript 5.x (strict mode)
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS v3
- UI Components: shadcn/ui
- Deployment: Vercel

## Folder Structure
- /app → App Router pages and layouts
- /app/api → API routes
- /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)
- TypeScript strict mode (no `any` types)
- Tailwind utility classes only (no inline styles, no custom CSS)
- Components under 150 lines
- One component per file
- Currency always in PHP (₱)

## Behavior Rules
- Always ask before installing dependencies
- Always ask before Supabase migrations
- Never modify /lib/supabase.ts
- Never push to git
- Run freely: npm run dev, build, lint
- If unsure — ask

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

Total: 50 lines. Actually useful.

The difference in Claude's behavior?

Before: Claude used default exports, inline styles, modified supabase.ts without asking, installed packages freely.

After: Claude follows every convention consistently. Asks before touching critical files. Matches project patterns.

My Raw Notes (Unfiltered)

Went back and rewrote my CLAUDE.md for both Resiboko and 1MinThumb after figuring this out.

The old ones were basically useless — just vibes.

Adding exact versions to the tech stack made a noticeable difference. Claude stopped suggesting Pages Router patterns when I specified "App Router."

The Behavior Rules section is the most important one for staying in control.

Verify it by asking Claude to summarize the rules back — that's the real test.

If Claude's summary doesn't match what you wrote, the structure needs work.

Tomorrow (Day 9 Preview)

Topic: Advanced CLAUDE.md — adding project-specific workflows, custom terminology, and context that makes Claude feel like it's been on your team for months.

What I'm testing: How much project-specific knowledge can CLAUDE.md hold before it starts degrading performance? Where's the sweet spot?

Following This Series

Phase 1 (Days 1-7): Foundations ✅
Phase 2 (Days 8-14): Getting Productive ⬅️ You are here

So far in Phase 2:

  • Day 8: CLAUDE.md structure and sections (today)
  • Day 9: Advanced CLAUDE.md (tomorrow)

G

P.S. - The single biggest improvement to my Claude Code results: rewriting my CLAUDE.md with the 6-section structure. Same AI, dramatically different behavior.

P.P.S. - If your CLAUDE.md is under 30 lines, it's probably too vague to be useful. If it's over 200 lines, it's probably too detailed for Claude to internalize well. Sweet spot: 50-100 lines.

P.P.P.S. - Always verify with "Read my CLAUDE.md and summarize the rules." Claude's summary is the truth of what it actually understood, not what you think you wrote.