Show, don't tell: examples and roles

Some things are far easier to show than to describe. Try writing instructions precise enough to reproduce your team's commit message style — the capitalisation, how long the first line runs, whether the body explains what or why — and you'll end up with a paragraph that still misses. One real example carries all of it at once.

Here's a commit message in our house style:

  Stop the nightly export retrying forever

  The retry loop had no ceiling, so a malformed row kept it
  running until the next run overlapped it.

Write one in the same style for: fixed a crash when the
uploaded CSV has no header row.

This is worth reaching for whenever the thing you want is a pattern — a tone, a structure, a level of detail. Give one example, not six: a single clear case sets the pattern, while a pile of them tends to get averaged, and any accidental feature they happen to share gets copied along with the ones you meant.

Roles are the same idea aimed at judgement. "You are a skeptical editor" is useful because a skeptical editor disagrees with you — it changes which things get flagged. "You are a world-class expert" changes vocabulary and confidence, not judgement, so the answer sounds more authoritative while containing the same content. If you can't say what the role would push back on, it isn't doing anything.

The useful test is to name the viewpoint and the audience: "Answer as a patient tutor explaining to someone who has never programmed" tells Claude both where the advice comes from and who has to understand it.

Loading your workspace…