How to Improve Your Claude.md Using Past Sessions

Claude Code is an AI coding assistant that runs in VS Code. Every time you start a session, it reads a file called CLAUDE.md from your home folder — this file tells it how you like to work, what to avoid, and any project-specific rules. Out of the box it’s generic. This guide shows you how to make it genuinely useful by having Claude review its own past sessions and update the file based on real mistakes it made.

What is CLAUDE.md?

CLAUDE.md lives at ~/.claude/CLAUDE.md on your machine. Claude Code loads it as persistent instructions at the start of every conversation. Think of it as a standing brief — you write it once, and Claude follows it across every session without you having to repeat yourself.

A freshly set-up file might look something like this:

Original CLAUDE.md (starting point)

## Workflow Orchestration

### 1. Plan Mode default
- Enter plan mode for any non-trivial task (3+ steps or architectural decision)
- If something goes sideways, stop and replan immediately
- Use plan mode for verification steps, not just building
- Write detailed specs upfront to reduce ambiguity

### 2. Subagent strategy
- Use subagents liberally to keep main context window clean
- Offload research, exploration and parallel analysis

### 3. Verification
- Always verify changes: run tests, typecheck, and compile after edits
- If you can't verify it, don't ship it
- When compacting, always preserve the full list of modified files and any test/build commands used

---

## Code Style & Conventions
- Prefer explicit over clever — readability first
- No commented-out dead code in commits
- Keep functions small and single-purpose
- Consistent naming: camelCase for variables/functions, PascalCase for components/classes

---

## File Reading Rules
- Before editing any file, read it first. Research before you edit.
- Before modifying a function, grep for all callers first
- When referencing a file you've already read this session, do NOT re-read it — use what's in context

---

## What NOT to Do
- NEVER rewrite an entire file to fix a small bug — make targeted edits
- NEVER install packages without asking first
- NEVER leave console.log or debug statements in committed code
- NEVER silently swallow errors — always handle or rethrow with context
- Do not make assumptions about project structure — read files first

---

## Git & Branch Conventions
- Commit messages: imperative mood, present tense ("Add feature" not "Added feature")
- Keep commits atomic — one logical change per commit
- Do not commit directly to main/master — always branch

---

## Shell Config
- Set export BASH_MAX_OUTPUT_LENGTH=15000 to reduce bash output noise

---

## Skills

### caveman (installed)
Trigger with /caveman, "caveman mode", or "less tokens please".
Stop with "stop caveman" or "normal mode".

This is a solid starting point. But it’s written from the top down — it describes ideal behaviour, not corrected behaviour. The most valuable rules come from actual sessions where something went wrong.

How to Get Claude to Improve It

Claude Code stores transcripts of every session locally. You can ask it to read those transcripts, identify patterns of mistakes or friction, and update the CLAUDE.md accordingly. Here’s how.

Step 1 — Install Claude Code in VS Code

If you haven’t already, install the Claude Code extension from the VS Code marketplace. Search for Claude Code by Anthropic. Once installed, open a chat panel with Ctrl+Shift+P → “Claude Code: Open Chat”.

Step 2 — Ask Claude to review past sessions

Open a new Claude Code chat and type exactly this:

Can you view your own CLAUDE.md in your root folder? Can you review previous sessions I've had, identify any issues and modify the CLAUDE.md to help fix those issues

Claude will:

1. Read ~/.claude/CLAUDE.md
2. Scan the session transcript files stored in ~/.claude/projects/
3. Extract real conversations where something went wrong or caused friction
4. Make targeted edits to CLAUDE.md to prevent the same issues in future

Step 3 — Review what changed

Claude will explain each change it made and why. You can accept, reject, or tweak any of them. The changes only affect your local file — nothing is sent anywhere.

What Changed in My CLAUDE.md — and Why

Here’s a real example. After running this process on my own sessions, Claude identified 7 concrete issues and added rules to address each one:

Issue from past sessions	Rule added to CLAUDE.md
Restructured site files into a subdirectory — broke Cloudflare Pages deployment silently	Before restructuring hosted files, always check the publish directory setting first
Placeholder text YOUR-SUBDOMAIN was committed and pushed to production	NEVER leave placeholder strings in files about to be committed
Ran wrangler secret put non-interactively — silently set an empty secret	NEVER run interactive commands non-interactively — tell the user to run them manually
Two similar repos existed (torellio vs torellio-site) — nearly pushed to the wrong one	Always verify git remote -v before pushing
Long multi-phase session ran out of context mid-task	Proactively suggest /compact at natural breakpoints in long sessions
WordPress MCP tools were added to config but not yet loaded — assumed available without checking	After adding MCP servers, verify tools are loaded before assuming they’re available
User pasted app password directly into chat	If credentials appear in chat, acknowledge and note they should be rotated if sensitive

The updated CLAUDE.md

After the session, the file had three new sections added:

## Hosting & Deployment Rules
- Before restructuring any files served by a hosting platform (Cloudflare Pages, Netlify,
  Vercel, etc.), always check the publish/output directory setting first — moving files to
  a subdirectory can silently break the deployed site
- Cloudflare Pages by default serves from the repo root; subdirectory restructures require
  a Pages build config change
- When deploying workers or serverless functions, verify all environment variables and
  secrets are set before testing

---

## Environment & Tooling
- User is on Fedora Linux — dnf requires sudo for system packages
- For Node.js installs, prefer nvm (no sudo) over dnf install nodejs
- When MCP servers are newly added, VSCode extension needs a full window reload — always
  verify tools are loaded before assuming they're available

---

## Security Reminders
- If user pastes credentials in chat: acknowledge, but note they're in the session
  transcript and should be rotated if sensitive
- API keys should be in env vars or secret stores, never hardcoded in committed files

And two existing sections got targeted additions:

## What NOT to Do
# Added:
- NEVER leave placeholder strings (YOUR-*, <your-value>, etc.) in files about to be committed
- NEVER run interactive commands non-interactively (e.g. wrangler secret put, gh auth login)
  — they silently fail or set empty values; tell the user to run them manually instead

## Git & Branch Conventions
# Added:
- Always verify git remote -v before pushing — user often has multiple repos and the wrong
  one can be active

Bonus: Cut Token Usage with Caveman Mode

You’ll notice the original CLAUDE.md above includes a Skills section with a plugin called caveman. This is one of the most useful things you can add to your Claude Code setup, so it’s worth explaining properly.

Caveman is a Claude Code plugin by Julius Brussee that makes Claude respond like a caveman — stripping out articles, filler words, pleasantries, and hedging language, while keeping all the technical substance intact. The result is responses that are roughly 75% shorter with zero loss of useful information.

Why bother?

Claude Code’s default responses are verbose. Every reply tends to open with “Sure, I’d be happy to help with that!” and end with a paragraph summarising what it just did. When you’re deep in a coding session firing off 50+ messages, this adds up fast — in reading time, in scrolling, and if you’re on a paid API plan, in token costs.

Caveman mode strips all of that. Compare:

Normal mode	Caveman mode
“Sure! The issue you’re experiencing is likely caused by a new object reference being created on each render. When you pass an inline object as a prop, React sees it as a new reference every render and triggers a re-render. You can fix this by wrapping it in useMemo.”	“New object ref each render. Inline object prop = new ref = re-render. Wrap in useMemo.”

Same information. A fraction of the words.

How to install it

Install via the Claude Code CLI:

claude plugin install https://github.com/JuliusBrussee/caveman

Once installed, add the Skills entry to your CLAUDE.md so Claude knows it’s available:

## Skills

### caveman (installed)
Trigger with /caveman, "caveman mode", or "less tokens please".
Stop with "stop caveman" or "normal mode".
Use when you want concise, low-token responses. Code blocks and technical terms stay exact — only filler prose is stripped.

How to use it

At the start of any session, just say:

/caveman

Claude switches into compressed mode for the rest of the session. To go back to normal:

stop caveman

There are also intensity levels — /caveman lite for slightly compressed, /caveman ultra for maximum compression. The plugin also comes with /caveman-review for compressed code review comments and /caveman-commit for tight commit message generation.

Full details and source at github.com/JuliusBrussee/caveman.

Tips for Getting the Most Out of This

• Run this every few weeks. The more sessions you’ve had, the more patterns there are to learn from. It gets better over time.
• Be specific when something goes wrong. If Claude makes a mistake during a session, say so clearly. It will remember the correction in that session, and next time you run the review it’ll make a permanent rule from it.
• Review the changes before accepting. Claude is conservative with CLAUDE.md edits but you should still read them — occasionally a rule will be too broad or specific to one project when it should be general.
• Keep rules general, not task-specific. “Always verify the remote before pushing” is a good rule. “Remember I have a repo called torellio-site” is not — that belongs in a project-level CLAUDE.md inside that repo’s folder.
• Don’t add rules for hypothetical problems. Only add rules for things that actually went wrong. A CLAUDE.md full of speculative warnings makes it harder for Claude to find the important ones.

Where the Session Files Are

If you’re curious, Claude stores session transcripts at:

~/.claude/projects/<project-path>/<session-id>.jsonl

Each file is a JSON Lines file — one event per line. Claude reads these directly when you ask it to review past sessions. You don’t need to do anything to enable this; it happens automatically as long as you’re using Claude Code.

Summary

1. Claude Code reads ~/.claude/CLAUDE.md every session
2. Session transcripts are stored locally in ~/.claude/projects/
3. Ask Claude to “review previous sessions and update the CLAUDE.md” — it will read the transcripts, find issues, and make targeted fixes
4. The result is a CLAUDE.md that reflects real mistakes, not just ideal intentions
5. Install the caveman plugin to cut response verbosity by ~75%
6. Repeat the review every few weeks as you accumulate more sessions