Project Instructions: CLAUDE.md and AGENTS.md
Teach an agent your codebase once. What to put in project instruction files, what to leave out, and templates you can copy.
Every coding agent session starts with amnesia. The agent doesn't know that your tests run with pnpm test:unit, that the legacy/ folder must never be touched, or that your team stopped using that state library a year ago. So it guesses, and you correct it, and tomorrow you correct it again.
A project instructions file fixes this. It's a plain markdown file in your repository that the agent reads automatically at the start of every session: an onboarding doc for a brilliant new teammate who forgets everything overnight. In this lesson you'll learn which file each tool reads, what belongs in it, what to leave out (that's where most files go wrong), and you'll get templates you can copy into your projects today.
What an instructions file does
When a session starts, the agent loads your instructions file into its context, the working memory of text the model can see while it works. Everything in that file shapes every decision the agent makes for the rest of the session.
That's powerful and also a responsibility. A short, accurate file makes the agent noticeably more consistent. A long, stale, or contradictory one makes it worse, because every line competes for the model's attention and wrong instructions get followed just as faithfully as right ones.
Think of it as the answer to one question: what would a capable engineer, new to this repo, get wrong in their first week? Write that down. Skip everything else.