Writing Your First CLAUDE.md: Teaching the AI Your Project's Rules
Updated: 2026-08-15 | Reading time: 5 min
If you find yourself typing the same instruction to an AI assistant for the third time — "use four spaces", "do not add extra libraries", "keep the comments short" — you are wasting effort that a single file could save.
What the file is
A CLAUDE.md file sits in your project folder. Claude Code reads it automatically and treats it as standing instructions. Write your project's rules once, and every later conversation already knows them.
Practitioners consistently report it as one of the highest-impact things you can set up — and it matters most in plan mode, because a plan can only respect constraints the tool has been told about.
Put the important rules at the top
Content near the top of the file carries the most weight, so lead with the rules you care about most. A student project rarely needs more than a page.
A starter template
Something like this is enough to begin with:
# Project: Student Marks Tracker
## Rules
- Python 3, standard library only unless I approve a package.
- Keep functions short; one job each.
- Explain any change in one sentence before writing it.
- Do not add error handling I have not asked for.
## Structure
- main.py — entry point
- students.py — loading and saving student records
- data/ — CSV files, never edited by hand
## How to run
python main.py
What to leave out
- Anything secret. No passwords, no API keys, no database credentials. Ever.
- Things the code already says. The file is for intent and rules, not a description of every function.
- Wishful thinking. Rules you do not actually follow just create confusion.
Why this is a teaching tool, not just a config file
Writing a good CLAUDE.md forces a student to articulate how their project is organised and what "good" means in it. Most beginners have never had to state that out loud. The students who write clear rule files tend to be the ones whose projects stay understandable a month later — with or without AI.