You'll keep seeing files ending in .md. README.md. CLAUDE.md. AGENTS.md. They look like something for programmers and they aren't. A .md file is the single most useful thing a non-technical person can learn about here, and it takes four minutes.
What it actually is
A .md file is a plain text file with a few simple formatting marks. That's the entire definition. The md stands for Markdown.
You write # Heading and it's a heading. You write **bold** and it's bold. You write a dash at the start of a line and it's a bullet. Nothing else to learn, and you can ignore the rest of the marks forever.
You can make one in any text editor. Save the file with .md on the end instead of .txt and it's done.
Why not a Word doc or a Google Doc
Because those files are stuffed with invisible junk. Fonts, spacing rules, revision history, formatting objects. A human sees a clean page and a machine sees a mess wrapped around a small amount of text.
A .md file is only the words and the shape of the words. Nothing to strip out and nothing to misread. That's why every AI tool reads and writes them by default, and it's why so much runs on them underneath, quietly.
There's a second reason that matters more once you're building. A .md file lives inside your project folder, right next to what's being built, which a Google Doc never does. It travels with the work.
The formatting, all of it
# A big heading
## A smaller heading
Just type for a normal paragraph.
**bold** and *italic*
- a bullet
- another bullet
1. a numbered thing
2. another one
[a link](https://christiloucks.com)
> an indented quote
`a bit of code or a file name`That's genuinely it. You now know Markdown.
Now the part that matters for building
CLAUDE.md
When you're building something with Claude Code, it looks for a file called CLAUDE.md in your project folder and reads it before it does anything, every single time.
That means anything you put in there is a standing instruction. Not something you repeat in every conversation, and not something it forgets when the chat gets long. It's the sheet you leave for the substitute teacher, except the substitute actually reads it.
(Some tools look for AGENTS.md instead, and some read both. Same idea, different filename.)
What to put in it
# This project
What this is: [one sentence, plainly]
Who uses it: [the actual person, in the actual moment]
# How to work on this
Ask me before making a decision that would be annoying to undo.
When you finish something, tell me how to check it myself.
Keep it small. If something is getting complicated, say so and stop.
Don't add features I didn't ask for.
# Never
Never delete anything without asking.
Never put real client information anywhere in this project.
Never [what would make you cry].
# Rules I keep forgetting to repeat
[Every time you correct the same thing twice, it goes here.]That last section is the trick. The second time you correct the same behavior, stop correcting and write it down. Your CLAUDE.md should get longer every week for a while and then settle.
Why this is what separates people
Someone using AI without one of these is re-explaining their situation constantly, getting slightly different results every time, and slowly concluding the tool is unreliable.
Someone with a good one has a tool that already knows the rules and gets more useful the longer they use it, because every irritation turns into a line and never happens again.
Same tool. The only difference is a text file with a few dashes in it.
Try it in the next ten minutes
- Open any text editor. TextEdit is fine, but switch it to plain text first.
- Type a heading with a
#and a couple of lines under it. - Save it as
notes.mdsomewhere you'll find it. - Open it again. That's a .md file, you made one, and it's the same kind of file that runs every project you'll ever build.
Related: Set Up Claude So It Already Knows You does the same job for chat rather than for building.