Wait, CLAUDE.md Is Actually a Thing?
I stumbled onto something on vibe-coding and I had no idea it existed until yesterday.
I was working on deployment issues where everything looked successful, but the static files were not updated. Classic deployment amnesia, where you forget to check the actual result. I was asking Claude to help me create a deployment checklist when they suggested something I'd never heard of:
Let's put this in a CLAUDE.md file in your project root.
Wait, what? That's a thing?
CLAUDE.md with Claude CLI
It turns out that Claude Code (the CLI tool I've been using) has a feature I never knew about. When you start a session in any project, it automatically looks for a file called CLAUDE.md in the root directory and loads it as a persistent context.
This isn't just documentation. This is like giving the AI a project-specific memory that persists across every conversation.
Instead of starting the day with "Look at all the documentation in docs/ and ..." I can encode all that context once, and every conversation begins with the AI already understanding my project.
Testing It Out: The Deployment Example
I decided to test this with my recurring deployment issue. Instead of writing another document, I'd forget to tell Claude to check when deploying, I put the essential reminders directly into the Claude memory:
## 🚀 Deployment Protocol
**CRITICAL**: When the user asks to deploy, ALWAYS reference:
📋 Deployment Checklist: docs/guides/deployment/deployment-checklist.md
### Key Reminders:
1. Verify actual site content, not just deployment status
2. Check fly.toml timeout is 60s (not 600s)
3. Large commits with confidence reports are normal
4. Site updates may take 2-3 minutes to propagate
Now, every time I mention deployment, Claude automatically brings up the checklist. It's like having a pair programming partner who never forgets the boring but critical verification steps.
What Else Can Go in AI Memory?
Once I understood this concept, I realized I could encode way more. This project has specific quirks that used to trip me up constantly:
Scale Context: This pipeline processes 925+ episodes with thousands of confidence reports. When you see over 600 files in the confidence_reports folder, that's normal, not a sign that something is broken.
Architecture Reminders: The speaker recognition system uses ECAPA-TDNN embeddings with cross-episode memory. When confidence rates drop below 80%, that's when you investigate, not at 85%.
Common Debugging Patterns: If the pipeline seems stuck, check run-insights/ for execution logs. If speaker recognition is low, check the embeddings/ folder size.
Project-Specific Gotchas: Large commits with 500+ confidence report files are normal. A deployment lag of 2-3 minutes is expected. The fly.toml timeout must be 60s, never 600s.
Besides all the documentation, I now consider that one thing a 'must do' for every project. And this isn't just for big, complex projects. Any project with quirks, gotchas, or context that's tedious to re-explain could benefit from this.
An Example
Yesterday, I was debugging a pipeline issue, and instead of explaining the whole speaker recognition architecture, I just said, "The embeddings count looks low." Claude immediately knew I was referring to the ECAPA-TDNN voice fingerprints in the embeddings folder and suggested checking the vector database connection.
Because all that context was already loaded from CLAUDE.md.
It's not revolutionary technology. It's just putting project knowledge where the AI can actually use it consistently.
What I'm Testing Next
I want to see how far this can go. Can I encode enough operational knowledge that Claude becomes genuinely helpful for complex debugging? Can I capture not just facts but reasoning patterns?
These are the kinds of patterns that take time to learn through experience.
The deployment example was just the starting point. Now every time I figure out something project-specific, a debugging pattern, an architecture gotcha, a performance threshold, I'll think of adding it to CLAUDE.md
It's like building up knowledge that doesn't reside in anyone's head. It exists in the AI's memory and can act on it without me having to remember to do anything. It's consistent and cannot forget something. That's why AI is so powerful when it comes to coding.
– Benoit Meunier