A Good Prompt Is Not a Good Specification
AI-assisted development talks a lot about prompts. I care about what we're building, by which rules, and how we'll know it's right. Brief, architecture, acceptance criteria, tests and production checks.

In AI-assisted development there is an enormous amount of talk about prompts. How to write one, how much context to add, which phrases work, which model is better. I understand why: the prompt is what you can see and what you can change in a second.
With every project, though, I'm more interested in something else. What are we actually building. Why. Which rules apply. What must not break. How we'll know the result is right. If I can't answer those questions, a better prompt doesn't help me. I just get a faster route to the wrong thing.
A good prompt is not a good specification. That seems to me one of the more important things I've learned working with AI, so I'll try to explain it through how I work myself.
A prompt solves the moment, a specification solves the project
A prompt is an instruction for one task. A specification is a description of what the system has to do, even when nobody has the task in their head anymore. A prompt disappears into the conversation history. A specification stays, and anyone can read it, including the tool that will be working on the same project next week.
When I write a prompt without a specification, I decide over and over about things that should have been decided once. Which library. How we name things. Where the permissions are. What happens with an error. The tool decides its own way in every conversation, and after a few weeks I have a project in which every part is written to different rules.
The brief: what and for whom, before how
Every piece of work with me starts with a brief. It isn't long. It says which problem we're solving, for whom, what the result has to enable and what it must not break. If I can't write that in a few paragraphs, I don't understand the problem well enough to hand it to anyone, human or tool.
In the brief, I'm most interested in the constraints. Existing project or new? Which technologies are already in use? Who will maintain it? Does the change affect login, data, payments? Production or an experiment? Nobody will tell the tool these things unless I write them down. And without them the solution will be perfectly sensible for the wrong world.
Architecture: rules I don't repeat in every conversation
Every project has a few decisions that determine everything else. Where the logic lives. How data is read and written. How output is escaped. How permissions are checked. How things get deployed.
I write these decisions down once and give them to the tool every time. Not as a prompt, but as a document that's part of the project. In my projects that document takes the form of instructions for agents, a file every tool reads before touching the code. It says what the architecture is, what the security boundaries are, what must not be changed without a plan, and how the result is verified.
The difference is noticeable immediately. A tool that knows the rules suggests solutions that fit. A tool without rules suggests solutions that are good on their own and foreign to the project.
Acceptance criteria: how I know it's done
Most of the mistakes I've made working with AI happened when I didn't say in advance what "done" means. The tool then simply picked the moment when it was satisfied, and that moment was usually too early.
Now I try to write a few concrete criteria for every task. On invalid input, the user sees an error and keeps the data they entered. A draft is not publicly accessible in any way, not even through RSS or the sitemap. The page doesn't scroll horizontally at 320 pixels wide. These are sentences that can be checked. "Improve the user experience" is not.
Criteria have another benefit: they give the tool something to hold on to when it meets ambiguity. Instead of guessing what I meant, it checks whether the solution satisfies the rule.
It also helps to separate criteria by what happens if they aren't met. Some are a condition for release: if a draft leaks to the public, the feature doesn't go to production, full stop. Others are a wish that can be fulfilled later. A tool that knows this difference won't spend an hour on a cosmetic edge case while the main thing doesn't work. And I won't be reviewing fifty changes to find the one that matters.
Documentation: a description of the state, not the intention
Project documentation matters more when working with AI, not less. The tool has no memory between conversations; everything it knows about the project it has to read. If the documentation describes the state from three months ago, it will be working for a project that no longer exists.
So after every major change I update what changed: what exists, what's on production, what's open. Not because I like documents, but because it's the only way the next conversation starts from the truth.
This blog is built the same way. Every change has a record of what was done, what was verified and what wasn't yet. When the record is missing, it shows at the very next step.
Tests and verification: a proposal is not a result
A tool that writes code also likes to write a report saying everything works. That report isn't proof. Proof is tests that check what I'm worried about, and a manual look at the actual screen.
With tests, I'm not interested in the number but in the question of what could break. If a test merely repeats the assumption from the code, the two agree and both miss it. So the acceptance criteria from the previous section become tests: the same sentences, only executable.
Checking on production is its own step. Something that works locally tells me a lot, but not how it behaves with different permissions, settings and data. Every release gets a list of URLs and actions I check afterwards. It's tedious, and so far it has found more problems than any prompt.
Why a better model isn't the answer
I hear the argument that the next model will understand vague instructions too. That's partly true: models keep getting better at guessing what I meant. But guessing remains guessing. If I don't know myself whether a payment error should return the user to the form or to the start, no model knows either. It can only pick one option and execute it very well.
A vague specification isn't fixed by a more capable tool. It's fixed by my making the decision and writing it down. A better model then helps me carry it out faster and better. That's the right order.
What this looks like for me in practice
For a new feature, I first write what it has to enable and for whom. Then I check whether the project's existing rules cover what will need to change, and add what's missing. I write the acceptance criteria. Only then do I write the prompt, which refers to all of that and is therefore short.
I review the result against the criteria, not against a feeling. Tests check what could break. The release gets its own checklist. The documentation is updated. The next conversation starts from what's true.
This isn't a faster process for one task. It's a faster process for a project that lasts more than a day. In the projects I maintain myself, it has paid off every time so far.
The same task, two beginnings
Let me try to show the difference on a hypothetical task that's ordinary enough: a contact form for a website.
The first beginning is a prompt: "Make a contact form with name, e-mail and message that e-mails the owner." The tool builds it in a minute. The form looks fine. Then it turns out it isn't protected against automated submissions, that it wipes the entered text on an error, that it sends e-mail from an address the server isn't allowed to use, that it doesn't store the message if sending fails, and that on a phone it shows a text keyboard instead of an e-mail one. None of that is the tool's fault. I hadn't said any of it.
The second beginning is a short brief and a few criteria. The form is for visitors without an account, without cookies, on an existing site with these rules for output and validation. The message is stored before any e-mail is attempted. On an error the user sees an understandable message and keeps their input. Bot protection without external services. A limit on messages per hour. The right keyboard on a phone. We verify with an automated test and by hand on the real server.
The prompt that follows this brief is shorter than the brief. And the result is a form I can publish. The difference isn't the model; the same model worked both times. The difference is that in the second case I made the decisions before handing them to the tool.
This example isn't invented for the article; the form on this site came about the second way, with the project's rules and criteria, and some of the rules listed came precisely from asking what could break. The first way, the reader would have discovered them.
The prompt is the last step, not the first
If I had to condense this: the prompt is the last thing I write, not the first. Before it comes up, the things the tool can't decide for me are decided. What we're building, why, by which rules, and how we'll know it's right.
When that's clear, the prompt is simple and the result is good. When it isn't, no prompt helps. The tool will very quickly turn a vague instruction into the wrong thing, and do it with complete confidence. Speed isn't an advantage there.