Claude Code · Part 4

Claude Code — Part 4 — Understanding and Writing CLAUDE.md

CLAUDE.md is the file that stops you from re-explaining the same project conventions every single session, and writing a good one is mostly about being specific rather than being long.

By K Shankar R Karanth AI Tools Series Part 4

Quick idea: CLAUDE.md is a plain markdown file that Claude Code reads at the start of every session, so anything you would otherwise repeat every time belongs in it instead.

CLAUDE.md

Instructions you write, loaded into every session for a project, a user, or an organisation.

Auto Memory

Notes Claude writes itself as it learns your corrections and preferences, no authoring required.

/init

Generates a starting CLAUDE.md by having Claude analyse the codebase for you.

Introduction

Every session in this series so far has started from zero context beyond what Claude reads from the folder itself. That is fine for a one-off task, but it gets repetitive fast once you are back in the same PowerShell library or the same AD toolkit every day, typing the same corrections into chat each time.

CLAUDE.md exists to fix exactly that. It is a plain markdown file, read at the start of every session, that carries the instructions you would otherwise re-explain.

What Is CLAUDE.md?

CLAUDE.md is a markdown file containing persistent instructions for a project, your personal workflow, or an entire organisation. You write it in plain English, in plain markdown, and Claude Code loads it automatically, no special syntax or configuration format required.

Think of it as the onboarding document you would hand a new engineer on their first day: build commands, naming conventions, “always do X, never do Y” rules, and the project-specific quirks that are not obvious from the code alone.

Key difference: CLAUDE.md is what you write. Auto memory is what Claude writes about itself as it works, capturing things like debugging insights and build commands it discovers, without you asking it to.

Where CLAUDE.md Files Live

CLAUDE.md files exist at several scopes, loaded in order from broadest to most specific.

Scope	Location (Windows)	Purpose
Managed policy	`C:\Program Files\ClaudeCode\CLAUDE.md`	Organisation-wide rules deployed by IT, cannot be excluded by individual settings
User instructions	`%USERPROFILE%\.claude\CLAUDE.md`	Your personal preferences across every project on your machine
Project instructions	`.\CLAUDE.md` or `.\.claude\CLAUDE.md`	Team-shared standards, checked into source control
Local instructions	`.\CLAUDE.local.md`	Your own project-specific notes, not committed, add to `.gitignore`

Claude Code finds these by walking up the directory tree from wherever you started the session. If you run claude inside C:\Scripts\AD\Reports, it loads CLAUDE.md from that folder, from C:\Scripts\AD, and from C:\Scripts, all the way up. They are concatenated, not overridden, with instructions closer to your working directory read last.

Practical note: A CLAUDE.md placed in a subdirectory below your working directory is not loaded at launch. It loads on demand only once Claude reads a file inside that subdirectory.

What Belongs In It

The clearest test is whether you find yourself typing the same correction into chat more than once. If a code review would catch something Claude should already have known about this codebase, or a new teammate would need the same context to be productive, it belongs in CLAUDE.md.

Specificity matters more than length. “Use full cmdlet names, no aliases” is something Claude can actually check itself against. “Write good PowerShell” is not.

Example: “Run PSScriptAnalyzer before delivering any script and resolve high-severity findings” is verifiable. “Make sure scripts are high quality” is not, and Claude has no consistent way to act on it.

A CLAUDE.md for a Windows operations scripts library might look like this in practice:

# Workspace Instructions

## Scope And File Safety
- Do not write output files outside C:\Temp\Reports unless approved.
- PowerShell scripts may run locally for testing, never against
  production without explicit approval.

## Quality Baseline
- Use Set-StrictMode -Version Latest.
- No aliases in delivered scripts: Where-Object, not ?.
- Typed parameters with validation attributes where appropriate.

## Environment Assumptions
- WinRM is assumed blocked. Use Get-WmiObject for remote collection,
  not Invoke-Command.
- Keep scripts compatible with Windows PowerShell 5.1 unless asked
  for PowerShell 7+.

Notice what is left out: nothing here describes what Active Directory is or how PowerShell works. Claude already knows that. What earns a place in CLAUDE.md is the project-specific decision that Claude has no way to guess: which cmdlet family to use when two exist, where output belongs, and what boundary requires a human to say yes first.

Creating One

You do not have to start from a blank file. Run /init inside a session and Claude analyses the codebase itself, then writes a starting CLAUDE.md with the build commands, test instructions, and conventions it can discover on its own.

# Generate a starter CLAUDE.md from the current project
/init

Important: If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. Refine from there with the instructions Claude would not be able to discover on its own, like which subsystem requires manual approval before changes.

To review what is actually loaded in a given session, or to open a file for editing, run /memory. It lists every CLAUDE.md, CLAUDE.local.md, and rules file currently in effect, and links directly to the auto memory folder.

Keeping It Effective

CLAUDE.md content is loaded as part of every session’s context, so a bloated file has a real cost, not just a theoretical one. The general guidance is to stay under roughly 200 lines. Past that, instructions consume more context and adherence drops.

Symptom	Likely Cause	Fix
Claude ignores an instruction	The instruction is vague or contradicts another CLAUDE.md file	Rewrite it as a concrete, checkable rule and remove the conflicting instruction.
Instruction seems lost after a long session	It was only ever said in chat, not written to CLAUDE.md	Ask Claude to add it to CLAUDE.md directly, or edit the file yourself via `/memory`.
File keeps growing past 200 lines	Instructions that only apply to one part of the project are mixed in with universal ones	Move file-type or subsystem-specific rules into `.claude/rules/` with a `paths` filter instead.
An action needs to happen every single time, no exceptions	CLAUDE.md is context, not enforcement, so Claude can still decide differently	Use a hook instead. Hooks run as shell commands at fixed points and apply regardless of what Claude decides.

Final Thoughts

CLAUDE.md is not configuration in the strict sense, it is context that Claude reads and tries to follow, which is exactly why specific and checkable instructions work so much better than vague ones. Treat it as the onboarding document for a very capable but literal-minded new teammate.

Once your project conventions persist across sessions, the next question is how to package a repeatable multi-step workflow so it can be invoked by name instead of re-described every time.

Key takeaway: If you have typed the same correction into chat twice, it belongs in CLAUDE.md. Write it as a specific, checkable rule, keep the file under about 200 lines, and use a hook instead for anything that must happen without exception.

Next in this series

Next, we build a custom Skill: packaging a repeatable procedure so it runs on demand instead of being re-explained in the chat every time.