The Shape of a Useful Engineering Prompt

A useful prompt is not necessarily long. It is shaped so that the agent can distinguish the desired outcome from the tempting shortcuts.

Prompts for engineering work are closer to small project briefs than magic phrases. They describe a reality, a destination, and the boundaries that matter. The agent still needs to inspect the repository and reason about the implementation; the prompt makes that reasoning accountable.

Describe the system as it exists: relevant files, conventions, users, deployment constraints, and the reason the change matters. Context should reduce discovery cost without prescribing code that has not yet been inspected.

Point to authoritative local sources rather than pasting everything into the request. “Read the root contribution guide and the existing post component” is usually better than duplicating rules that may drift. If the agent discovers a contradiction, ask it to surface the conflict instead of guessing which copy is current.

State what should be true when the work is complete. “Add search” leaves important questions unanswered. “Create keyboard-friendly static search that does not load the index on article pages” establishes a result that can be tested.

Describe observable behavior before choosing implementation details. This preserves room for a better solution while making it harder to satisfy the request with a shallow approximation.

Constraints are where product judgment becomes executable. They can cover accessibility, privacy, compatibility, dependency limits, or behavior that must not change.

Too many constraints can conflict or obscure the goal. Prioritize them. If accessibility outranks animation and maintainability outranks novelty, say so. The agent then has a decision rule when every preference cannot be maximized at once.

A compact prompt might look like this:

Inspect the current article layout and image pipeline.
Add a responsive primary image to every normal post.
Preserve Markdown authoring and static output.
Require meaningful alt text and prevent layout shift.
Prove the change with content validation, a production build, and a mobile check.
Document any authoring convention that changes.

Ask for the proof appropriate to the risk: a focused test, a production build, a screenshot, a trace, or a concise explanation of an unresolved limitation.^[1]

“Run the tests” is not enough when the existing tests do not cover the requested behavior. Ask the agent to identify what each check proves and where manual review remains necessary. A green suite is useful evidence only when its scope matches the claim.

The practical pattern is context → outcome → constraints → evidence. It gives an agent room to reason while making the finished work easier for a human to evaluate.

When an agent repeatedly makes the same wrong assumption, improve more than the next prompt. Put the durable rule in repository guidance, validation, or a test. The prompt should carry task-specific intent; the repository should carry the rules that every task needs.

This is the same principle used in healthy engineering systems: turn recurring review feedback into a guardrail close to the work. Better prompts help one task. Better project context helps the next hundred.

• Web Content Accessibility Guidelines 2.2
• Eleventy documentation