Back to Articles A CLAUDE.md markdown file providing context to an AI coding assistant for better code generation.

How to Write a Better CLAUDE.md File for AI Coding

You ask your AI to add a login endpoint. It installs Ruby, creates files in random folders, and imports libraries you never asked for. Sound familiar? A well-written CLAUDE.md file, sometimes called a project markdown file or AI coding instructions file, prevents exactly this. These md files give the AI a roadmap of your entire project without you having to repeat yourself every time.

Most people have learned how important the project markdown file is. It gives the AI context on the overall picture of what you are wanting to create without you having to specify it repeatedly. I started playing around with the organization of mine after reading examples like this. But there is a piece of software engineering that this file can be used for that I think most people ignore.

Organization

We have all watched as our AI of choice puts methods wherever it wants, puts 16 classes into a single file, randomly creates folders when its heart desires, and suddenly tries to run a Ruby script inside of a C# project. CLAUDE.md, copilot-instructions.md, and other md files that AI tools support by default can be used to protect against this. I continue to refine my file layout and content but I wanted to share one that has been serving me very well in my current project.

Sections of the CLAUDE.md File

My markdown file has 8 sections:

  • The Introduction
  • The Repository Diagram
  • Build, Run, Test Command Table
  • Other Available Tools and Rules Surrounding Them
  • Code Architecture
  • Network Architecture
  • Key Conventions
  • Requirements

The Introduction

Section 1 is pretty standard, explain what you are building. This helps give the AI context on the purpose for the code. It doesn’t need to be long, for example:

This repository contains support code for a mobile app. The backend is an ASP.NET Core web app that serves the frontend and provides a few API endpoints. The frontend is a static site built with vanilla JavaScript, HTML, and CSS.

The Repository Diagram

Section 2 is one I haven’t seen much but has helped a lot. Layout the folder structure of your repo and give the AI context about what goes where. For example:

## Repository Diagram

| - `ExampleSite`
    | -- `.devcontainer`                      <- only used for local development
    | -- `.github`
          | -- `copilot-instructions.md`      <-- you are here
    | -- `src`                                <-- all actual code
          | -- `ExampleSite`
                | -- `Controllers`            <-- controller objects
                | -- `Models`                 <-- any object models needed
                | -- `wwwroot`                <-- static files for landing page

It doesn’t have to be complex. But it is an easy way to tell AI where your controllers, models, services, etc should all get stored

Build, Run, Test Command Table and Other Tools

I added sections 3 and 4 after an agent wanted to install Python and Ruby to run a simple CLI command. That kind of stuff easily adds landmines to code and can install unneeded or malicious packages. It would also sometimes generate miscellaneous build/test commands that were wrong. So just give it a table to explain what to do.


## Build, Run, and Test Commands

| Task | Command | 
|---|---|
| Restore/build the solution | `dotnet restore Example.sln` and `dotnet build Example.sln` |
| Run the app in development | `dotnet run --project src/ExampleSite/ExampleSite.csproj --launch-profile https` |
| Watch for changes and run | `dotnet watch run --project ExampleSite.sln` |
| Run tests | `dotnet test ExampleSite.sln` |

## Other Available Tools and Rules Surrounding Them
This repo and container only has dotnet SDK and runtime. No tools are available other than default linux tools and `dotnet` commands.

**Do Not**
- Install any additional tools
- Attempt to run other languages (python, node, ruby, docker, etc)

Code Architecture

Section 5 gives you the opportunity to explain in more detail how you want your code to be laid out. Are you using an observer pattern? MVC? Do you want all your data to pass through one orchestration layer? Does something need to be a singleton? All of that can be defined here and helps not only the AI, but also you think through your project.


## High-level code architecture

- This repository is a single ASP.NET Core `net10.0` web app in `src/ExampleSite`.
- `Program.cs` is the composition root. It registers MVC controllers, configures JWT bearer authentication, creates the configured files and directories on startup, enables static-file hosting, and falls back unmatched routes to `index.html`.
- Each controller handles a collection of operations on the same type of object
    - `exampleController` handles all of my example api requests
- Request/response models live in `Models/` and use data-annotation validation attributes rather than custom validators.
- The front end is a static site checked in under `src/ExampleSite/wwwroot/` (`index.html`, `test.css`, `test.js`), with ASP.NET Core serving the default file and SPA-style fallback.

Network Architecture

Section 6 may or may not be needed for you. I added it because I use dev containers locally and run my projects on servers I manage myself. This section allows me to specify any gotchas, network differences, and special considerations.


## High-level network architecture

- While developing locally, this app runs inside of a docker container using dev containers.
- When this app is deployed, it will run as a container in a kubernetes cluster. The app will be exposed publicly on the
internet, so it needs to be secure by default.

Key Conventions

Section 7 is the area to specify any other conventions. How do you manage secrets? Should every model/class be in its own file? Is your Dockerfile supporting local development as well as deployed code? All of these types of things can go here.


## Key conventions

- Any secrets needed will be injected via environment variables, and the app will fail to start if any required secrets are missing. There are no secrets in the code or config files, and no user input is used directly in any security-sensitive operations.
- The Dockerfile and `.devcontainer/devcontainer.json` are part of the runtime story, not just tooling: they create the 
needed files and directories and fixes ownership so the app can write there. If you run outside that environment, override those config values or create writable paths first.
- Controller routing uses `[Route("api/[controller]")]`.
- Each object/class created should be created in a separate file unless it is only used by one other object. It may then be placed in the same file

Requirements

Lastly, section 8 gives you the area to specify any technical requirements. What is / do you have a caching layer? How are you handling authentication? Any special validations that need to occur? All of these can be placed here and again, they not only give the AI context but also serve as a useful place to document the decisions you have made.


## Requirements

- the app will use redis to control rate limiting
- a rate limit entry consists of the requests unique ID and the IP address the request came from.

Final Thoughts

I have been really happy with this layout and while I have some more ideas of things to add, this has helped me immensely in my projects and, while not perfect, has greatly cut down on the clutter AI produces. I hope it serves you as well.

Try this template on your next project. Copy the sections above, fill in your own details, and watch your AI’s output get cleaner. For more on balancing AI speed with code quality, read about the hidden costs of vibe coding and how to use AI without becoming dependent on it.