I want to tell you about the chapter in the Claude Code 101 course that made me stop and feel something I wasn’t expecting.
Not excitement. Not curiosity.
Vindication.
The ChatGPT Trauma Is Real
If you’ve spent serious time building with AI tools, you know the specific frustration I’m about to describe.
You establish a working pattern. You explain your preferences. You get good output. Next session — or sometimes just a few prompts later — it’s gone. The AI has drifted. The comments are missing. The error handling is different. There’s an emoji in your code block for reasons nobody can explain.
You correct it. It apologizes. It does it again.
Over roughly a year of heavy ChatGPT use, I accumulated a mental list of things I had to re-explain every single session:
Always add error handling. Always add logging. Always add comments — but useful ones, not narration of what the code obviously does. Never put emojis in code. Test coverage is not optional. When you update code, update the tests. When you add a function, add it to the right file — don’t invent a new one.
Basic stuff. Professional stuff. Stuff that shouldn’t require repeating.
I repeated it constantly.
What CLAUDE.md Actually Is
Claude Code has a system of persistent instruction files called CLAUDE.md. They live at three levels:
Project level — lives in the repo, gets committed, shared with the whole team. Everyone working on the project gets the same instructions automatically.
Local level — your personal overrides and notes, gitignored, never leave your machine. For the things that are about how you work, not how the project works.
Machine level — global config at ~/.claude/CLAUDE.md that applies across every project on your machine. The baseline. The non-negotiables.
Claude Code reads all three at the start of every session. Automatically. No prompt required. The instructions are just… there, before you type a single word.
What’s In Mine
I spent real time on my global CLAUDE.md before starting my first project. Not because the course told me to — because I’d been burned enough times to take it seriously.
Here’s the shape of it:
Background context — my CalPERS history, what “enterprise legacy code” means to me from lived experience, the kinds of systems I’ve worked on. Not resume padding — actual context that changes how Claude interprets ambiguous instructions. “Production-grade” means something different to someone who’s maintained a system for 7 years than to someone who’s been shipping side projects.
The workflow — Explore → Plan → Confirm → Code. Claude Code proposes before it writes. I review before it proceeds. Nothing gets built that I haven’t seen the plan for first.
Code standards — error handling requirements, logging patterns, comment style, test expectations. Written as rules with reasoning attached. Not “always add error handling” — why I want it, what it should catch, what the output should look like.
The don’t-do-this list — explicit prohibitions with explanations. No emojis in code or comments. No inventing new files when an existing one is the right home. No removing existing functionality to make a test pass. No placeholders — if you can’t implement it now, say so explicitly rather than writing # TODO: implement this.
Voice and communication style — direct, no filler, opinionated. If Claude thinks I’m making a mistake, say so. Don’t just execute blindly.
The key thing: every rule has a why attached. I learned this from the course — Claude follows opinionated instructions better when it understands the intent behind them. “Don’t add emojis” is a rule. “Don’t add emojis because this is production code that will be read in code review by engineers who will judge it” is a reason. The reason sticks better.
What Changed When I Used It
The difference showed up immediately in the first project session.
Claude Code opened with full context. It understood the project structure before I explained it. It proposed an approach that matched my preferences without me specifying them. When it hit an unexpected problem — the Claude 4 extended thinking API had changed between when I documented it and when the SDK was installed — it diagnosed the issue, researched the fix by introspecting the installed package, updated the code, updated the affected tests, and updated the CLAUDE.md example to reflect the new pattern.
It didn’t ask me to repeat my standards halfway through. It didn’t drift. It didn’t put emojis anywhere.
I’ve been writing software for over a decade. The mental overhead of maintaining consistency — across sessions, across tools, across the gap between “how I want it done” and “how it came out” — is real, and it compounds. CLAUDE.md doesn’t eliminate that overhead. But it moves it from a recurring tax to a one-time investment.
Write it once. It works every session after that.
The Team Angle
Here’s the thing I keep thinking about for engineering teams.
Every senior engineer has a way they want things done. Coding standards. Review expectations. The patterns that have proven themselves over years of production incidents and 3 am pages. Most of them spend a significant portion of their career re-explaining those standards — to new hires, to junior developers, to contractors, to tools that don’t retain context.
A team CLAUDE.md is that conversation written down once.
Not a wiki nobody reads. Not a style guide that’s three years out of date. An active instruction set that every Claude Code session on every developer’s machine reads before writing a line. Project-level standards that get committed to the repo and travel with the code.
The senior engineer’s preferences stop living in their head and start living in the file.
A new developer joins the team. They clone the repo. Claude Code reads the CLAUDE.md. They’re already building to the team’s standards before their first PR.
That’s not a small thing.
The Uncomfortable Flip Side
I’ll say the quiet part out loud.
If your team’s standards aren’t written down anywhere — if they exist only as tribal knowledge in the heads of your senior engineers — a CLAUDE.md is going to expose that gap fast.
You can’t write an instruction file for standards you haven’t articulated. The process of building a good CLAUDE.md is also the process of actually deciding how you want things done and writing it down.
For some teams, that’s going to be the most valuable engineering exercise they do this year. For others, it’s going to be uncomfortable.
Either way, it’s worth doing.
Where to Start
If you’re using Claude Code and you haven’t built a CLAUDE.md yet, start with your global one. Open ~/.claude/CLAUDE.md and write down three things:
Your background and context — what “production-ready” means to you from actual experience.
Your non-negotiables — the three to five things you re-explain every session because they keep getting missed.
The why behind each one — not just the rule, the reasoning.
That’s it. Start there. Refine it as you go. The file gets better every time you catch yourself correcting something that should have been in the instructions.
The Anthropic Academy’s Claude Code 101 course covers CLAUDE.md in depth — including the three-level structure and how to write instructions Claude actually follows. Free, certified, worth your time at anthropic.skilljar.com.
Next up: The second project — this time with timestamps, git commits after every command, and actual benchmarks. Because 45 minutes on a broken setup deserves a proper rematch.