Project Instructions (CLAUDE.md)

Chapter 2: Project Instructions (CLAUDE.md)

CLAUDE.md is a project-level instruction file that Claude Code loads automatically at the start of every session. It acts as persistent context: rules, conventions, and constraints that Claude follows without being reminded. Think of it as a .editorconfig or .eslintrc for AI behaviour. Checked into version control, shared across the team, applied consistently.

Location:   CLAUDE.md  at the repository root.

Writing an effective CLAUDE.md

A good CLAUDE.md is concise, specific, and actionable. It tells Claude what matters for your project without being verbose. the team’s template. Used on Project Alpha, Project Beta, and Project Studio (the internal reporting platform). Has the following recommended sections.

Project Structure

Tech stack, primary language, directory layout, package managers. Example from Project Alpha:

This is a monorepo (Project Alpha) using Python (FastAPI worker, data pipeline, LLM gateway) with TypeScript (Next.js 16 frontend). Infrastructure is managed via Terraform on GCP. Primary languages are Python and TypeScript. Package management: uv for Python, npm for Node.js. The repo uses git worktrees for parallel development branches: always verify location before work.

Attribution

A hard rule at the team. Never attribute authorship to Claude Code anywhere. No Co-Authored-By in commits, no “Generated with Claude Code” in PR descriptions, comments, or reviews. No attribution whatsoever. This goes at the top of every CLAUDE.md.

Working Directory

Tell Claude where to operate. Prevents edits outside the project boundary, especially when worktrees are in play. Example: “Your main working directory for this application is project-alpha-dev (or relevant git worktree). All work must be carried out in this directory unless explicitly stated by the user.”

Plan Mode preferences

• Make the plan extremely concise. Sacrifice grammar for the sake of concision.

• At the end of each plan, give the user a list of unresolved questions to answer, if any.

These two rules cut planning overhead massively. Plans become checklists, not essays.

Coding Standards, Testing Conventions, Git Conventions

Be specific. “Use TypeScript strict mode” beats “write good code.” “Mock at the service boundary, not at client internals” beats “test things properly.” See the Chapter 23 anti-patterns for what bad testing looks like.

Platform / Directory rules

If your repo has multiple platforms (backend / frontend / infra), spell out which directory each one lives in. Example from Project Studio (the internal reporting platform):

apps/web/ : Next.js frontend (App Router)

apps/api/ : FastAPI orchestration

apps/workers/ : Cloud Run jobs (Python). Agent workers, renderers, auto-learning agent.

packages/ : shared, agent, renderers, budget

infra/ : Terraform IaC

evals/ : golden set + nightly regression suite

Install platform-specific packages inside their own directory. Never run npm install at the repo root if the package belongs to web/.

Tips for writing CLAUDE.md

• Be specific and actionable.  “Use TypeScript strict mode” beats “write good code.”

• Use imperative form.  “Never commit to main” beats “It would be nice if commits didn’t go to main.”

• Keep it concise.  Claude loads this every session. Long files waste context.

• Add rules when problems recur.  If Claude keeps making the same mistake, add a rule.

• Remove stale rules.  If a rule no longer applies, delete it.

Instruction cascade

• Priority: 1 (lowest) · Source: Global settings · Scope: All projects.
• Priority: 2 · Source: CLAUDE.md · Scope: Everyone on this repo.
• Priority: 3 · Source: settings.local.json · Scope: Your machine only.
• Priority: 4 · Source: Auto memory · Scope: Your machine, persistent.
• Priority: 5 (highest) · Source: Session context · Scope: Current session only.

Memory system

Claude Code maintains a persistent memory system that survives across sessions.

Auto memory

Location:   ~/.claude/projects/<project-hash>/memory/MEMORY.md

Loaded into the system prompt at the start of every session (truncated at 200 lines).

What to save:  stable patterns, architectural decisions, user preferences, debugging insights.

What NOT to save:  session-specific context, unverified conclusions, CLAUDE.md duplicates, speculative notes.

Topic-specific memory files

For detailed notes that exceed the 200-line limit, use topic-specific files alongside MEMORY.md :

~/.claude/projects/<hash>/memory/

 MEMORY.md # Main index (loaded every session)

 debugging.md # Debugging patterns

 patterns.md # Code patterns

Modifying CLAUDE.md

Since CLAUDE.md is checked into version control: discuss the change with the team, make targeted edits, test by starting a new session, commit and push. For personal customisations, use settings.local.json or auto memory instead. Never branch CLAUDE.md just for yourself.