Prompt conventions: coding standards for the AI era

Your team has a linter config, a branch naming scheme, a review checklist and a definition of done. And then every developer prompts coding agents however they feel like that morning, with whatever context they remember to paste, toward whatever finish line they privately imagine. Free-form prompting produces free-form quality, and most of the variance teams blame on the tools comes from exactly this.

The fix is the same one engineering applied to every previous source of variance: team AI coding conventions, written down, versioned in the repository, enforced the way coding standards are. Nobody argues about tabs versus spaces anymore because the linter settled it. How an agent task gets framed deserves the same treatment.

Free-form prompting produces free-form quality

Give the same ticket to two developers with the same agent and the same model, and you can get a clean tested diff from one and a plausible mess from the other. The model did not change between sessions. What changed is how the task was framed, what context the agent received, and what verification the developer demanded before calling it done.

When output quality varies this much across a team, the instinct is to blame the tool, or the person. In our experience the real culprit is the absence of a standard. Individual prompting skill is real, but it is procedure, and procedure that lives in one person’s habits is variance waiting to happen for everyone else.

What team AI coding conventions cover

The useful conventions are not a library of magic prompts. They standardize four decisions every delegated task involves.

Task framing: a delegated task states its goal, its boundaries (which files, which layers, what is out of scope) and its definition of done, including which tests must pass. If the task cannot be written this way, it is not ready to delegate.

Context: what always accompanies a task in this codebase. The module involved, the interfaces it must respect, the conventions file. Also what stays out, because context discipline is part of the standard: dumping the whole repository into a session is the prompting equivalent of a thousand-line function.

Verification: what must be true before agent output reaches a pull request. Tests run locally, lint passes, and the developer who delegated has read the diff line by line. The convention makes explicit that delegation transfers work, never accountability.

Escalation: when to stop. Two failed iterations on the same task means the task was underspecified, and the fix is rewriting the task, not prompting louder.

Version them like linter rules

Conventions that live in a wiki die in a wiki. Put them in the repository, keep them to a page, change them through pull requests, give them an owner. The parallel with linter rules is exact: a proposed change gets discussed once, in review, and then the argument is over for everyone.

The repo location also matters because conventions feed the machinery. The always-true parts belong in the context files your agents read before touching code. The task-specific procedures belong in agent skills. The conventions document is the human-facing layer above both: it tells developers how to frame and verify, while context files and skills tell the agent what the team already decided.

Write the first version from evidence, not theory

Do not convene a working group to imagine ideal prompting. Your best agent sessions already happened. Pull the transcripts from your two or three strongest users, extract what they consistently do (how they scope, what they attach, what they check) and write that down. One page. Revise it monthly for the first quarter, then quarterly.

Two anti-patterns to avoid. The fifteen-page prompting guide, which nobody reads and which mistakes volume for rigor. And the total ban on free-form work: exploration should stay free, because chatting with an agent to understand a problem is thinking, not delivery. The conventions apply at the moment work is delegated, which is precisely the jump from chatting with AI to handing it complete tasks where unmanaged variance gets expensive.

A team that frames tasks the same way reviews faster, onboards faster and can finally compare results, because the inputs stopped being random. Writing these conventions with the pilot squad, from their own transcripts, is one of the first deliverables in our agentic engineering engagements, and it is usually the cheapest one relative to what it changes.