Day 10: Evolving Your CLAUDE.md Over Time

Hey, it's G.

Day 10 of the Claude Code series.

CLAUDE.md isn't a document you write once and forget.

Projects change. New dependencies get added. Folder structures shift. Conventions evolve.

A stale CLAUDE.md is almost worse than none — because it gives Claude Code confidently wrong information.

Today I learned how to treat CLAUDE.md as a living document and built a habit around keeping it accurate.

The Problem (My CLAUDE.md Was Lying)

Here's what happened with Resiboko:

I wrote a solid CLAUDE.md when I started the project.

Tech stack documented. Folders mapped. Conventions clear.

Then I didn't touch it for two months.

What changed in those two months:

• Added Stripe for payments
• Added Resend for emails
• Added Zod for validation
• Restructured the /api folder
• Renamed /components/forms to /components/custom
• Changed from default exports to named exports

My CLAUDE.md still said:

• Tech stack: Next.js, Supabase, Tailwind (that's it)
• Forms live in /components/forms
• "Use default exports for pages"

What Claude Code did:

• Suggested patterns for forms that didn't match our new structure
• Referenced folders that no longer existed
• Used default exports (our old convention, now wrong)
• Had no idea Stripe, Resend, or Zod existed

Claude was confidently wrong. Every single session.

The Concept (Living Document, Not Static File)

Most developers do this:

Write CLAUDE.md → Never update it → Wonder why Claude keeps making the same mistakes

The fix isn't a big monthly audit.

It's a small habit attached to things you're already doing.

There are three moments that should trigger a CLAUDE.md update:

1. When Something Changes

New dependency, new folder, new convention

2. When Claude Makes the Same Mistake Twice

That's a missing or weak rule

3. When You Start a New Major Feature

Add context before Claude touches it

Think of it like a codebase README.

The best ones stay accurate because the team updates them as part of the work — not as a separate chore.

Trigger 1: When Something Changes

Scenario: You just added Stripe to your project for payments.

Do this immediately:

code CLAUDE.md

Update these sections:

## Tech Stack
- Framework: Next.js 14 (App Router)
- Database: Supabase
- Styling: Tailwind CSS
- Payments: Stripe (added March 2026)
- Email: Resend

## Folder Structure
- /lib/stripe.ts → Stripe client config — do not modify directly
- /utils/payments.ts → all payment logic lives here
- /app/api/billing → Stripe webhook handlers

## Behavior Rules
⚠️ NEVER modify /lib/stripe.ts without asking first
⚠️ NEVER expose Stripe secret keys in client-side code
- All payment operations must go through /utils/payments.ts

Why this matters:

Next time you ask Claude to add a payment feature, it knows:

• Stripe exists and is configured
• Where the config lives (don't touch)
• Where payment logic should go (/utils/payments.ts)
• Security rules (never expose keys client-side)

Without this update, Claude would:

• Suggest installing Stripe (it's already installed)
• Create payment logic in random files
• Potentially expose secrets

Trigger 2: When Claude Makes the Same Mistake Twice

Scenario: Claude keeps creating default exports even though your convention is named exports only.

This happened twice. That means your rule isn't strong enough.

Current rule in CLAUDE.md:

- Use named exports

This is too weak.

Rewrite it:

- Named exports ONLY — never use `export default`, 
  not even for pages or layouts. No exceptions.

Another example:

Claude keeps putting components in the wrong folder.

Weak rule:

- Keep components organized

Strong rule:

- UI components go in /components/ui (shadcn/ui only)
- Custom components go in /components/custom
- Feature-specific components go in /app/[feature]/components
- Never create components outside these three locations

The pattern:

Mistake happens once → Could be Claude misunderstanding
Mistake happens twice → Your rule is too vague

Fix it immediately.

Trigger 3: When You Start a New Major Feature

Scenario: You're about to build a subscription billing system.

Before you start the first Claude session, add context:

## Current Focus
We are currently building a subscription billing system.

Context:
- Stripe is already configured in /lib/stripe.ts
- New components for billing UI go in /components/billing/
- New API routes go in /app/api/billing/
- Subscription plans defined in /config/plans.ts

Important:
- Do not touch /app/api/payments/ — that is the old 
  one-time payment system and is being deprecated
- Do not modify existing payment flows while building 
  subscription features

Why this works:

Claude now knows:

• What you're currently working on
• Where new code should go
• What NOT to touch (old payment system)
• Context it needs without you repeating it every session

This section is temporary. Remove it when the feature is done.

Advanced Pattern: Version Notes

Add a last updated note to your CLAUDE.md:

# MyProject CLAUDE.md
Last updated: March 11, 2026

## Project Overview
...

Why:

When you look at your CLAUDE.md, you instantly know if it's current or stale.

If it says "Last updated: December 2025" and it's now March 2026, you know to audit it.

Advanced Pattern: Ask Claude to Flag Inconsistencies

Add this instruction to your CLAUDE.md:

## Meta Rule
If anything I ask you to do contradicts or isn't covered 
by this CLAUDE.md, flag it so I can update the file.

What happens:

> Add a new feature using Firebase Auth

Claude: I notice your CLAUDE.md says we use Supabase Auth, 
but you're asking me to use Firebase. Should I proceed with 
Firebase or is this CLAUDE.md outdated?

Claude becomes your CLAUDE.md quality checker.

Monthly Audit Command

Once a month (or at the start of each sprint), run this:

claude

> Read my CLAUDE.md and compare it against the actual 
> project structure and package.json. Flag anything that 
> looks outdated, missing, or inconsistent.

Claude will respond with something like:

I found several inconsistencies:

CLAUDE.md says tech stack is:
- Next.js 14, Supabase, Tailwind

But package.json shows you also have:
- stripe (not mentioned)
- zod (not mentioned)  
- react-hook-form (not mentioned)

CLAUDE.md says forms live in /components/forms
But that folder doesn't exist. I see /components/custom instead.

CLAUDE.md says to use default exports
But most of your recent files use named exports.

Should I help you update CLAUDE.md to match current reality?

Fix everything it flags.

Real Example (Before and After)

3 Months Ago (When I Started)

# Resiboko

## Tech Stack
- Next.js 14
- Supabase
- Tailwind

## Folder Structure
- /app → pages
- /components → components

Total: 8 lines. Accurate at the time.

Today (After Never Updating It)

My project now has:

• Stripe for payments
• Resend for emails
• Zod for validation
• React Hook Form for forms
• A /emails folder for email templates
• A /schemas folder for Zod schemas
• A /components/billing folder for subscription UI

But my CLAUDE.md still says:

• Tech stack: Next.js, Supabase, Tailwind
• Folders: /app, /components

Claude Code has no idea about:

• Stripe (so it suggests installing it again)
• Resend (so it suggests nodemailer instead)
• Zod (so it doesn't use our validation patterns)
• The /emails folder (so it creates email templates in random places)

Result: Claude confidently makes wrong decisions every session.

Updated Version (Current Reality)

# Resiboko
Last updated: March 11, 2026

## Project Overview
AI-assisted expense tracker for Filipinos. Scan receipts 
or chat with AI to log expenses. Free tier + Pro subscription.

## Tech Stack
- Framework: Next.js 14 (App Router)
- Database: Supabase (PostgreSQL)
- Auth: Supabase Auth
- Styling: Tailwind CSS
- UI Components: shadcn/ui
- Payments: Stripe (subscription billing)
- Email: Resend
- Validation: Zod
- Forms: React Hook Form
- Deployment: Vercel

## Folder Structure
- /app → routes and pages (App Router)
- /app/api → API routes
- /app/api/billing → Stripe subscription webhooks
- /components/ui → shadcn/ui components (don't modify)
- /components/custom → our custom components
- /components/billing → subscription UI components
- /emails → Resend email templates
- /schemas → all Zod validation schemas
- /lib → third-party configs (supabase, stripe, resend)
- /utils → helper functions

## Current Focus
Building Pro subscription tier with Stripe.
- New billing components go in /components/billing/
- Subscription logic in /utils/subscriptions.ts
- Do not modify free tier expense tracking flow

## Coding Conventions
- Named exports ONLY — never `export default`
- TypeScript strict mode — never use `any`
- Zod for all validation — never inline validation
- React Hook Form for all forms
- Currency always in PHP (₱)

## Behavior Rules
⚠️ NEVER modify /lib/stripe.ts or /lib/supabase.ts
⚠️ NEVER expose Stripe secret keys client-side
- Always ask before installing dependencies
- Run freely: npm run dev, build, lint

## Meta Rule
If anything I ask contradicts this CLAUDE.md, flag it 
so I can update the file.

Total: 65 lines. Accurate and comprehensive.

The difference in Claude's behavior:

Before (stale CLAUDE.md):

• Suggests installing Stripe (already installed)
• Creates email templates in /components (wrong location)
• Uses default exports (outdated convention)
• Doesn't know about Zod validation patterns

After (updated CLAUDE.md):

• Knows Stripe exists and where config lives
• Creates email templates in /emails
• Uses named exports consistently
• Applies Zod validation automatically

The Update Habit (What Actually Works)

Don't schedule "CLAUDE.md update time."

Instead, attach updates to things you're already doing:

After Installing a Package

npm install stripe

# Immediately:
code CLAUDE.md
# Add Stripe to tech stack and folder structure

After Renaming a Folder

git mv components/forms components/custom

# Immediately:
code CLAUDE.md
# Update folder structure section

After Changing a Convention

# You just decided: no more default exports

# Immediately:
code CLAUDE.md
# Update coding conventions with the new rule

After Claude Makes the Same Mistake Twice

# Claude created another component in the wrong folder

# Immediately:
code CLAUDE.md
# Make the folder rule more specific

The pattern:

Something changes → Update CLAUDE.md right then → Commit it with the change

Example commit:

git add lib/stripe.ts CLAUDE.md
git commit -m "add stripe integration + update CLAUDE.md"

CLAUDE.md updates are part of the work, not a separate task.

What To Remove From CLAUDE.md

CLAUDE.md can also get bloated. Remove things that are no longer true:

Old Dependencies

# Remove if you're no longer using Firebase:
- Auth: Firebase Auth ❌ DELETE THIS

Deprecated Folders

# Remove if /components/forms no longer exists:
- /components/forms → form components ❌ DELETE THIS

Outdated Rules

# Remove if you changed from default to named exports:
- Use default exports for pages ❌ DELETE THIS

Completed "Current Focus" Sections

# Remove when subscription feature is done:
## Current Focus
Building subscription billing... ❌ DELETE THIS

Keep CLAUDE.md lean. Remove the old when you add the new.

My Raw Notes (Unfiltered)

This was the problem I had with Resiboko. Started with a decent CLAUDE.md but never updated it.

By month two Claude was suggesting patterns we'd already moved away from and referencing folders that had been renamed.

The "Current Focus" section is something I added recently and it genuinely changes how Claude approaches tasks — it knows what we're working on right now, not just what the project is in general.

The monthly audit command is something I now run at the start of every new sprint.

Attaching updates to things I'm already doing (install package → update CLAUDE.md) made it actually stick as a habit.

Tomorrow (Day 11 Preview)

Topic: What Slash Commands Are and Your First Custom One

What I'm testing: Claude Code's slash command system — how to create custom commands that save you from typing the same prompts repeatedly.

CLAUDE.md Mastery track complete. 🎉

Next track: Slash Commands (Days 11-13)

Following This Series

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

So far in Phase 2:

• Day 8: CLAUDE.md structure and sections
• Day 9: Writing rules Claude actually follows
• Day 10: Evolving CLAUDE.md over time (today)
• Day 11: Slash commands basics (tomorrow)

G

P.S. - The single habit that keeps my CLAUDE.md accurate: update it immediately when something changes, commit it with the change. Make it part of the work, not a separate chore.

P.P.S. - If your CLAUDE.md doesn't have a "Last updated" date, add one today. It's the simplest way to know when it's gone stale.

P.P.P.S. - The monthly audit command is gold: "Compare my CLAUDE.md against actual project structure and flag inconsistencies." Claude becomes your CLAUDE.md quality checker.