Engineering best practice for AI agents

Intent

This pattern is a specialised implementation of guardrails, skills and workflow for agents, for AI coding agents that make design decisions. It assumes an organisation with its own view of good engineering, and embeds that view in the agent, whatever it looks like: your definition of best practice, gathered into a curated, cited base the agent consults. This enables three outcomes:

1. Agents are guided by your definition of best practice, rather than the model's taste.
2. Every design decision names its source, so a person can check it.
3. Agents push back on a suggestion with a source, so people weigh a reason rather than a preference.

Motivation

There is no single definition of best practice. Each organisation settles its own, shaped by its domain, its history and the risks it carries. A model knows none of this: its training holds a blur of engineering advice, good and bad, with no citations. Left to that, or to searching the web, an agent fails in three ways:

1. It applies someone else's standards. Its answers follow whatever the model absorbed, not what your organisation has decided.
2. Its answers can't be checked. Asked for the best design, it answers fluently, with nothing behind it to verify.
3. It agrees too readily. Sycophancy is a known behaviour of language models, so a wrong suggestion often goes unchallenged.

This pattern makes your definition explicit, and puts it where an agent can use it. Your organisation decides what goes in: its own standards and decisions and, where it chooses, authoritative third parties such as Martin Fowler, DORA's research or the OWASP Top Ten, distilled into short entries a person has read and vouches for. Agents then take each kind of question to its own source, and name that source in what they decide.

Applicability

Use this pattern when:

1. AI agents make design decisions, not just follow instructions, and those decisions should follow your organisation's idea of good practice.
2. The team wants agents to push back on a suggestion with a reason they can cite.
3. The team has standards, but nobody can say what they rest on, or agents apply them to cases they don't fit.

Do not use this pattern when:

1. Agents only make mechanical changes, such as renames or dependency bumps, with no design decisions in their hands. Guardrails and existing code are enough there.

Structure

Participants

Constraints and trade-offs

1. It guides the agent, but guarantees nothing. Language models are non-deterministic, so an agent can ignore an entry, or make something up and cite it with confidence. You still need enforced quality gates, and a human reviewing the result, as in human in the loop for AI coding agents.
2. Curation is reading work. A person writes or checks every entry, and the base is only as current as its last review.
3. It narrows the agent. A curated base can leave out good ideas the model would otherwise use, so agents should propose additions, with a source, for a person to vet.
4. It follows your view, even where wider practice disagrees. The agent raises the conflict, and your own standards win until a person decides otherwise.

Part of how I deliver

Where agents make design decisions, this is how I get them working to your idea of good engineering. It's one of many patterns I bring through contract delivery, and it builds on the standards your team already holds.

Related