Treat prompts like specifications, not chat messages

Most prompts sent to AI coding assistants look like chat messages: one run-on sentence that mixes two tasks, a constraint and an implicit expectation. “Fix the login issue and make Google login work and don’t break anything.”

A senior engineer handed that sentence would ask a dozen questions before starting. An AI assistant usually does not ask. It guesses — and the quality of what comes back depends heavily on how much it had to guess.

A prompt is a specification

The fix is to treat a prompt as what it really is: a small specification. The structure that works for engineering tickets works for prompts too:

• Objective — the outcome in one sentence.
• Requirements — each distinct thing that must be true, as a separate item.
• Constraints — what must not change, which libraries or patterns to use or avoid.
• Context — only the files and facts relevant to the task, not the whole repository.
• Edge cases and tests — what could go wrong, and how success will be verified.
• Acceptance criteria and output format — what “done” looks like and what shape the answer should take.

Not every task needs every section. A one-line rename does not need acceptance criteria. But a bug fix that touches authentication does, and writing them down is how you notice the requirement you forgot.

Preserve every requirement

When you restructure or shorten a prompt — by hand or with a tool — the most important property is that nothing the author asked for disappears. Rewriting for clarity is valuable; silently dropping “and don’t break the existing session handling” is not. Any prompt-optimisation step should be able to show, requirement by requirement, that the original intent survived.

Spend tokens on signal

Tokens cost money and attention. Long prompts are not better prompts; prompts full of the right context are. Remove filler, duplicated instructions and irrelevant files. Keep the constraints and the acceptance criteria — those are the tokens that change the outcome.

Check the prompt before it leaves

A prompt is also data leaving your machine. Developers paste stack traces with connection strings, configuration files with API keys, and logs with customer email addresses. Before a prompt is sent, it is worth checking automatically for:

• secrets and credentials,
• personal data,
• prompt-injection patterns copied in from untrusted sources (for example, instructions hidden in a web page or a document).

These checks are deterministic. They do not need a model, so they can run locally in the editor or browser without uploading anything.

Close the loop

The specification is useful twice: once to instruct the model, and again to review its output. When the change comes back, the same acceptance criteria become a review checklist. You can go further and generate a review prompt from the modified files and the original specification, so a second pass checks the change against what was actually asked.

The takeaway

AI assistants have made writing code faster. They have not removed the need to say clearly what the code should do. Teams that write prompts as specifications — structured, minimal, checked and reviewable — get more predictable results from the same models, and leak less data doing it.