What belongs in the file next to your code

Ten days ago I added a file to a project containing the things I had been saying at the start of every session anyway. What the project is, how to run it, the conventions, what not to touch.

It is the least impressive change I have made this year and it has had more effect than anything since March. Since several people have asked what goes in one, here is the working version.

What earns a place

The commands. How to run it, test it, seed it, deploy it. Exact lines you can paste. This is the single highest value section and the one most people skip because they think it is obvious.

The conventions that are not visible from one file. Where new code goes. What the error handling looks like. Which of the three similar helpers is the one still in use. These are the things a newcomer gets wrong and a reviewer corrects three times a week.

The traps. Anything that has bitten you once. A migration that must run before another. A service that silently returns an empty list instead of an error. Each of these is one line and saves an hour.

What not to touch, and why. The why matters. Without it the rule gets reasoned away by anyone clever, human or otherwise.

What does not earn a place

Anything readable from the code in under a minute. The folder structure. The list of models. If it is derivable, do not duplicate it, because the copy will drift and the drift is worse than its absence.

Aspirations. "We write tests for everything" belongs in the file only if it is true. A rule the code visibly breaks teaches the reader that this file lies, and then the real rules go unread too.

History. Why it was built this way in 2022 is interesting and belongs somewhere else. This file is operational.

The test I apply

Could a competent contractor joining on Monday follow this without asking me anything?

That is the whole bar. It is also why the file is useful to the machine, which is the same test with a shorter attention span and no ability to ask.

The unexpected part

I now read my own file.

Before this, the procedure for deploying that project lived in my head and in the shape of my shell history. Writing it down so a machine could follow it meant writing it well enough that a person could, and the first person it saved was me, six weeks later, at an hour when I was not thinking clearly.

The habit that keeps it alive

When something goes wrong, the correction goes into the file, not into a one off instruction. If the fix landed on the wrong branch, the branch selection step was unclear, and it was unclear for people too.

Every one of those corrections has made the document better for humans. Not one has made it worse. That ratio is why I now treat this file as the most valuable non code artefact in any project I own.