← A Working Developer's Claude Code Workflow
What should go in CLAUDE.md?
Whatever a new engineer would need explained on day one that isn’t obvious from reading the code: architecture decisions, coding standards, the commands that actually matter, and the pitfalls that have already bitten someone. Skip anything Claude Code can figure out by reading the codebase itself.
Architecture and code standards
State the shape of the project up front: how it’s organized, what the major components are and how they relate, and which conventions the codebase actually follows (naming, file structure, patterns to use or avoid). This is the context that would otherwise take several files and a few wrong guesses to reconstruct. Keep it factual and current: an architecture note that’s gone stale is worse than none, because it actively misleads.
Key files and commands
List the commands that matter for this specific project: how to run tests, how to start a dev server, how to build, how to lint. Generic advice (“run the test suite”) is far less useful than the actual command with its actual flags. The same goes for key files: if there’s a file that defines core conventions (a base class, a config schema, a shared utility everyone should know about), name it and say why it matters.
Known pitfalls and preferred approaches
This is where CLAUDE.md earns its keep. Anything that’s caused a real mistake before, a gotcha in how a library is used, a step that’s easy to skip, a pattern that looks right but isn’t, belongs here. Document the lesson once and it stops recurring. This section tends to grow over time as new pitfalls surface; that’s a sign it’s working, not a sign it’s bloated.
What to leave out
CLAUDE.md is context that gets loaded into every session, so it isn’t the place for anything a codebase search or a file read would answer just as well. Skip narrative history of why decisions were made unless the reasoning itself changes how someone should act today. Skip anything that duplicates what’s already in a README or in the code’s own comments. A shorter file that’s accurate and current beats a long one that’s comprehensive but stale, since Claude Code (like any engineer) reads it once and treats it as ground truth.
Talk to 84EM about setting up an AI-assisted development workflow if your team is getting inconsistent results from Claude Code.
