Intent Is More Important Than the Prompt

Prompting an AI coding agent can feel like giving instructions to a very fast developer.

That comparison is useful, but incomplete.

A human developer usually operates inside a large body of shared context: architecture discussions, team habits, security expectations, previous incidents and an instinct for what must not be broken even when the ticket forgets to mention it.

An agent often sees a far thinner slice — a gap where all that unspoken context ought to be.

This creates a particular risk. The agent may comply with the literal instruction while cheerfully undermining its purpose.

Suppose a repository contains a file that must remain human-written because it acts as an architectural gatepost. The file explains the boundaries of the system and provides a stable statement of intent.

A prompt says, “Do not modify this file.”

That seems clear. It is not.

Later, another task asks the agent to update documentation across the repository. The agent notices that the protected file is now inconsistent, and reasons — quite sensibly — that fixing it is necessary to do the job properly.

The words were understood. The intent was quietly trampled.

This is not defiance. It is local optimisation. The agent is trying to satisfy the immediate request using the context directly in front of it.

Humans do this too. We bypass a control because this particular case is exceptional, urgent or obviously safe. (It is remarkable how often a case turns out to be obviously safe.) The difference is speed and scale. An agent can make thousands of locally reasonable decisions without carrying the institutional memory behind each boundary.

That is why important controls cannot live only in prompts.

Prompts are guidance. Systems provide enforcement.

If a file must not be changed, repository permissions, CI checks or required review should protect it. If an architectural condition must hold, the build or pull-request process should test for it wherever possible.

Not every intention can be encoded mechanically. Some principles are stubbornly qualitative: keep the design simple, preserve human accountability, do not hide operational complexity.

For these, explanation matters.

Instead of writing:

“Do not add a second event-processing path.”

Write:

“This system relies on one auditable event-processing path so that retries, monitoring and operational ownership remain consistent. A second path would create invisible behavioural divergence. Do not add one without explicit architectural approval.”

The second version gives the rule a reason. It helps the agent recognise equivalent violations, not merely the exact forbidden action.

Intent also improves human decisions. Rules without reasons decay into cargo cults. People either follow them mechanically or bin them the moment they become inconvenient.

A well-explained boundary can adapt.

There is another side to this. Long instruction files can create the comforting illusion of governance. We bolt on more text after every mistake until the poor agent is wading through rules, exceptions and reminders like a solicitor reading the small print aloud.

Eventually the guidance grows too large to interpret reliably. Contradictions creep in. Old rules outlive the architecture they described. Genuinely important principles get lost somewhere between the formatting preferences.

The answer is not maximum instruction. It is hierarchy.

A small number of durable intentions should sit at the top:

• protect customer data;
• preserve auditability;
• keep operational ownership clear;
• prefer simple, reversible changes;
• use technology to support human judgement rather than obscure it.

Specific rules can then explain how those intentions apply in the current system.

We should also ask agents to reflect explicitly:

• Which architectural principles are relevant?
• What assumptions does this change make?
• What could this instruction unintentionally bypass?
• Is there a safer or simpler way?

These questions do not guarantee alignment. But they widen the frame beyond mere task completion.

The central lesson is straightforward:

The prompt describes what to do. Intent explains what must remain true.

Reliable AI-assisted engineering needs both.

• #ai
• #software-engineering
• #governance

@online{byatt2026-intentismoreimportantthantheprompt,
  author  = {Stephen Byatt},
  title   = {Intent Is More Important Than the Prompt},
  year    = {2026},
  date    = {2026-05-25},
  url     = {https://learningoutloud.stephenbyatt.com/blog/intent-is-more-important-than-the-prompt/},
  urldate = {2026-05-25},
  note    = {Learning Out Loud}
}