Prompts for Coding: How to Brief an AI Coding Assistant

A useful coding prompt resembles a small engineering brief. It explains the behaviour you need, the constraints surrounding it, and the evidence that will make the result acceptable. It does not need elaborate role-play or a long list of adjectives describing an expert developer.

Suppose you want to replace custom card styles with utility classes. “Convert this to Tailwind and make it responsive” invites dozens of hidden decisions. A stronger request identifies the states, breakpoints, design tokens, and compatibility requirements before the assistant starts changing code. The difference is specification quality, not a secret prompting formula.

Describe outcomes before implementation details

Start with the observable outcome. Name the person using the feature, the action they take, and what they should see. For a pricing card, that might mean comparing plans, selecting a billing period, and activating a clear purchase link. Explain the relevant loading, disabled, or unavailable states if they exist.

Separate the outcome from your suggested implementation. “Use a shared component” is a technical preference; “all plan cards expose the same billing information” is a behavioural requirement. If the preference is mandatory, explain why. Otherwise, let the assistant propose an approach within the repository's established conventions.

Write acceptance criteria that someone else could check. “Looks professional” cannot settle a review disagreement. “At narrow widths, cards stack without horizontal overflow; keyboard focus remains visible on purchase links” is testable. Use the W3C accessibility tutorials to identify relevant interaction requirements rather than relying on vague requests to make everything accessible.

Keep the brief proportional. A small spacing correction does not need a full product specification. It does need enough context to prevent the assistant from solving a different problem or expanding the scope beyond the intended change.

Supply constraints that prevent expensive detours

Name the implementation boundaries: permitted files, framework conventions, supported browsers, and dependency policy. Include the current styling setup and whether the team allows arbitrary values. A request to use design tokens is ambiguous unless the assistant can find the actual token definitions.

Explain what must remain unchanged. Public component props, analytics hooks, translated text, and established test identifiers may be compatibility requirements even when they appear easy to tidy up. Ask the assistant to flag a conflict rather than silently dropping one constraint to satisfy another.

Use the AI coding assistants directory to choose an environment that supports your preferred review workflow. The prompt should remain useful across tools: a clear requirement is portable, while a long transcript dependent on one interface is not. For file selection and repository evidence, the codebase context guide provides a companion workflow.

Include a stop condition. Tell the assistant when it should ask a question instead of editing, such as missing token definitions or contradictory examples. This is more useful than demanding that it never make mistakes, which supplies no practical decision rule.

Provide examples with explicit limits

Examples reduce ambiguity when they demonstrate both allowed and disallowed results. Show the current component, one approved pattern, and a counterexample that should not be copied. Explain which aspect of each example matters: structure, naming, spacing, or interaction.

For style migration, use the CSS to Tailwind converter to create a first-pass mapping from a small, non-sensitive CSS snippet, then compare the output with your project's tokens and utility conventions. Do not treat conversion as proof of visual equivalence. Cascade order, inherited properties, custom breakpoints, and interactive states still need inspection.

Make representative states part of the prompt. A card with a short heading and no badge may fit perfectly while a translated heading and promotional label overflow. Include long content, narrow layouts, and keyboard focus where those states matter. The MDN CSS documentation helps resolve property behaviour when a generated utility mapping seems plausible but changes layout.

Avoid placing sensitive production examples in prompts. Synthetic names and realistic lengths usually preserve the important constraints. If an example is simplified, label the simplification so the assistant does not infer that missing validation or authorisation is intentionally unnecessary.

Ask for a small plan and a bounded patch

Use an output contract that separates understanding from implementation. Ask for assumptions, affected files, and a verification plan before requesting edits. This gives you a cheap opportunity to reject a mistaken approach before it becomes a large diff.

Goal: migrate PlanCard styling to existing Tailwind utilities.
Preserve props, copy, analytics attributes, and link semantics.
Use tokens from the attached theme; add no dependencies.
Cover narrow layouts, long headings, hover, and visible focus.
First list affected files, assumptions, and checks.
Ask if a required token is missing. Then make the smallest patch.
Report checks actually run separately from suggested manual checks.

This output contract makes review easier without prescribing every line. If the assistant returns a broader redesign, point to the violated boundary and request a revised plan. Do not keep appending instructions to a fundamentally incorrect implementation; return to the last clear agreement.

Check generated classes against the project's version and configuration. The Tailwind documentation is the authoritative reference for supported utilities and configuration concepts. A class that exists in a different setup may have no effect in yours, and a plausible name is not evidence that the build emits it.

Iterate from evidence rather than frustration

When a result fails, provide a specific discrepancy: the reproduction steps, expected behaviour, actual behaviour, and relevant output. “The badge overlaps the title at a narrow viewport with this text” is more actionable than “the layout is still broken”. Include a screenshot only when your tool and data policy support it.

Ask for a diagnosis before another patch if the previous change had no effect. The assistant may be editing an unused component, misunderstanding the build, or testing the wrong route. Repeated broad rewrites can hide the original issue beneath unrelated modifications.

Maintain independent verification. Run tests and inspect rendered behaviour, particularly when the assistant wrote both implementation and tests. Do not let a successful text transformation stand in for visual checks, accessibility checks, or route-level behaviour. The AI code review guide offers a useful final gate before merge.

After completion, improve the reusable brief rather than saving every conversational turn. Capture the missing constraint that caused trouble, the fixture that exposed it, and the check that prevented regression. Good prompting becomes a lightweight engineering practice: clear requirements, limited authority, and evidence that the result actually satisfies the task.

Key takeaways

• Define observable outcomes and acceptance criteria before asking for code.
• State architectural boundaries and explain what must not change.
• Label examples carefully and include awkward but realistic states.
• Request a small plan, explicit assumptions, and a bounded patch.
• Iterate using reproducible discrepancies and independently verified results.