The File I Write Before Claude Code Writes Code

Before Claude Code writes a line of code for any of my products, I write one file by hand. I call it the intent file. It holds four things: who the change is for, what the product must never do, what done looks like in something I can actually look at, and which decisions are already closed so nothing gets reopened. Writing it takes about fifteen minutes. It is the highest leverage fifteen minutes in my week, because an agent that produces code faster than I can read it needs its constraints before it starts, not my corrections after.

I ship seven SaaS products solo with an AI-native workflow. Arvuyot Yashir issues digital rental guarantees, so every change there touches money and a legal document. Brainers Club carries more than 10,000 paying members. The Next Level is a white-label fork of that same community platform. Luma.ai turns text and images into video for more than 10,000 subscribers. None of those is a good place to discover in production how an agent chose to read a sentence I wrote at midnight.

What actually goes in the file

Four sections, never more. The reader is the agent, and a long file gets skimmed exactly the way a long brief gets skimmed by a junior developer.

• Audience: one sentence on who touches this screen or endpoint, and in which language. On a Hebrew-first product that single line removes a whole family of layout and copy bugs before they exist.
• Forbidden: the things that must not happen, written as events rather than values. No new write path to the guarantees table without an audit row. No change to the billing webhook signature check. No English fallback string reaching a Hebrew user.
• Done: what I will look at to believe it works. A specific URL, a specific record, a specific log line. Not the phrase 'tests pass'.
• Settled: decisions that are already made and are not waiting for a better idea. Which auth library, which table owns the truth, how currency rounding works.
• Open: the one or two things I genuinely have not decided, marked as questions for me and not as something the agent closes on its own.

The forbidden list is the part that pays

Goals are the cheap thing to write. Every product brief is made of goals. The expensive knowledge is the negative space: the twelve places that break quietly if you approach them the obvious way. That knowledge normally sits in a senior engineer's head and gets applied in code review, one comment at a time. Once code arrives in volume, review is too late and too slow to be the only place it gets applied.

So I move it earlier. On Arvuyot Yashir the forbidden section says the guarantee document is generated once and never regenerated in place. An agent reading only the code would see a clean refactor: generate on read, drop the stored file, less state to manage. It would be right about the code and wrong about the product, because a landlord who already has a PDF in his inbox has to keep holding the exact document we issued. That is one sentence in a file. It is also the difference between a refactor and an incident.

It is what makes several agents at once survivable

I stopped handing out one task at a time a long while ago. Several agents work in separate worktrees on the same repo while I read diffs. What holds that together is not a better prompt per agent, it is one shared file they all start from. Without it, three agents invent three slightly different ideas of what the feature is, and merging those ideas becomes my job.

With it, disagreement shows up as code that contradicts a line I can point at. I do not argue with an agent about taste. I quote the file, it fixes the diff, and the review is about correctness instead of my preferences.

What I tell my students to do with it

I am a tech mentor at nCode, Israel's largest coding academy, and more than 600 students have come through. Almost all of them start by trying to get better at prompting. The ones who actually ship stop tuning prompts and start writing down constraints. A prompt is a sentence you throw away. The intent file is an asset that makes the next twenty prompts land, and it is the one artifact in my setup that has to come from a human, because it encodes what the business can afford to lose.

If you want the smallest possible version, do this today: open a file, write three lines under a heading that says must never happen, and point your agent at it before the next task. You will know within a day whether those three lines were the right ones, because the agent will try to break one of them.