CLAUDE.md
Working with Claude on Projects
CLAUDE.md is the project instructions file — a markdown document that Claude reads at the start of every session in your project. It's the place for standing rules, permanent context, and behavioural preferences that should never have to be restated. Written well, it makes every session feel immediately productive. Written poorly, it's ignored noise. This chapter covers what goes in it, how to structure it, and how it differs from the memory system.
What CLAUDE.md Is For
Think of CLAUDE.md as the briefing document Claude reads before walking into the room. It answers the questions that would otherwise have to be re-explained every session:
- What is this project? — the purpose, the tech stack, the goal
- Who is the user? — role, expertise, how they like to work
- What are the standing rules? — code style, tool preferences, what to avoid
- What should Claude always do? — automatic behaviours, output formats, naming conventions
- What is the structure? — file locations, key paths, important conventions
It is not a task list, a session log, or a place for things that change frequently. Those belong in memory files or external tools.
CLAUDE.md is always loaded completely. Keep it focused — every line should earn its place by shaping Claude's behaviour. Verbose instructions dilute the signal.
Anatomy of a Good CLAUDE.md
One paragraph: what this project is, what it produces, who it's for. Gives Claude the context to make good judgement calls without being told everything explicitly.
Language, framework, OS, key tools, server details. Prevents Claude suggesting the wrong language, library, or platform.
Where things live. Key paths, naming conventions, output locations. Means Claude can write to the right place and reference the right files without asking.
Style rules, formatting preferences, linting conventions. What to always include (type hints, docstrings) and what to never do (e.g. use a specific anti-pattern).
How Claude should communicate, what it should always or never do, how to handle ambiguity in this project's context. The standing preferences.
Where to find the memory index, key documents, external resources. Short — just enough to orient Claude to the rest of the project's knowledge base.
A Complete CLAUDE.md Example
# Project: osztromok.com Learning Website ## Overview A personal learning website at osztromok.com. Philip uses Claude to generate HTML course chapters, SQL inserts, and PDF exports. The site hosts self-study courses covering Linux, networking, programming, and languages. ## Tech Stack - Server: Debian 12, Apache 2.4, PHP 8.2, MySQL 8 - Course pages: fragment HTML (no DOCTYPE/html/head/body tags) - Dark theme: background #0d1117, surface #161b22 - PDFs: Chrome headless + pypdf merge ## File Structure - Course HTML: claude-generated-files/ - SQL inserts: claude-generated-files/insert_*.sql - PDF output: claude-generated-files/*.pdf - Memory: C:\Users\emuba\.claude\projects\...\memory\ ## Coding Standards - HTML: fragment only — no DOCTYPE, html, head, or body tags - SQL: always SET NAMES utf8mb4; use CONVERT(UNHEX(...) USING utf8mb4) for bodies - Python: type hints required; no third-party deps beyond pypdf/requests - Shell: always suggest vim for terminal editing — never nano ## Behavioural Rules - Generate PDFs automatically with the final chapter of every course - Always ask for subtopic_id and page_id before generating SQL - Course shorthand prompts: respond without asking for clarification - Be direct — no hedging, no excessive caveats, no closing summaries - When generating code: write it and run it; don't just show it ## Memory Index See memory/MEMORY.md for the full index of user preferences, feedback, project decisions, and course outlines.
Writing Instructions That Actually Work
Be specific and actionable
Vague instructions ("be helpful", "write good code") are ignored because they don't change Claude's behaviour — they match what Claude would do anyway. Specific instructions ("use type hints on all function signatures", "never suggest nano") change actual output.
Use imperative form
Instructions written as directives are more reliable than instructions written as preferences. Always generate the PDF in the same response as the final chapter is more effective than It would be great if the PDF was generated automatically.
Keep it current
A stale instruction is worse than no instruction — it actively misleads Claude. Review CLAUDE.md when the project changes significantly. Remove rules that no longer apply. Update paths and tool names when they change.
Don't duplicate memory
If a preference is already in a memory file, don't also put it in CLAUDE.md. Duplication creates conflicts when one is updated and the other isn't. Use CLAUDE.md for standing rules that never change session-to-session; use memory files for facts that evolve.
CLAUDE.md vs. Memory Files — When to Use Each
| What kind of information | CLAUDE.md | Memory file |
|---|---|---|
| Project tech stack and file structure | ✅ Always here | — |
| Standing code style rules | ✅ Always here | — |
| Automatic behaviours ("always do X") | ✅ Always here | — |
| User background and expertise level | Brief summary fine | ✅ Full detail here |
| Feedback from past sessions | — | ✅ Always here |
| Project decisions and rationale | — | ✅ Always here |
| Course outlines and status | — | ✅ Always here |
| Things that change frequently | ❌ Don't put here | ✅ Memory is easier to update |
| External resource locations | Brief pointer fine | ✅ Full details here |
CLAUDE.md for Different Project Types
Software project
Emphasise: language and framework, test runner and how to run tests, linting config, branch strategy, how to run the app locally, where the API docs are. The goal is for Claude to operate like a dev who has already read the onboarding docs.
Writing or content project
Emphasise: audience, tone, style guide rules (Oxford comma, US/UK English, heading capitalisation), output format (markdown, HTML, plain text), where drafts are stored, what "done" looks like for this project.
Research or learning project
Emphasise: what's already been covered (or point to memory files), the learning goals, preferred explanation depth, any domain-specific vocabulary conventions, where notes and outputs are stored.
Personal assistant / admin project
Emphasise: recurring tasks and their format, external accounts and tools in use, decision-making preferences, communication style, time zone and locale, preferred date formats.
How Long Should It Be?
Long enough to cover everything Claude needs; short enough that every line matters. In practice, a well-written CLAUDE.md for most projects fits in 50–150 lines. The test: if you could remove a line without changing Claude's behaviour, remove it.