This video is about writing the project's instruction file, CLAUDE.md. Project instruction files keep instructions available across sessions. We'll choose useful instructions, record the project's check commands, and edit an instruction file to keep it focused. Finally, we'll see why a rule written in that file is only a request.
The project's root instruction file is loaded when you start Claude Code there. Ancestor instruction files also load at startup, while files in subdirectories load as needed. These are instructions available across tasks. Other agents read the same kind of file under another name. Codex, for example, reads AGENTS dot M-D. If you ran "slash init", as we did in a previous video, you already have a first draft of your Claude dot M-D file. This video is about what belongs in it.
A common first instruction is "Make sure everything works". That line isn't very good. It leaves the agent to guess which checks this project uses, and when to run them.
Replace it with the exact commands, and say when to run them. Here, that is before reporting a task as done. This example is a Python project configured with three tools. It runs "pytest" for the tests, "mypy dash dash strict dot" for type checking, and "ruff check dot" for linting.
Include commands to avoid, repository conventions and useful file locations. A line earns its place when it records a project fact the agent would otherwise have to guess or ask about again in another session.
A rule in the instruction file is a request, not an enforced setting. The harness loads it as text in the context window, next to the task, the files the agent read, the tool output and its own replies. All of that competes for the model's attention.
The model interprets the instruction alongside the rest of the context. That makes it a fuzzy tool, one whose handling of the same instruction can vary from one session to the next. It can follow the rule, but it can also overlook or misapply it. A written instruction alone does not enforce the action.
So when the agent reports that the checks pass, look for the run itself. The session shows each command the agent ran, followed by its output.
So a rule that must hold cannot live only in the instruction file. Hooks take care of that. A hook is code the harness runs at set points, such as after every edit, so the check runs whether or not the model remembers the rule. We will build hooks in upcoming videos.
Instruction files grow as people add rules, and every line uses context in every session. Claude Code's guidance warns that long instruction files reduce adherence. Here is an example instruction file for this project, after a few additions.
Two lines ask for clean, readable code. They repeat each other, and a generic request like that tells the agent nothing about this project, so both go. The test command is stale. The project moved to pytest, and an old command in the instruction file sends the agent to the wrong tool. Correct it.
Two lines stay. Each build overwrites the generated folder, so edits there are lost. And where the tests live is this project's choice, which the agent cannot guess. A mistake you have actually observed is a good reason to add or clarify a rule. Also record known project constraints before they cause trouble, and review the file periodically for stale or repeated instructions.
The instruction file is worth writing and keeping focused. Record the exact check commands and when to run them, and check the session to see that they ran. It is still a request addressed to a model. A rule that must hold needs a hook, which runs the check on its own.
Reusable checks reduce what you must verify by hand after each change. The tests you keep go on checking earlier requirements while the project grows. That's it for writing instruction files. See you in the next video.