Stop Repeating Yourself: Put Project Context in CLAUDE.md

As we saw in the insights report from last week, there are usually a few suggestions on how to improve our CLAUDE.md file. But if you never used a CLAUDE.md file that may not help you enough. In this post we take a close look at this helpful file and how we can use it to our advantage.

The two CLAUDE.md files

There are two places we can put a CLAUDE.md file and it is important to keep them apart.

The first location is in the project folder. Here the CLAUDE.md file goes into the top folder (next to the .git folder) and is only about this one project. In this file we put all the instructions that are specific to this project.

Inside the .claude folder for the user (C:\Users\USERNAME\.claude) we can create a CLAUDE.md file that Claude Code will read for all projects on this computer. Therefore, make sure that this global file only contains things that are true for every project you do. That is especially hard if you use different programming languages, technology stacks and project management methods. Should you have such a large variety of projects you may skip this file entirely and only focus on project specific CLAUDE.md files.

Keep it short

Claude Code will read the CLAUDE.md file in every session and keep it inside its working memory. Therefore, make sure that this file is to the point and does not waste important tokens.

Important: While CLAUDE.md will clutter your context, there is no guarantee that Claude will always follow it. If you depend on the run of certain steps, better put them into hooks.

Create the first CLAUDE.md file

When we run

/init

Claude Code will analyse our project and create a basic CLAUDE.md file for our project. How useful that is depends on how much code you have. If you have an empty folder, then skip that and try it with a project that has code.

For a minimal project I created in Visual Studio I ended up with this CLAUDE.md file:

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working 
with code in this repository.

## Project Overview

This is a C# .NET 10.0 console application used as a demo/learning 
environment. 

## Build & Run

 ```powershell 
dotnet build
dotnet run --project ConsoleApp1
 ``` 

Run a specific configuration:

 ```powershell 
dotnet run --project ConsoleApp1 --configuration Release
 ``` 

## Project Structure

 ``` 
ConsoleApp1/          ← solution root (git repo root)
├── ConsoleApp1/      ← C# project
│   ├── Program.cs    ← entry point
│   └── ConsoleApp1.csproj  (.NET 10.0, nullable enabled, implicit usings)
└── ConsoleApp1.slnx  ← Visual Studio solution file
 ``` 

## Key Settings

- Target framework: `net10.0`
- Nullable reference types: enabled
- Implicit usings: enabled

As we can see, there is not much useful content – because we lack anything specific that Claude could find.

If we have a large project with a lot of code, we can get something like this:

...
### Web Application (***.Web)

Uses **ASP.NET Core Areas** — one per domain role (`**`, `**`, `***`) — so 
controller and view organization mirrors the domain structure. Authentication 
is OpenID Connect with cookie-based sessions; authorization is claims-based.

### Data Access

Dapper is used throughout (no full ORM). Database migrations are manual SQL 
scripts under `db/Sripts/`, numbered sequentially (e.g., `0001_***.SQL`). The 
`***.Database` project handles initial schema setup; `***.Database.Seed` 
imports seed data from Navision/Business Central.

### Background Processing

`***.Processes` contains Hangfire job definitions. Jobs run in a separate 
`***.Hangfire.WindowsService` process (not in-process with the web app). 
`***.Hangfire.Dashboard` provides a monitoring UI.

### Service Registration Pattern

Each module exposes a `*ServiceCollection.cs` class that registers its 
services via `IServiceCollection` extension methods. The web app calls 
these from `Program.cs`/`Startup.cs`.

### Maintenance Utilities

Several standalone console apps handle operational tasks: 
`***.Maintenance.SizeReduction`, `***.Maintenance.Reminder`, 
`***.Maintenance.TemplateUpload`.

### Testing Layers

- **Unit tests** (`***.*.Tests`): NUnit 4, NSubstitute for mocking, 
 AwesomeAssertions for fluent assertions
- **Integration tests** (`***.*.Integration`): hit real infrastructure (DB, etc.)
- **Acceptance tests** (`***.AcceptanceTesting`): Reqnroll (BDD/Gherkin) 
 with Selenium, run with `bdd.runsettings` (6 parallel workers)
- **Shared test utilities** (`***.TestHelpers`): builders and factories 
 shared across test projects

### Code Generation

`***.Metaprogrammierung` is a utility project for code generation — consult 
it before writing repetitive boilerplate.
...

Here we have a much better example with clear insights that not only show us what this project is all about but also helps Claude Code to find its way.

Build on top of an existing CLAUDE.md

When you have a larger project and can use /init to generate a useful CLAUDE.md file, you can take it and copy it to your fresh project. Do not forget to modify it so that it matches the goal you have with this new project.

If you do not have a good starting point, go to GitHub and search for CLAUDE.md. When I tried that, I got over a million results. Filter for languages to better match what you are looking for. Just be aware that there will be so many files to choose from that it will be overwhelming.

Helpful resources

Here are a few helpful resources that you can use to write your own CLAUDE.md file:

Awesome Claude Code offers inside the resources folder a nice selection of templates for the CLAUDE.md file. It does not offer a template for every technology stack, but feel free to copy what you find useful.
HumanLayer wrote a helpful blog post that offers ideas on how to optimise your CLAUDE.md file.
Dometrain offers us a nice introduction with samples for .Net.
Bijit Ghosh wrote a great list of things to put into CLAUDE.md and what should stay outside.